Quickstart

This guide gets you from a clean machine to a running Chidori agent. We'll install the runtime, write a short agent, and run it against an LLM.

Install the runtime

Chidori ships as a single Rust binary. Build from source or install with cargo.

cargo install chidori

Configure an LLM provider

Chidori talks to LLMs directly (Anthropic, OpenAI) or through a LiteLLM-compatible proxy.

export ANTHROPIC_API_KEY=sk-ant-...

Write your first agent

Create agents/summarizer.ts. An agent is a .ts file that exports an agent function — its input argument is the typed JSON payload, and its return value is the JSON output. The runtime injects a chidori host object for every side effect.

import type { Chidori } from "chidori";

export async function agent(input: { document: string }, chidori: Chidori) {
  const summary = await chidori.prompt("Summarize in 3 bullets:\n" + input.document, { type: "summary" });
  const actionItems = await chidori.prompt("Extract action items:\n" + summary, { type: "actions" });
  return { summary, actionItems };
}

Run it

chidori run agents/summarizer.ts \
  --input document="Rust is a systems programming language focused on safety, speed, and concurrency."

The agent's return value is serialized to JSON and printed to stdout:

{
  "summary": "- Rust is a systems language\n- Focused on safety and speed\n- Enables fearless concurrency",
  "actionItems": "- Evaluate Rust for performance-critical services\n- Identify training resources for the team"
}

See the trace

Pass --trace to get a structured call log — every host function call with its arguments, result, duration, and token usage.

chidori run agents/summarizer.ts --input document=@notes.txt --trace

Run as a server

For event-driven agents, webhooks, or anything with sessions, run the agent as an HTTP server.

chidori serve agents/summarizer.ts --port 8080

This exposes:

• GET /health — health check
• POST /sessions — create a session, run the agent, return the output
• GET /sessions/{id}/checkpoint — the full call log
• POST /sessions/{id}/replay — re-run from a checkpoint (zero LLM calls)
• ANY /* — any other request is passed to agent(event, chidori) as the typed input

What's next?

• Agents as TypeScript — the authoring model and what makes runs deterministic.
• Host Functions — the full chidori.* API: prompt, tool, http, memory, input, parallel, exec, retry.
• Event-Driven Agents — turn any agent into a webhook handler.
• Checkpoint & Replay — save a session and replay it later for free.