Skip to main content

Agents API

The agents API tracks Claude invocations within executions.

Contract

  • Sync: All methods are synchronous.
  • Return shape: snake_case fields with Date timestamps.
  • Status: pending | running | completed | failed | cancelled.

Methods

start

Log the start of an agent.
const agentId = db.agents.start(
  "Implement the feature",      // prompt
  "sonnet",                      // model
  "You are a senior engineer"    // system prompt
);

complete

Mark agent as complete.
db.agents.complete(
  agentId,
  "Feature implemented",         // output
  { success: true, files: 3 },   // structured result
  { input: 1000, output: 500 }   // tokens
);
structuredResult is stored as result_structured in the database.

fail

Mark agent as failed.
db.agents.fail(agentId, "Timeout exceeded");

current

Get the currently running agent.
const agent = db.agents.current();
if (agent) {
  console.log(`Running: ${agent.prompt.substring(0, 50)}...`);
}

list

List agents for an execution.
const agents = db.agents.list(executionId);

for (const agent of agents) {
  console.log(`${agent.model}: ${agent.status}`);
  console.log(`  Tokens: ${agent.tokens_input ?? 0} in, ${agent.tokens_output ?? 0} out`);
}

Tool Calls

Track tools used by agents:
// Start a tool call
const toolId = db.tools.start(
  agentId,
  "Edit",
  { file: "src/main.ts", changes: "..." }
);

// Complete the tool call
db.tools.complete(
  toolId,
  "File edited successfully",
  "Edited src/main.ts: added 15 lines"
);

// List tool calls for an agent
const tools = db.tools.list(agentId);

Types

interface Agent {
  id: string;
  execution_id: string;
  phase_id?: string;
  prompt: string;
  model: string;
  system_prompt?: string;
  status: "pending" | "running" | "completed" | "failed" | "cancelled";
  result?: string;
  result_structured?: Record<string, any>;
  error?: string;
  tokens_input?: number;
  tokens_output?: number;
  tool_calls_count: number;
  started_at?: Date;
  completed_at?: Date;
  created_at: Date;
  duration_ms?: number;
  log_path?: string;
  stream_summary?: StreamSummary;
}

interface ToolCall {
  id: string;
  agent_id: string;
  execution_id: string;
  tool_name: string;
  input: Record<string, any>;
  output_inline?: string;
  output_summary?: string;
  output_size_bytes?: number;
  output_path?: string;
  output_git_hash?: string;
  error?: string;
  status: "pending" | "running" | "completed" | "failed";
  started_at?: string;
  completed_at?: string;
  created_at: string;
  duration_ms?: number;
}

interface StreamSummary {
  textBlocks: number;
  reasoningBlocks: number;
  toolCalls: number;
  toolResults: number;
  errors: number;
}