Agent

API reference for the Agent orchestrator — run, stream, and spawn.

The Agent class runs the model ↔ tool loop, maintains conversation state, and emits events for streaming UIs.

import { Agent } from "kenpachi";

---

Constructor

const agent = new Agent(provider, tools, context?);

provider · ModelProvider · required

LLM adapter — createAnthropicProvider() or createOpenAIProvider().

tools · Tool[] · required

Tools available to the model (can include handoff() tools).

context · AgentContext · default: "new AgentContext()"

Optional conversation state — use a branched context for time-travel.

---

run(userInput, options?)

Runs to completion and returns AgentRunResult.

const result = await agent.run("What's the weather?", {
  onText: (chunk) => process.stdout.write(chunk),
  onEvent: (e) => console.log(e.type),
  maxTurns: 8,
  maxToolRepairAttempts: 2,
});

console.log(result.text);
console.log(result.history);

AgentRunOptions

maxTurns · number · default: "8"

Maximum model turns before stopping.

maxToolRepairAttempts · number · default: "2"

Retries when tool arguments fail Zod validation.

onEvent · (event: AgentEvent) => void

Fires for every event: turn_start, text_delta, tool_call, tool_result, rollback_start, run_end, etc.

onText · (text: string) => void

Shorthand — called on each text_delta (token-level when the provider supports streaming).

AgentRunResult

text · string

Plain text extracted from the final assistant message.

message · Message

Full final assistant Message object.

content · Message['content']

Alias for message.content (backward compatible).

history · Message[]

Full message history after the run.

---

stream(userInput, options?)

Async generator yielding AgentEvent on each step, then returning AgentRunResult.

for await (const event of agent.stream("Hello")) {
  if (event.type === "text_delta") process.stdout.write(event.text);
}

Same options as run(). Internally, run() is implemented as a thin wrapper around stream().

See Streaming for all event types and UI patterns.

---

spawn(seedMessages?)

Creates a new Agent with the same provider and tools but a fresh context, optionally seeded with messages.

const sub = agent.spawn(parentMessages);
const result = await sub.run("Continue this task");

Used internally by handoffs. Call directly when you need an isolated sub-run without mutating the parent.

---

context

Public AgentContext instance — snapshots, branching, message history.

await agent.run("Hello");
const snapshots = agent.context.listSnapshots();
const branched = agent.context.branchAt(0);
const branchedAgent = new Agent(provider, tools, branched);

See State Checkpointing.

---

Other methods

getProvider() · ModelProvider

Returns the provider passed to the constructor.

getTools() · Tool[]

Returns the tool list.