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.
• When the live guide advertises lifecycle.skillSavesAreDrafts: true, Skill saves stage working content and retain the previous published package. Agent presentation stages with the graph when lifecycle.agentPresentationVersioned: true. A missing capability is not evidence of staging support.
• 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": "..." }. A current read provides the opaque write revision paired with that content. An explicit historical version adds top-level selectedVersion and a read-only history revision; never use it to authorize a current update or publication.
• 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 opaque revision paired with the edited baseline, and at least one metadata or graph change. version is an optional additional current-version guard. It does not move an agent to another team. Never decode or synthesize a revision, or substitute a newer token onto stale edits.
• 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 opaque revision of the exact approved content; pass its currentVersion as optional version for a second guard. It returns authoring state plus published: true and alreadyPublished. An exact already-published version is a validated no-op. After a lost response, reuse the same supported idempotency key only with identical arguments, or re-read and reconcile content and lifecycle state. Do not infer success merely from a published status or retry blindly under a fresh key.
• test_agent requires the selected draft’s version. Send its paired revision when advertised; explicit top-level skillVersions: [{ skillId, version }] require that revision and matching schema support. Never place these controls inside business input.
• 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 skill.packageJson, currentVersion, and, on supporting servers, publishedVersion and hasDraft. The current package can be an unpublished draft. Send the complete candidate to update_agent_skill with the version paired with its baseline as expectedVersion; do not send only changed files.
• publish_agent_skill accepts skillId and the approved package’s expectedVersion. A stale version returns skill_version_conflict; re-read and reconcile, and obtain approval for changed publication content.

​

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. Keep the returned content and revision together. Before a later update, compare any remote changes with the intended edit; do not replace a stored guard without reconciling. Pass the revision paired with the edited baseline and optionally its current version.
7. Use test_agent only when a real hosted preview is authorized. It is optional, not a publication gate. Publish only the exact validated content the user approved, with its paired guard; never publish dependencies implicitly.

​

Exact draft Skill previews

​

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. Before editing a published Skill, read get_agent_builder_guide. With lifecycle.skillSavesAreDrafts: true, a save stages a working package while the prior published version remains live. Read the complete package, apply the intended edit, and send its paired currentVersion as expectedVersion. Omit status unless a separate availability change is authorized; setting it to draft is not how staging works.
5. Publish only the exact validated package explicitly approved by the user, using its expectedVersion. A published status with hasDraft: true is valid: availability and the presence of working changes are different things.

​

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 opaque `revision` paired with the
   edited baseline; optionally pass its `currentVersion` as `version`.
   Do not decode or synthesize revisions. Retain returned content and its guard
   together; do not attach a fresh guard to stale local edits.
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
   revision paired with the exact approved content and optional current version
   only after saved validation passes. Re-read to detect drift, not to silently
   publish a different revision. Publish required Skills only with separate approval.
   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.

For publication, changed content needs renewed approval rather than automatic
reconciliation into the previously approved revision. After an ambiguous
mutation, recover with the same supported idempotency key and identical intent,
or reconcile before any new write. Stop if the outcome remains uncertain.

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.

Check the live guide's staged-save and presentation capabilities before assuming
draft isolation. Skill saves stage content only when `skillSavesAreDrafts` is
confirmed. For an explicitly requested draft preview, use the current version
and advertised revision; exact Skill selections belong in top-level
`skillVersions`, never `input`. Unsupported selections are a capability gap,
not permission to drop them or publish dependencies. Preview is optional and
does not bypass approvals or imply publication intent.

​

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 names tool_search, catalog_search, tool_describe, tool_invoke, tool_batch_invoke, skill_search, skill_describe, skill_read_file, er_skill_read, 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