Running Agents

Basic Run

const result = await agent.run({
  task: 'Summarize the latest sales report',
});

console.log(result.runId);   // "run_1710000000000_abc123"
console.log(result.status);  // "completed"
console.log(result.output);  // The agent's response

result = await agent.run(task="Summarize the latest sales report")

print(result.run_id)   # "run_1710000000000_abc123"
print(result.status)   # "completed"
print(result.output)   # The agent's response

RunInput

interface RunInput {
  task: string;       // The task for the agent
  context?: string;   // Additional context (appended to system prompt)
  runId?: string;     // Resume a previous run (for checkpoint/resume)
}

RunResult

interface RunResult {
  runId: string;
  status: RunStatus;
  output: string | null;
  trace: {
    steps: StepRecord[];
    summary: TraceSummary;
  };
  rollback?: RollbackResult;
  anomalies?: Anomaly[];
}

Run Status

Status	Description
`initializing`	Run is being set up
`running`	Agent is actively executing
`paused`	Paused by a hook or policy
`awaiting_approval`	Waiting for human approval
`completed`	Finished successfully
`failed`	An error occurred
`max_steps_exceeded`	Reached `maxSteps` limit

With Context

Pass additional context that gets appended to the system prompt:

const result = await agent.run({
  task: 'What should we order?',
  context: 'Current inventory: 5 pens, 0 notebooks, 12 folders',
});

Error Handling

const result = await agent.run({ task: 'Do something risky' });

if (result.status === 'failed') {
  console.error('Run failed:', result.output);
  // Check the trace for details
  for (const step of result.trace.steps) {
    if (step.error) {
      console.error(`Step ${step.index}: ${step.error}`);
    }
  }
}

Inspecting the Trace

Every run produces a full trace:

const result = await agent.run({ task: 'Do something' });

for (const step of result.trace.steps) {
  console.log(`Step ${step.index}: ${step.type}`);
  console.log(`  Duration: ${step.duration}ms`);
  console.log(`  Tokens: ${step.tokens.input} in / ${step.tokens.output} out`);
  if (step.toolCall) {
    console.log(`  Tool: ${step.toolCall.name}(${JSON.stringify(step.toolCall.input)})`);
  }
}

console.log('Summary:', result.trace.summary);
// { totalSteps, totalTokens, totalDuration, toolCalls, ... }

Next Steps

Streaming — real-time events
Resume — resume from checkpoints
Steps — step records in detail

On this page