paseo/public-docs/sdk/agents.md

title, description, nav, order, category

title	description	nav	order	category
Agents with the SDK	Create, run, find, reuse, parent, and archive coding agents from TypeScript.	Agents	52	TypeScript SDK

Agents with the SDK

An agent handle keeps a stable agent ID and exposes the turn lifecycle without exposing daemon RPCs.

Run an initial prompt

const agent = await client.agents.create({
  config: {
    provider: "claude/claude-sonnet-5",
  },
  cwd: "/Users/me/dev/storefront",
  prompt: "Review the checkout flow and propose one focused fix.",
  labels: { source: "checkout-review" },
});

const result = await agent.waitForFinish();
console.log(result.status, result.lastMessage);

waitForFinish() returns one of four statuses:

Status	Meaning
idle	The turn completed and the agent can accept another prompt.
permission	The agent needs a person to answer a permission request in Paseo.
error	The provider ended the turn with an error.
timeout	The wait deadline elapsed; the agent may still be running.

A timeout does not cancel the agent.

Keep a session alive for follow-ups

Create an idle session when prompts arrive later:

const reviewer = await client.agents.create({
  config: {
    provider: "codex/gpt-5.5",
  },
  cwd: "/Users/me/dev/storefront",
  title: "Checkout reviewer",
});

const first = await reviewer.run("Review the current diff.");

if (first.status === "idle") {
  const second = await reviewer.run("Now focus on failure recovery.");
  console.log(second.lastMessage);
}

Use send() for fire-and-forget delivery. Use run() when the caller needs the outcome of that turn.

Find agents by label

Set labels at creation, then filter on them. The daemon does the matching:

const page = await client.agents.list({
  filter: { labels: { "issue-provider": "my-tracker" } },
});

for (const { agent } of page.entries) {
  console.log(agent.id, agent.title, agent.status);
}

Continue an agent by ID

const agent = client.agents.ref("agent_01H8X...");

const result = await agent.run("Now write the fix.");
console.log(result.lastMessage);

ref() does not contact the daemon. Call refresh() first when you need to know whether the agent still exists; it returns null if it does not.

Create a subagent

Create a child through its workspace. The handle owns placement, so the caller does not repeat its directory:

if (!parent.workspaceId) throw new Error("Parent has no workspace");

const workspace = client.workspaces.ref(parent.workspaceId);
const child = await workspace.agents.create({
  config: {
    provider: "codex/gpt-5.5",
  },
  parent,
  title: "Implement checkout fix",
  prompt: "Implement the accepted checkout plan and run focused tests.",
});

parent establishes parentage. Archiving a parent cascade-archives its children. Call detach() first when a child should continue independently.

Request structured output

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    risk: { type: "string", enum: ["low", "medium", "high"] },
  },
  required: ["summary", "risk"],
  additionalProperties: false,
};

const agent = await client.agents.create({
  config: {
    provider: "codex/gpt-5.5",
  },
  cwd: "/Users/me/dev/storefront",
  outputSchema: schema,
  prompt: "Assess the release risk of the current diff.",
});

const result = await agent.waitForFinish();
if (result.status !== "idle" || !result.lastMessage) {
  throw new Error(result.error ?? "Agent returned no structured output");
}

const assessment = JSON.parse(result.lastMessage) as {
  summary: string;
  risk: "low" | "medium" | "high";
};

Validate the parsed value in your application before using it as trusted input.

Archive or detach

await agent.archive(); // Soft-deletes the agent and closes its runtime.
await child.detach(); // Keeps the child alive but removes its parent relationship.

Closing the SDK connection does not archive agents. Archive temporary agents explicitly, preferably in finally.