Build agents over MCP

​

Backend-enforced guarantees

• create_agent always creates a draft, and update_agent writes a draft while preserving any retained published version.
• publish_agent validates the complete saved graph and publishes only the exact current revision/version. The authoring tool family exposes no archive or delete operation. test_agent runs the guarded current draft; run_agent is a separate capability that resolves only a retained published version.
• Every call re-checks the connected user’s live workspace, team, and agent permissions. Advanced API keys use their creator’s live permissions.
• update_agent and publish_agent require an opaque revision, and the backend atomically rejects stale revisions before mutation. The client handles that result by re-reading and reconciling; it cannot bypass the check by retrying.
• validate_agent never mutates, publishes, or executes the draft.
• Skill package validation never saves or executes code. Skill creation is draft-only, full-package updates require expectedVersion, and publication re-validates the current package.
• User-authored Skill actions run only through the isolated E2B action runtime. Declaring sideEffects: "none" disables action-runtime network access, but does not make workspace-authored code trusted or bypass write confirmation.

​

Authorize agent building

​

Advanced API-key setup

​

Access model

• get_agent can read only an agent the connection owner can normally see.
• create_agent must target an accessible team in the connection owner’s workspace.
• update_agent, validate_agent, and publish_agent require the connection owner’s normal edit permission for the target agent. Publishing also re-checks visibility of its current home team when one is assigned.

​

Tools

​

Argument and response summary

• get_agent_node_catalog accepts optional nodeType, builderSection, and includeFieldDetails filters. Set includeActionTypes to true to include valid action types and optionally set maxActionTypes from 10 to 500 (default 120). Its versioned, builder-visible response is the source of truth; hidden/internal nodes, event triggers, raw HTTP categories, and unsafe action names are filtered out.
• get_agent_builder_guide takes no arguments and returns versioned builder guidance, including the external tool-policy and baseline-tool rules below.
• get_agent takes agentId and an optional positive integer version. It returns { "agent": { ... }, "builderUrl": "..." }; agent.revision is the current opaque write token. An explicit historical version also adds top-level selectedVersion, while agent.currentVersion still identifies the actual current graph version.
• create_agent requires teamId, name, nodes, and edges. Optional metadata includes description, category, tags, difficulty, estimatedTime, and behaviorType (interactive or pipeline). The new agent is shared with the selected team, and its response includes the first opaque revision.
• update_agent requires agentId, the latest opaque revision, and at least one metadata or graph change. version is an optional additional guard against editing a different current graph version. It does not move an agent to another team. Never decode, synthesize, or reuse an old revision.
• validate_agent can validate a saved draft by agentId, or validate proposed name, behaviorType, nodes, and edges before creation. Optional proposed fields overlay the saved graph when agentId is present. Its response includes agentId, version, valid, and structured diagnostics with severity, code, message, and relevant graph paths or IDs.
• publish_agent requires agentId and the latest opaque revision; pass currentVersion as optional version for a second guard. It returns the published authoring state plus published: true and alreadyPublished. A current already-published version is a validated no-op. If a response is lost, call get_agent: matching status: "published", currentVersion, and publishedVersion confirms success; otherwise do not retry with the stale pre-publish revision.
• A canonical Skill package is { "version": 1, "entryPath": "SKILL.md", "files": [...], "actions": [...] }. Every action points to an included file and declares runtime: "e2b", language, and sideEffects (none or external).
• validate_agent_skill and create_agent_skill accept the complete object as either package or packageJson. Create also requires a display name and always returns a draft.
• get_agent_skill returns the complete package as skill.packageJson. Send that complete package to update_agent_skill with the latest skill.currentVersion as expectedVersion; do not send only changed files.
• publish_agent_skill accepts skillId and the latest expectedVersion. A stale version returns skill_version_conflict; re-read and reconcile instead of overwriting newer work.

​

Recommended flow

1. Call get_agent_builder_guide once at the start of the build.
2. Call get_agent_node_catalog and choose only node types and fields present in the returned live catalog.
3. Construct the complete directed graph and call create_agent with the target teamId.
4. Keep the returned agent ID, opaque revision, currentVersion, and builderUrl.
5. Call validate_agent. The backend requires the complete proposed definition to pass validation. If an existing agent has unrelated pre-existing errors, stop before writing and ask whether the user wants to expand the change to repair them.
6. Use get_agent to re-read the persisted draft. For every update, pass its latest opaque revision; optionally pass currentVersion as version for an additional graph-version guard. Replace the stored revision with the new value returned by each successful update.
7. Use test_agent with the current draft version when an execution test is authorized, then inspect the returned run. After the user explicitly asks to make the validated draft live, call publish_agent with the latest revision and optional current version.

