Agents

Reach for this when you're building Butterbase agents: declarative LLM and tool graphs that execute multi-step workflows, not free-running chat loops. It handles the full lifecycle from writing and validating a graph_spec (entry node, LLM nodes, tool calls, edges) to deploying with access controls and debugging failed runs. You'll use it to wire up MCP servers, set rate limits and budgets, and troubleshoot tool errors or timeout issues. One thing to know: agents with write tools and public visibility require you to explicitly set safety_acknowledged true, which is the right forcing function. The validate_agent_spec step is mandatory for a reason; skip it and you'll chase Zod errors at runtime instead of design time.

GitHub stars: 532
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add butterbase-ai/butterbase-skills --skill agents --agent claude-code

Installs into .claude/skills of the current project.

Files

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.