Skip to content
Chimera

Agents

An Agent is the central orchestrator in Chimera. It wires together four components — a Provider (the LLM), a set of Tools, a reasoning Loop, and a system Prompt — and exposes a single run(task, env) method that returns an AgentResult.

The Agent Equation

Section titled “The Agent Equation”
Agent = Provider + Tools + Loop + Prompt

The Agent class lives in chimera.core.agent and is deliberately minimal (under 50 lines). All complexity is pushed to the composable pieces it holds.

Agent Lifecycle

Section titled “Agent Lifecycle”

1. Construction

Section titled “1. Construction”
from chimera.core.agent import Agent
from chimera.providers.factory import create_provider
from chimera.core.loop import ReAct
from chimera.core.prompt import Prompt
from chimera.tools import ReadFileTool, WriteFileTool, BashTool


agent = Agent(
    provider=create_provider(model="claude-sonnet-4-20250514"),
    tools=[ReadFileTool(), WriteFileTool(), BashTool()],
    loop=ReAct(max_steps=50),
    prompt=Prompt.from_string("You are a helpful coding agent."),
    name="my-agent",
)

All arguments except provider have defaults:

ParameterDefaultDescription
tools[]List of BaseTool instances
loopReAct()Reasoning loop (50 steps max)
prompt"You are a helpful coding agent."System prompt template
nameNoneOptional human-readable name

2. Running

Section titled “2. Running”
result = agent.run("Implement a fibonacci function in fib.py", env)

Internally, run() does three things:

  1. Renders the prompt — calls self.prompt.render(tools=...) to produce the system message, including a listing of available tools.
  2. Creates a Context — a fresh Context(system=system) that manages conversation history.
  3. Delegates to the loop — calls self.loop.run(provider, tools, context, env) and returns the AgentResult.

3. AgentResult

Section titled “3. AgentResult”

The return value is a dataclass with everything you need:

@dataclass
class AgentResult:
    output: str           # Final text response
    steps: int            # Number of reasoning steps
    tool_calls_total: int # Total tool invocations
    cost: float           # Estimated USD cost
    success: bool         # Whether the agent completed successfully
    error: str | None     # Error message if success=False

Prompt and Context

Section titled “Prompt and Context”

Prompt

Section titled “Prompt”

Prompt is a lightweight template engine with {{variable}} substitution (no Jinja2 dependency). It supports two constructors:

# From a string
prompt = Prompt.from_string("You are a {{role}} agent.")


# From a file
prompt = Prompt.from_file("prompts/system.txt")

When rendered, the prompt automatically appends a list of available tool names.

Context

Section titled “Context”

Context manages the conversation history for a single agent run. It holds a system message and an ordered list of Message objects (user, assistant, tool).

context = Context(system="You are helpful.")
context.add(Message.user("Write a function."))
context.add(Message.assistant("Sure, here is the function..."))
messages = context.to_messages()  # Includes system message

Three API Tiers

Section titled “Three API Tiers”

Chimera offers three levels of abstraction depending on how much control you need.

Tier 1: One-liner via synthesize()

Section titled “Tier 1: One-liner via synthesize()”
from chimera import synthesize


result = synthesize(
    "Build a REST API with FastAPI",
    tests="tests/",
    model="claude-sonnet-4-20250514",
)

This wires up an Agent, Provider, Environment, Trainer, and Strategy automatically. Good for quick prototyping.

Tier 2: Configured Agent

Section titled “Tier 2: Configured Agent”
from chimera.core.agent import Agent
from chimera.providers.factory import create_provider
from chimera.core.loop import ReAct
from chimera.core.tool_group import DEFAULT_TOOLS
from chimera.env.local import LocalEnvironment


provider = create_provider(model="claude-sonnet-4-20250514")
agent = Agent(
    provider=provider,
    tools=list(DEFAULT_TOOLS),
    loop=ReAct(max_steps=100),
)


with LocalEnvironment(workdir="./output") as env:
    result = agent.run("Implement a calculator module", env)
    print(f"Steps: {result.steps}, Cost: ${result.cost:.4f}")

Tier 3: Subclass Agent

Section titled “Tier 3: Subclass Agent”

For advanced use cases, subclass Agent and override run():

class MyAgent(Agent):
    def run(self, task, env):
        # Custom pre-processing
        task = f"[IMPORTANT] {task}\nAlways write tests first."
        result = super().run(task, env)
        # Custom post-processing
        if not result.success:
            result = super().run(f"Fix the error: {result.error}", env)
        return result

The 7-CLI architecture

Section titled “The 7-CLI architecture”

CodingAgent is the shared library every coding-agent CLI inherits. Chimera ships seven of them, each composed from the same nine-phase core but with different per-CLI defaults (step budget, slash-command surface, permission preset, transport):

CLIAliasPosture
chimera minktuiTUI-first interactive coding agent
chimera ottermultiServer-first, multi-client (HTTP+SSE, ACP serve)
chimera ferretsandboxIDE-flagship, sandbox × approval composition
chimera weaselminiMinimal harness, four modes, sub-agents off by design
chimera shrewtinyTuned for small local models
chimera stoatshellShell-mode toggle, Kimi-tuned defaults
chimera badgerstrictHarness-rewrite posture, parity tracking

For the per-CLI quickstart, slash-command surface, and parity row, see each CLI’s documentation:

The chimera which and chimera agents discovery commands surface the full list at the terminal — see the Quickstart for the 7-CLI tour.

Section titled “Related concepts”
  • Sub-agent profiles — the four built-in profiles (planner, researcher, executor, reviewer) the dispatch router routes to.
  • Permission modes — the five-mode approval surface (read-only / suggest / auto / yolo / strict) wired into every CLI.
  • Hook events — the 27 lifecycle events agent runs emit, with payload schemas.
  • File undo — otter’s per-session content-addressed snapshot store powering /undo and /redo.

API Reference

Section titled “API Reference”
  • chimera.core.agent.Agent — main agent class (low-level seam)
  • chimera.core.context.Context — conversation history manager
  • chimera.core.prompt.Prompt — system prompt template
  • chimera.types.AgentResult — result dataclass
  • chimera.synthesize.synthesize — top-level one-liner
  • chimera.assembly.coding_agent.CodingAgent — fully-assembled production agent
  • chimera.assembly.presets.PRESETS — registered AssemblyConfig presets
  • chimera.assembly.presets.AssemblyConfig — preset config dataclass