---
title: "TypeScript SDK Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/typescript
---

# TypeScript SDK

The TypeScript wrapper is the most complete path for Node.js and Bun apps that want agent sessions, event streaming, per-step run control, concurrent-agent awareness, 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.

## Pause at completed tool steps

Pass `stopWhen` to `agent.run()` or `agent.send()` when your application needs to inspect a completed tool step before the agent continues.

``` typescript
import {
  Agent,
  isStepCount,
} from '@autohandai/agent-sdk';

const agent = await Agent.create({ cwd: '.' });

try {
  const first = await agent.run(
    'Inspect this repository and identify the first release risk.',
    { stopWhen: isStepCount(1) },
  );

  console.log(first.status); // 'stopped'
  console.log(first.steps);

  // Continue in the same agent session with its existing history.
  const next = await agent.run('Continue from that result.');
  console.log(next.text);
} finally {
  await agent.close();
}
```

Use `isStepCount(count)`, `hasToolCall(toolName)`, or an async custom condition. Read [Pause and resume agents with stopWhen](/agent-sdk/io/step-control.html) for result types, event semantics, and failure handling.

## Coordinate concurrent agents

Choose a session-awareness tier when multiple local Autohand agents may work in the same repository. The default `warn` tier reports likely Git, file-claim, and repository-drift conflicts without taking control away from the host.

``` typescript
const agent = await Agent.create({
  cwd: '/path/to/project',
  sessions: { awareness: 'coordinate' },
});

const peers = await agent.getSessionPeers();
console.log(peers);
```

The `passive`, `warn`, and `coordinate` tiers are local-machine coordination modes. Hosts can observe `session_peer_joined`, `session_peer_updated`, `session_peer_left`, and recoverable `session_awareness_error` events. See [Concurrent session awareness](/agent-sdk/concepts/sessions.html#concurrent-session-awareness).

## 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.
-   \`step\_end\`: a completed tool-step boundary, including its calls and results.
-   \`permission\_request\`: runtime pause for approval.
-   \`session\_peer\_joined\`, \`session\_peer\_updated\`, \`session\_peer\_left\`: concurrent local agent presence.
-   \`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 [Pause and resume agents with stopWhen](/agent-sdk/io/step-control.html) for controlled multi-step runs.
-   Read [Work with sessions](/agent-sdk/concepts/sessions.html#concurrent-session-awareness) for concurrent-agent coordination.
-   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.