​

Manage a Skill package

1. Build the complete package, including SKILL.md, every referenced text file or script, and action metadata.
2. Call validate_agent_skill and resolve every error. Validation does not save or run the package.
3. Call create_agent_skill; it always creates a draft. Review the returned skill.packageJson.
4. For later changes, call get_agent_skill, apply the intended edit to the complete package, and call update_agent_skill with its latest currentVersion as expectedVersion. Omit status to preserve it. A published Skill has no separate retained draft pointer, so an update to one changes its live package.
5. Publish only when explicitly requested by calling publish_agent_skill with the newly returned currentVersion.

​

Agent Builder skill

---
name: erstan-agent-builder
description: Create or update an Erstan Agent Builder draft over the erstan MCP server, validate its graph, and publish it only when explicitly requested. Use when asked to build, configure, revise, or publish an Erstan agent or its lanes.
---

# Erstan Agent Builder protocol

Use the connected `erstan` MCP server to author a draft. The Erstan backend
enforces permissions, revision-guarded writes and publishing, published-only public execution, and
optimistic concurrency. Treat server errors as authoritative control results.

## Procedure

1. Call `get_agent_builder_guide` at the start of every authoring request.
2. Call `get_agent_node_catalog`. Use only returned node types, fields, aliases,
   action types, and tool sources. Do not invent hidden or unsupported fields.
3. Establish whether this is a new or existing agent. For a new agent, require
   the target `teamId`. For an existing agent, require its `agentId` and call
   `get_agent` before designing changes.
4. Build a complete graph with stable node and edge IDs. Represent lanes as
   supported start nodes from the live catalog. Connect every lane's start to
   its own executable path. Lanes do not need edges to one another.
5. Preflight the proposed graph with `validate_agent`. For an existing agent,
   include its `agentId` so the proposed fields overlay the saved definition.
6. Persist through `create_agent` or `update_agent`. Supplying `nodes` or `edges`
   to an update replaces that entire array, so send the complete replacement
   graph rather than a fragment. Pass the latest opaque `revision`; optionally
   pass `currentVersion` as `version`. Do not decode or synthesize revisions.
7. Call `validate_agent` on the saved draft, then re-read the final state with
   `get_agent`.
8. If the user explicitly requested publishing, call `publish_agent` with the
   latest revision and optional current version only after saved validation passes.
   Otherwise stop at the validated draft and do not make it live.
9. Hand back the agent ID, current and published versions, `builderUrl`, validation
   result, publication result, and any remaining warnings. Do not claim that the
   draft was tested unless it was actually tested, or published unless
   `publish_agent` returned success.

For a new agent, resolve every error diagnostic before persistence. For an
existing agent, resolve errors caused by the requested change. If preflight
reports unrelated pre-existing errors, stop before writing: the backend validates
the complete candidate and will reject the update until those errors are fixed.
Report them and ask whether the user wants to expand the scope. Do not repair
unrelated behavior without approval.

## Revision conflicts

If `update_agent` or `publish_agent` returns `agent_revision_conflict` or `agent_version_conflict`,
make at most one automatic reconciliation attempt for that intended update:

1. Re-read with `get_agent`.
2. Compare the current graph with the intended change and preserve unrelated
   concurrent edits. If both edits touch the same nodes, edges, attachment
   points, or behavior, stop and ask the user instead of guessing.
3. Reapply only the requested change using the newly returned revision.
4. If it conflicts again, stop and report the concurrent edit instead of
   repeatedly overwriting newer work. Apply the same one-reconciliation limit
   to any later update made to correct validation errors.

The backend atomically rejects stale revisions before mutation. This retry
procedure reconciles user intent; it does not implement or replace concurrency
control.

If the user later approves a same-node merge or expanded repair, treat that as a
new intended update: re-read first, preflight the newly approved complete graph,
and use the latest revision and version.

## Lifecycle boundary

