Direct Clients

Direct clients call a runtime in-process.

const runtime = createAgentRuntime({
  agent,
  storage,
  scopeKey: (identity) => identity.workspaceId,
});

const pai = runtime.client({
  identity: { userId, workspaceId },
});

const thread = pai.thread(pai.newThreadId());
const run = await thread.send("Draft a report");

await run.waitUntilIdle();

Use direct clients for trusted code:

• command-line applications;
• tests;
• background jobs;
• local scripts;
• single-runtime apps.

They expose the same AgentClient, Thread, and RunHandle shape as remote clients.

Direct clients skip HTTP and do not run resolveIdentity(). Treat them as already-authenticated callers.

They also do not provide a browser security boundary. If a CLI, job, or server-side task acts for an end user, call your application policy before constructing runtime.client({ identity }). Remote browser traffic should use an HTTP receiver such as createPaiHonoReceiver({ pai, resolveIdentity, ... }) so resolveIdentity runs at the server boundary.