TypeScript SDK

The TypeScript wrapper is the most complete path for Node.js and Bun apps that want agent sessions, event streaming, JSON output, and direct permission control.

Install

Start the low-level SDK

Use `AutohandSDK` when you want to manage the CLI lifecycle yourself.

Use the high-level agent API

Use `Agent.create()` when you want a longer-lived session with cleaner application code.

Handle permissions

Interactive mode emits `permission_request` events. Your app decides how to respond.

Important event types

  • `message_update`: streaming assistant text.
  • `tool_start`, `tool_update`, `tool_end`: tool execution lifecycle.
  • `permission_request`: runtime pause for approval.
  • `error`: transport, runtime, or execution failure.

Configuration notes

The TypeScript SDK reads provider setup from the CLI config file. A typical setup looks like this:

`cwd: "."` works as expected, and leaving `cwd` unset falls back to `process.cwd()`.

Next steps

  • Read [Get structured output from agents](/docs/agent-sdk/io/structured-output.html) if you want typed JSON workflows.
  • Read [Handle approvals and user input](/docs/agent-sdk/io/approvals.html) for full approval flows.
  • Open [TypeScript API](/docs/agent-sdk/typescript-api.html) for the reference surface.