Journey Agents

Journey: Agents

Build the agents described in 02-plan.md. Order: MCP servers first (probe must pass before any agent references them) → agents → smoke runs.

When to use

• Dispatched by journey when current_stage: agents.
• Directly via /butterbase-skills:journey-agents.
• Skipped (annotated (n/a)) if the plan lists no agents.

Preflight

If docs/butterbase/03-preflight.md is missing, older than 24 hours, or 00-state.md has app_id: null, invoke butterbase-skills:journey-preflight first. Wait for it to return successfully before proceeding.

Inputs

• docs/butterbase/02-plan.md — the Agents section (names, purpose, tool list, visibility, MCP servers needed).
• docs/butterbase/00-state.md — for app_id.
• Any handcrafted spec files under agents/ in the project (preferred — version-controlled and survives clones).

Procedure

• Refresh docs. Call butterbase_docs with topic: "agents". If the cache (docs/butterbase/03b-docs-cache.md) already covers agents, skip.

• Register MCP servers first. For each MCP server in the plan:
• Print: "Registering MCP server '<label>' at <url> (transport=<sse|http|streamable_http>). Proceed?". Wait for yes.
• Call the MCP-servers registration route (or the dashboard's MCP Servers page if a wrapping MCP tool is not yet available — check butterbase_docs topic agents for the current preferred path).
• Wait for probe result. If status: unhealthy, surface the error and ask the user to fix (URL, auth header, transport mismatch) before continuing. Do not create agents that reference an unhealthy server.

• Build each agent. For each agent in the plan, in order:

a. Print: "About to build agent: <name> (visibility=<v>, tools=<n builtin / m mcp / k function>). Proceed?". Wait for yes.

b. Invoke butterbase-skills:agents via the Skill tool with: agent name, intended behaviour, plan-derived tool list, model preference, visibility/limits. The wrapped skill drafts the graph_spec, writes it to agents/<name>.json in the project repo, and calls validate_agent_spec.

c. If validation fails, surface the Zod issues and loop the agents skill to fix.

d. Safety gate. If visibility != 'private' AND any node can reach a write tool (insert_row, update_row, delete_row, write_storage, or any read_write-mode MCP/function tool), explicitly ask: "This agent is reachable by <visibility> callers and can write data. Set safety_acknowledged=true? (yes / change to private / reduce tools)". Do not proceed silently.

e. create_agent with the validated spec.

f. Smoke: invoke_agent with a representative input. Poll get_agent_run until terminal. If the run errors, debug per the agents skill's debugging procedure; otherwise show the user the final output.

g. Append one line per agent to docs/butterbase/04-build-log.md:

<ISO timestamp> agents create_agent <agent-name> ok (run smoke=<run_id>)

• Persist specs to the repo. Confirm agents/<name>.json files are tracked locally. They will be carried by butterbase repo push (run by the templates stage if the user is publishing, or any time the user pushes a snapshot). This is the only way a clone recipient can recreate the agents — the agents table is not part of clone replay.

• Tick state. Mark - [x] agents in 00-state.md, set current_stage to the next unchecked stage.

• Return to journey orchestrator (or ask "Continue to the next stage? (yes/no)").

Outputs

• One or more agents created against the live app.
• One or more agents/<name>.json spec files in the project repo.
• One line per agent in docs/butterbase/04-build-log.md.

Anti-patterns

• ❌ Skipping validate_agent_spec. Bad specs surface as opaque runtime errors after the agent is live.
• ❌ Creating a public write-capable agent without rate limits or a daily_budget_usd. The runtime requires safety_acknowledged, but you should also pick hourly per-IP and per-app caps.
• ❌ Hard-coding secrets in system_prompt or args_template. Read them from ctx.env inside a function tool.
• ❌ Forgetting that the agents table is not replayed on clone. Always commit the spec JSON and document re-import (butterbase agents create -f agents/<name>.json) in the README.
• ❌ Smoking with visibility: 'private' and calling it good for a public agent. After the smoke, change visibility and re-test with an unauthenticated curl to confirm the public path works.