Migrate an early-alpha project to architecture v2

Use this guide only for Agent SDK projects deployed during the early alpha. Projects that never deployed on architecture v1 already use v2 and need no migration.

Check whether your project needs migration

Migrate when at least one of these signals is present:

• package.json depends on the legacy v1 package. Remove it, then install the package agent-sdk init writes:

  npm uninstall @cursor/julynpm install @grok/agent-sdk@latest

• A script or CI job runs the legacy early-alpha CLI.

• agent/agent.ts sets architecture: "v1".

• agent-sdk deployment get <slug> does not print architecture: v2.

Stop when none of these is true. An existing agent/ project root can remain in place; Agent SDK still loads it even though current examples use bot/.

agent-sdk migrate prints Nothing to migrate. and exits 0 only when --dir shows no migration work. The check looks for an @cursor/july dependency, architecture: "v1", bot/storage.ts or agent/storage.ts, runtime: "grokbot", a literal SCM credential, a /v1 continuation selector, an anonymous reminder, and a *_MCP_URL peer connection. When any of those is present, or a project file cannot be read, the command starts the agent. It does not read the hosted deployment. Run agent-sdk deployment get <slug> when you still need to see whether that copy is on v1.

Start the migration

Commit and push the source you want to migrate. agent-sdk migrate reads that pushed Git ref, starts a Cursor cloud agent with the bundled migration skill, and waits for the agent to open a pull request. It does not deploy the project.

agent-sdk loginagent-sdk migrate --dir .

Inside a checkout, the command infers the repository, current ref, and project path. Pass them when you need to target a different pushed source:

agent-sdk migrate \  --dir ./bots/triage \  --repo https://github.com/acme/agents \  --ref migrate-triage-v2 \  --path bots/triage

Use --no-wait to print the cloud agent URL and return while it works. Use --json for machine-readable status. The CLI reference covers every flag, output, and exit status.

Use the coding-agent skill directly

You can instead ask a coding agent working in the project checkout to follow the bundled bdk-migrate-v2 skill. The skill owns the code changes, capability checks, local verification, and deployment handoff.

Follow the bdk-migrate-v2 skill for this project. Open one pull request with the migration, but do not deploy it or change deployment secrets.

If the project depends on a v1 capability without a supported v2 path, the skill tells the coding agent to stop and name the blocker instead of removing the behavior.

Review the pull request

Before merging, confirm the pull request:

• Uses @grok/agent-sdk and agent-sdk, and removes the v1 architecture opt-in.

• Moves durable state to ctx.host.kv or ctx.host.files, reads secrets inside the handler that needs them, and accounts for hosted HTTP routes returning 202.

• Names SCM channel secrets instead of reading them: every githubChannel({ credentials }) field and the GitLab or Bitbucket webhookSecret is { secretName: "NAME" }. agent-sdk validate reports each field still written as a literal or () => process.env.NAME getter, as a warning while architecture: "v1" is set and as an error once it is removed. The GitHub guide explains the named form.

• Rewrites each peer call that took its URL from a secret or environment variable, such as BUILDER_MCP_URL, to defineConnection({ agent: "<slug>" }) under bot/mcp-connections/ (or agent/mcp-connections/ when the project root is agent/). Confirm the slug before you merge. The pull request lists each secret the rewrite left unused, and it leaves a TODO where it could not determine the slug.

• Calls out unsupported behavior and any follow-up needed for reminders, schedules, Slack, or MCP connections.

• Reports the validation, type checks, tests, and credential-dependent checks it ran or handed off.

The migration pull request should change source only. Deploy after it merges.

Choose a cutover

Prefer a new slug for Slack, webhooks, or data in ctx.host.kv. Point the trial at a test repository so both deployments do not act on the same source-control events. If the CLI reports that same-slug replacement is unavailable, use a new slug.

Deploy after merge

Deploy from the merged, pushed ref. Reuse every --cursor-events-repo value from the v1 deployment, and move every --allow-domain value into hosting.egressDomains. agent-sdk deploy has no --allow-domain flag.

agent-sdk validate --dir .agent-sdk deploy --dir . --slug <existing-or-new-slug>

When the folder contains more than one agent, deploy each agent folder alone. Run agent-sdk deploy --dir <agent folder> one time for each agent. One agent-sdk deploy on the parent folder prints those commands and does not deploy. Do not use agent-sdk deploy --all. Repeat agent-sdk slack create --env prod for each agent folder. The Slack app slug is the folder name.

When the pull request calls another agent with defineConnection({ agent: "<slug>" }), deploy the caller and that peer on @grok/agent-sdk 0.2.18 or newer. Both deployments must belong to the same team, and the caller reaches the peer once the peer deployment is running. The connection file is already in the merged source, so unset each URL secret the pull request lists after both deploys:

agent-sdk secret delete <slug> NAME

agent-sdk migrate prints the steps that follow the first deploy: one deploy per agent folder, agent-sdk slack create --env prod --dir <agent-folder> for each Slack agent, agent-sdk secret delete for peer URL secrets the pull request lists, and agent-sdk secret list / agent-sdk secret set when the slug is new. Slack setup redeploys the deployment by itself. agent-sdk secret set takes effect on the next request. Neither step needs another deploy.

After the deployment starts, follow that checklist for Slack, webhook callers, peer connections, and secrets, then verify a hosted turn. The deployment guide covers the managed hosting workflow.

Related

• CLI reference: migration flags, output, and exit status
• bdk-migrate-v2 skill: the coding procedure and complete capability matrix
• Peer agents: how a deployed caller reaches another agent by slug
• Deployment: deploy and verify the reviewed project