agents

Butterbase Agents

A Butterbase agent is a declarative graph of LLM and tool nodes — not a free-running chat loop. The runtime traverses the graph, calls tools (builtin / MCP / function), and resolves the end node's output_template. State, rate limits, and budgets are enforced by the control plane.

When to use

• The user wants to add a workflow that combines an LLM with tool calls (DB writes, storage reads, MCP servers, app functions).
• The user wants to expose an agent endpoint to end users (visibility: public or authenticated).
• Debugging a failing agent run (look at list_agent_runs, then get_agent_run).
• Registering an external MCP server for the agent to use.

Don't use for plain LLM chat completions — use the ai skill (manage_ai / /v1/ai/chat). Agents are for stateful, multi-step, tool-using workflows.

Concepts

graph_spec (validated by validate_agent_spec before anything is persisted)

Field	Required	Notes
spec_version	yes	Literal "1".
entry	yes	ID of the first node.
nodes	yes	Record { id → node }.
edges	yes	[{ from, to }]. Both endpoints must exist in nodes.
tools	yes	{ builtin: [], mcp_servers: [], functions: [] } — declares what nodes can call.
limits	yes	max_steps (1–200), max_tool_calls (0–500), max_parallel_tools (1–16), timeout_seconds (5–3600), human_timeout_seconds (60–7×24×3600).

Node types:

• llm — model, system_prompt, input_template, output_key, tools: [toolRef], optional temperature (0–2), max_tokens.
• tool — tool_ref, args_template (record), output_key.
• end — output_template (string; can interpolate {{output_key}} values).

toolRef is a discriminated union by source:

• { source: 'builtin', name }
• { source: 'mcp', server_id, name }
• { source: 'function', name }

Each may carry mode_override (read_only | read_write) and exposed_to_override (developer_only | end_user).