The authoring tools create, read, update, validate, test, and revision-safely
publish drafts. They expose no archive or delete operation. `test_agent` is the
separately scoped draft-test operation; `run_agent` executes retained published
versions. Never substitute one for the other, and never publish without an
explicit user request.

​

Create a draft

{
  "name": "create_agent",
  "arguments": {
    "teamId": "team_abc123",
    "name": "Request summarizer",
    "description": "Summarize a submitted request for review.",
    "behaviorType": "pipeline",
    "nodes": [
      {
        "id": "start_form",
        "type": "start",
        "position": { "x": 0, "y": 0 },
        "data": {
          "label": "External request",
          "triggerType": "input_form",
          "triggerConfig": {
            "inputForm": {
              "title": "Submit a request",
              "fields": [
                { "id": "request", "key": "request", "label": "Request", "type": "textarea", "required": true }
              ]
            }
          }
        }
      },
      {
        "id": "reply",
        "type": "agent",
        "position": { "x": 280, "y": 0 },
        "data": {
          "label": "Summarize request",
          "instructions": "Summarize {{input.request}} for a human reviewer.",
          "toolPolicy": "none"
        }
      }
    ],
    "edges": [
      { "id": "start-to-reply", "source": "start_form", "target": "reply" }
    ]
  }
}

{
  "agent": {
    "id": "agent_abc123",
    "status": "draft",
    "currentVersion": 1,
    "publishedVersion": null,
    "revision": "rev_MjAyNi0wNy0xMlQwMDowMDowMC4wMDBa"
  },
  "builderUrl": "/agents/agent_abc123/edit"
}

​

Update and validate

{
  "name": "update_agent",
  "arguments": {
    "agentId": "agent_abc123",
    "revision": "rev_MjAyNi0wNy0xMlQwMDo...",
    "version": 1,
    "description": "Summarize and prioritize new finance exceptions for review."
  }
}

{
  "name": "validate_agent",
  "arguments": {
    "agentId": "agent_abc123",
    "version": 1
  }
}

​

Publish a validated draft

{
  "name": "publish_agent",
  "arguments": {
    "agentId": "agent_abc123",
    "revision": "rev_MjAyNi0wNy0xMlQwMDo...",
    "version": 1
  }
}

​

External-authoring boundaries

​

Triggers

​

AI nodes and tool selection

• Every Erstan er_* binding must explicitly set source: "erstan"; Erstan source is never inferred. The name must be catalog-visible. Hidden/internal names, including er_agent_builder_*, are denied even when disguised with function prefixes, aliases, nested selectedActions, or toolKeys.
• Connector source names, tool names, and explicit connectionId values must all be visible to the connection owner in the current workspace.
• Within one node, normally pin each canonical runtime tool name once. The only accepted duplicate is one agentTools occurrence mirrored by one legacy selectedActions occurrence with the same trimmed/lowercased exact raw identity, the same explicit normalized source, and no conflicting connectionId (identical when both are set). Function prefixes are not ignored for compatibility: functions.foo and foo are different raw aliases. Duplicates within either array, different raw aliases that canonicalize to one runtime name, conflicting connections, and different sources are rejected. Source conflicts use pinned_tool_runtime_name_source_conflict; all other incompatible duplicates use pinned_tool_runtime_name_duplicate_conflict.
• The runtime-owned Tool Hub and skill meta names tool_search, catalog_search, tool_describe, tool_invoke, tool_batch_invoke, skill_search, skill_describe, skill_read_file, and skill_execute cannot be externally pinned under any connector source. Validation returns pinned_tool_runtime_name_reserved before consulting the connector catalog.
• providerTools is unavailable for external authoring at both node and nested-input level. Use validated agentTools bindings on conversational Agents, or selectedActions only on node types whose live catalog advertises that field.
• Both actionCategory: "http" and the integration alias webhook_outbound are raw HTTP actions and are denied.
• If supplied, a pinned tool’s writePolicy may be require_approval or deny. External authoring cannot introduce writePolicy: "allow", automatic-write flags, or autoApproveWrites. An update or publish may preserve an identical existing allow binding configured in Erstan, but cannot add, move, or duplicate one.

​

Canonical graph fields

​

Child agent references

​

Resource limits

​

Published agents and drafts

​

Next steps