TypeScript SDK

Install

bun i @autohandai/agent-sdk

npm install @autohandai/agent-sdk

Start the low-level SDK

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

import { AutohandSDK } from '@autohandai/agent-sdk';

async function main() {
  const sdk = new AutohandSDK({
    cwd: '.',
    debug: true,
  });

  await sdk.start();

  for await (const event of sdk.streamPrompt({
    message: 'Explain what src/index.ts is responsible for.'
  })) {
    if (event.type === 'message_update') {
      process.stdout.write(event.delta);
    }
  }

  await sdk.stop();
}

main();

Use the high-level agent API

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

import { Agent } from '@autohandai/agent-sdk';

const agent = await Agent.create({
  cwd: '.',
  instructions: 'Prefer Bun commands and focused edits.',
  permissionMode: 'interactive',
});

const run = await agent.send('Review the repository for release risks.');

for await (const event of run.stream()) {
  if (event.type === 'message_update') {
    process.stdout.write(event.delta);
  }
}

const result = await run.wait();
console.log(result.text);
await agent.close();

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.

What's new: updated builds keep cancellation responsive during async conditions and expose typed rate-limit events. Read the TypeScript development update for availability, runtime requirements, and verification scope.

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.

for await (const event of sdk.streamPrompt({
  message: 'Run the tests and report failures.'
})) {
  if (event.type === 'permission_request') {
    await sdk.permissionResponse({
      requestId: event.requestId,
      allowed: event.tool !== 'run_command',
      remember: false,
    });
    continue;
  }

  if (event.type === 'message_update') {
    process.stdout.write(event.delta);
  }
}

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:

{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "sk-or-...",
    "model": "openrouter/auto"
  }
}

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

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.