TypeScript SDK

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.

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

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.

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:

Next steps

• Read Pause and resume agents with stopWhen for controlled multi-step runs.
• Read Work with sessions 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.