Using Sub-Agents and Resume Functionality with the Cursor SDK: Advanced Orchestration Patterns

The Cursor TypeScript SDK enables long-running agent workflows by persisting agent state across process restarts, spawning specialized cloud sub-agents for delegated tasks, and resuming execution from unique identifiers without losing conversational context.

The @cursor/sdk package provides enterprise-grade primitives for building sophisticated AI systems that require durability and delegation. By leveraging persistent agent identities and hierarchical sub-agent architectures, developers can implement robust orchestration patterns that survive process crashes while distributing complex cognitive workloads across specialized worker agents.

Understanding the Cursor SDK Agent Architecture

The Cursor SDK distinguishes between parent agents (orchestrators) and sub-agents (specialized workers) through a cloud-native persistence layer. According to cursor-sdk/skills/cursor-sdk/references/advanced.md, the system is designed around three core primitives: creation-time configuration, runtime delegation, and cross-process identity restoration.

Agent Creation and Persistence

Every agent instantiated via Agent.create() receives a unique agentId that serves as the root of persistence. This identifier allows the agent to maintain state—including conversation history and tool configurations—across distributed executions and process boundaries.

The Sub-Agent Delegation Model

Sub-agents are specialized workers defined in the agents: field of the parent creation options. As implemented in the SDK reference documentation, these are cloud-only features at v1 that operate as named helpers. The parent agent invokes sub-agents via the built-in Agent tool, passing context and receiving results through the standard messaging interface.

Configuring Cloud Sub-Agents with MCP Server Sharing

Cloud sub-agents cannot embed full MCP server configurations directly. Instead, they reference servers defined on the parent agent by key. The parent’s mcpServers map acts as the source of truth, and sub-agents refer to entries using keys that map to this parent map, as documented in cursor-sdk/skills/cursor-sdk/references/advanced.md.

import { Agent } from "@cursor/sdk";

const main = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: { repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }] },

  // ── Sub‑agents ────────────────────────────────────────────────
  agents: {
    "code-reviewer": {
      description: "Expert code reviewer for quality and security.",
      prompt: "Review code for bugs, security issues, and proven approaches. Be concrete and cite file:line.",
      model: "inherit",
    },
    "test-writer": {
      description: "Writes tests for code changes.",
      prompt: "Write comprehensive unit and integration tests. Use the project's test framework.",
    },
  },

  // ── MCP servers (shared with sub‑agents) ───────────────────────
  mcpServers: {
    postgres: {
      type: "http",
      url: "https://mcp.example.com/postgres",
      headers: { Authorization: `Bearer ${process.env.PG_RO_TOKEN!}` },
    },
  },
});

To delegate work to a sub-agent from within a running parent agent, use the built-in Agent tool via natural language instructions:

await main.send(`
  Please run the "code-reviewer" on the latest diff.
`);

Resuming Agents Across Process Boundaries

The Agent.resume(agentId, options) method reconstructs a logical agent in a new process without losing accumulated state. As specified in cursor-sdk/skills/cursor-sdk/references/advanced.md, only configuration options that are not automatically persisted must be supplied again. These include inline mcpServers configurations and local.settingSources (for local agents).

import { Agent } from "@cursor/sdk";

async function continueAgent(agentId: string) {
  const resumed = Agent.resume(agentId, {
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "composer-2" },

    // re‑pass MCP servers because they are not persisted automatically
    mcpServers: {
      postgres: {
        type: "http",
        url: "https://mcp.example.com/postgres",
        headers: { Authorization: `Bearer ${process.env.PG_RO_TOKEN!}` },
      },
    },

    // local agents need the cwd to locate their data directory
    local: { cwd: process.cwd() },
  });

  const run = await resumed.send("continue where we left off");
  const result = await run.wait();
  console.log("Run finished with status:", result.status);
}

This pattern is particularly valuable for long-lived services that process requests intermittently, as shown in orchestrate/skills/orchestrate/scripts/core/loop.ts where checkpoint-restart logic leverages Agent.resume for fault tolerance.

Inspecting Runs and Retrieving Artifacts

Listing and Accessing Agent State

The SDK provides discovery methods for auditing active and historical agents. Use Agent.list to enumerate agents and Agent.get to retrieve specific instances. For execution forensics, Agent.listRuns and Agent.getRun expose detailed run metadata.

const localAgents = await Agent.list({ runtime: "local", cwd: process.cwd(), limit: 20 });
const cloudAgents = await Agent.list({ runtime: "cloud", apiKey: process.env.CURSOR_API_KEY! });

Replaying Event Streams

Run objects expose two primary inspection methods: conversation() yields the full turn-by-turn transcript, while stream() can replay the original event stream when available (cloud-only).

const runs = await Agent.listRuns(agentId, { runtime: "cloud", apiKey: process.env.CURSOR_API_KEY! });
const run = await Agent.getRun(runs.items[0].id, { runtime: "cloud", apiKey: process.env.CURSOR_API_KEY! });

if (run.supports("stream")) {
  for await (const ev of run.stream()) {
    console.log(ev);
  }
}

Downloading Cloud Artifacts

Cloud agents may emit files such as test reports or generated documentation. The SDK supports artifact enumeration via agent.listArtifacts() and retrieval via agent.downloadArtifact(path). Note that local agents currently return empty lists for these operations.

const artifacts = await resumed.listArtifacts();
for (const a of artifacts) {
  console.log(`Artifact ${a.path} (${a.sizeBytes} bytes)`);
  const content = await resumed.downloadArtifact(a.path);
}

Agent Lifecycle Management

Agents support soft-deletion workflows through the Agent.archive, Agent.unarchive, and Agent.delete methods. Archived agents remain searchable when includeArchived: true is passed to Agent.list, enabling compliance and audit workflows without cluttering active agent lists.

Summary

• Sub-agents are cloud-only specialized workers defined in the agents: field that reference parent MCP servers by key.
• Resume functionality uses persistent agentId values to reconstruct agents in new processes, requiring only non-persisted options (MCP servers and local settings) to be resupplied.
• Inspection APIs (listRuns, getRun, conversation, stream) provide full observability into agent execution history.
• Artifacts are cloud-only files emitted by agents, accessible via listArtifacts() and downloadArtifact().
• Lifecycle operations support archiving and deletion while maintaining searchable history, as implemented in orchestrate/skills/orchestrate/scripts/core/agent-manager.ts.

Frequently Asked Questions

Can sub-agents run locally, or are they cloud-only?

Sub-agents are cloud-only at v1. According to the Cursor SDK advanced reference documentation, the agents: configuration field only functions when the parent agent is created with cloud runtime settings. Local agents do not support the sub-agent delegation model.

What data is preserved when resuming an agent?

The agentId persists the agent’s core identity, conversation history, and cloud configuration automatically. However, inline mcpServers and local.settingSources are not persisted and must be explicitly provided again when calling Agent.resume(). This design allows credentials to remain ephemeral while maintaining agent continuity.

How do sub-agents access tools and MCP servers?

Sub-agents cannot define their own MCP server configurations. Instead, they reference entries from the parent agent’s mcpServers map by key. The parent acts as the source of truth for tool availability, and sub-agents inherit access only to the servers explicitly referenced in their configuration keys.

Can I retrieve artifacts from local agents?

No. The listArtifacts() and downloadArtifact() methods currently return empty results for local agents. Artifact emission and retrieval are cloud-only features designed for long-running cloud agents that generate reports, exports, or other file outputs during their execution lifecycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}