deep-agent

deep-agent is a TypeScript SDK for building tool-using agents. It packages the runtime layer of a coding agent into reusable library APIs: prompt assembly, provider calls, tool execution, permissions, hooks, sessions, artifacts, context management, MCP adapters, sub-agents, and observability.

It is deliberately not a complete client. The package does not include TUI/React screens, slash-command panels, login flows, themes, voice, remote bridge clients, telemetry dashboards, or application state for a product shell.

Install

npm install
npm run typecheck
npm test

The SDK is ESM-only and requires Node.js 22 or newer.

Quick Start

import { createDeepAgent } from "@qoxop/deep-agent";

const agent = createDeepAgent({
  cwd: process.cwd(),
  permissions: {
    mode: "ask",
    async onRequest(request) {
      if (request.tool.isReadOnly) return { behavior: "allow" };
      return { behavior: "deny", reason: "This host only allows read-only tools." };
    },
  },
});

const result = await agent.run("Read package.json and summarize this project.");

console.log(result.text);
await agent.close();

By default, the Anthropic provider reads configuration from environment variables or nearby .env files:

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_MODEL=claude-sonnet-4-5

Core Capabilities

• Model/tool loop with run() and event streaming through stream().
• Built-in tools for files, search, shell, todo state, sub-agents, skills, MCP resources/prompts, and stored tool results.
• Selective built-in tool registration through tools.builtIns, including include / exclude controls.
• Tool lifecycle governance: schema validation, hooks, permission resolution, sandbox checks, retries, timeouts, cancellation, progress, and large-result storage.
• Provider abstraction with registries, model metadata, dynamic credentials, Anthropic support, provider capabilities, streaming, retry, prompt cache support, usage normalization, and extended thinking options.
• Provider-aware message repair for tool-call ids, missing tool results, and thinking-block compatibility.
• Event-sourced transcript, optional file-backed sessions, replay, branching with branchSession(), session listing/resume/delete APIs, and recovery analysis.
• Context management with token/character budgets, snip, compaction, file-operation breadcrumbs, prompt cache planning, and provider context_too_large recovery.
• Long-running run control through per-run start().steer() and start().followUp(), including additional follow-up turn budgets.
• Sub-agent definitions, experimental background task registry, host interaction protocol, MCP lifecycle, and observability hooks.

Documentation

• Documentation index
• Usage guide
• Technical architecture
• Pi project upgrade plan
• Runnable examples
• Agent OS task list
• Agent OS subsystem plan
• Maintenance scripts
• Archived process documents

Common Patterns

Event Streaming

for await (const event of agent.stream("Inspect this repository.", { stream: true })) {
  if (event.type === "message") process.stdout.write(event.text);
  if (event.type === "tool_use") console.log("tool:", event.name);
  if (event.type === "tool_result") console.log("result:", event.name, event.isError);
  if (event.type === "done") console.log("done:", event.text);
}

Durable Sessions

const agent = createDeepAgent({
  session: {
    persist: true,
    path: ".deep-agent",
  },
});

await agent.run("Analyze this codebase.");

const sessions = await agent.listSessions();
const snapshot = await agent.resumeSession(sessions[0]!.sessionId);
console.log(snapshot.events.length);

Custom Tools

import type { ToolDefinition } from "@qoxop/deep-agent";

const readPackageName: ToolDefinition<{ path: string }, { name?: string }> = {
  name: "readPackageName",
  description: "Read package.json and return its package name.",
  inputSchema: {
    type: "object",
    required: ["path"],
    properties: { path: { type: "string" } },
    additionalProperties: false,
  },
  isReadOnly: () => true,
  async execute(input, context) {
    const result = await context.agent.run(`Use readFile to inspect ${input.path}.`);
    return { content: result.text, data: { name: undefined } };
  },
};

const agent = createDeepAgent({
  tools: { definitions: [readPackageName] },
});

Verification

npm run typecheck
npm test
npm run test:coverage
npm run examples:subagent
npm run examples:multi-agent
npm run examples:crew
npm run examples:long

Coverage is enforced with Vitest/V8 thresholds for statements, branches, functions, and lines.

Project Boundary

deep-agent is a runtime SDK. Hosts are expected to provide the UI, approval surfaces, task panels, process isolation, enterprise policy, and product-specific orchestration around the runtime.