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

> Master advanced Cursor SDK orchestration with sub-agents and resume functionality. Persist state, delegate tasks to cloud sub-agents, and resume execution seamlessly.

- Repository: [Cursor/plugins](https://github.com/cursor/plugins)
- Tags: deep-dive
- Published: 2026-05-25

---

**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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/cursor-sdk/skills/cursor-sdk/references/advanced.md).

```typescript
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:

```typescript
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`](https://github.com/cursor/plugins/blob/main/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).

```typescript
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`](https://github.com/cursor/plugins/blob/main/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.

```typescript
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).

```typescript
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.

```typescript
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`](https://github.com/cursor/plugins/blob/main/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.