Agent SDK

Appearance

Convert a Cursor Automation ​

convert-automation exports a dashboard Automation into a local Agent SDK project. Use it when you need to edit, test, or deploy the Automation as code. Keep using the dashboard if you only need to change its prompt or trigger.

The converter refuses Cursor-managed Automations because their behavior lives in managed configuration. The CLI reference lists flags and exit codes.

Run the conversion ​

Sign in before converting. Unlike init, this command does not start a login flow.

bash
agent-sdk login
# or: export CURSOR_API_KEY=key_...
agent-sdk whoami

Pass the Automation's dashboard URL or UUID. The URL must end with /automations/<uuid> or /custom-agents/<uuid>. Do not add path segments after the UUID.

bash
agent-sdk convert-automation https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555

The summary prints the output directory. Change into it before running any setup command. For an Automation named "Nightly triage":

bash
cd nightly-triage

The command fetches the Automation before writing files. A 404 means it was not found, you do not have access, or the agent_serve_mvp feature gate is off for your team. A 422 means it is Cursor-managed. The command writes nothing after either error.

The command runs npm install after writing the project. If the install fails, the files remain. Run npm install in the output directory before dev.

What the project contains ​

A cron Automation with a Linear MCP server might produce:

nightly-triage/
  package.json
  tsconfig.json
  agent/
    agent.ts
    instructions.md
    schedules/nightly-triage.ts
    mcp-connections/linear.ts
  evals/

The command adds missing init scaffold files but omits the demo echo tool. It writes the memory hook only when memory was enabled. File generation leaves existing paths unchanged and marks them as exist. This does not cover npm install, which may update lockfiles or run lifecycle scripts from an existing package.json.

Automation inputProject output
First promptCopies text to agent/instructions.md. Action markup such as @[label](action:...) becomes the label text.
Prompt modelPins the model on defineAgent in agent/agent.ts. git_config and agent_options remain comments.
Cron triggerCreates agent/schedules/<slug>.ts with defineSchedule in UTC.
GitHub triggerCreates agent/channels/github.ts. It converts pull-request action, push branch, issue action, and user allowlist filters.
Slack triggerCreates agent/channels/slack.ts. Mention-only uses cursorAccount; watches, reactions, and channel-created triggers use Socket Mode. Watches add engagement.channelPosts.
Linear, PagerDuty, Sentry, Teams, or generic webhookCreates a boilerplate agent/channels/<slug>.ts.
HTTP or SSE MCP serverCreates a name-based Cursor-account connection under agent/mcp-connections/. The project contains no server URL or credentials.
Stdio MCP serverWrites agent/mcp-connections/<slug>.todo.md.
Slack post or read actionAdds agent/mcp-connections/slack.ts. The summary includes a Verify: step for the original action.
Other built-in dashboard actionAdds a Verify: setup step instead of an Agent SDK tool.

Finish unsupported behavior ​

Warnings and setup steps identify behavior the converter could not reproduce.

Prompt snippets ​

The export omits the source text for unresolved %%INLINECODE<n>%% placeholders. Restore those snippets in instructions.md.

GitHub filters ​

Comment text, CI conclusion, label name, and review-state filters stay fail-closed. The generated hooks return null until you add them. The generated Cursor-account event relay includes only pull-request and comment data. Push, issue, and CI triggers need a GitHub App webhook or github forward. Add repositories for org-wide watches. The converter drops non-GitHub remotes.

Slack triggers ​

Reaction and channel-created triggers have no Agent SDK equivalent. The converter keeps their configuration in comments but adds no handler. Re-add any messageContains filter or completion reaction you need. These triggers and channel watches require a dedicated Socket Mode app. Run agent-sdk slack create --channel-posts, then finish the dashboard wizard.

Provider webhooks ​

Linear, PagerDuty, Sentry, Teams, and generic webhook channels mount POST / under their channel route. Every accepted body starts a run. In default multi-agent mode, the route is /<agent-slug>/v1/channels/<channel-id>. Single mode uses /v1/channels/<channel-id>.

Restore the filters and auth before registering the provider. A hosted alias requires X-Agent-Alias-Token. If the provider cannot send that header, use publicEndpoint() with signature verification in the handler, put an alias-token relay in front, or self-host.

Stdio MCP servers ​

The converter does not export the command, arguments, or environment. Run the server, then replace the .todo.md stub with a reachable connection.

Disabled default tools ​

The converter cannot preserve this restriction. Do not rely on instructions.md as enforcement. Use the tools allowlist, remove unwanted authored or MCP tools, and limit channel permissions.

Review and run the project ​

  1. Read every warning and setup step.

  2. Open the generated channel files. Fail-closed GitHub hooks dispatch nothing until you add their filters. Add auth to boilerplate webhook routes.

  3. Confirm the account MCP servers are connected under MCP in the Cursor dashboard. The serving host must be signed in with agent-sdk login or CURSOR_API_KEY.

  4. Run the printed next steps:

    bash
    agent-sdk validate
agent-sdk dev

  5. Before you deploy, disable the source Automation so both versions do not respond to the same events. The final setup step includes its dashboard URL.

  6. A hosted deployment uses a separate service account. After the first deploy, run agent-sdk mcp oauth <connection> for each generated Cursor-account connection.

What's next ​