05 — Extend

Specialist agents

An agent is a Docker-packaged specialist the Manager dispatches to. Add as many as you need from GitHub, a local path, or a remote URL.

Official agents

Official agents live in the costaff-ai GitHub org. The current line-up (see AI Staff for the full pitch):

Agent	Repo	What it does
Business Analysis	`costaff-agent-business-analysis`	Auto-chart + narrative; polished PDF / PPT / PNG output with full CJK support.
Coding	`costaff-agent-coding`	Writes and runs Python in a sandbox — data cleaning, conversions, batch jobs.
Database	`costaff-agent-database`	Plain-language SQL over PostgreSQL / MySQL with schema auto-discovery.
Twinkle Hub	`costaff-agent-twinkle-hub`	Open government data: 52,960+ datasets, DuckDB filtering at source.
Template	`costaff-agent-template`	The starting point for writing your own specialist (ADK + MCP + manifest).

From GitHub (official + community)

Add by repo URL:

# Business analysis specialist
costaff agent add business-analysis \
  --github https://github.com/costaff-ai/costaff-agent-business-analysis

# Coding specialist
costaff agent add coding \
  --github https://github.com/costaff-ai/costaff-agent-coding

The CLI clones the repo to ~/.costaff/costaff-agent/<name>/src/, validates the agent manifest (add --strict to enforce the full Agent Protocol JSON Schema), prompts for any required env vars (or pre-supply them with -e KEY=VAL), builds the image, and brings the agent up. It also restarts the Manager so the new agent is visible in the next conversation.

Focused tools out of the box

agent add automatically whitelists just the four core platform tools the new agent needs from the Manager's MCP (send_message_now, add_task_comment, move_to_shared, list_data_files) — instead of all ~40. Smaller tool spec, fewer tokens, fewer mis-picks. Customize later in config.json → agent_mcp_filters.

From a local path (for development)

costaff agent add my-agent --local /path/to/my-agent

Useful when you're iterating on a fork or your own agent. The CLI uses the directory in place — no copy.

Register a remote A2A endpoint

Already running an A2A server somewhere? Skip the clone and register the URL:

costaff agent add partner-agent --url http://partner.example.com:8081

Manage agents

Command	What it does
`costaff agent list`	Show every registered agent, its A2A URL, and a health check result.
`costaff agent restart <name>`	Restart the container without rebuilding — fast.
`costaff agent rebuild <name>`	Rebuild the image and restart. Needed after code or `.env` changes.
`costaff agent remove <name>`	Stop, remove, and unregister.
`costaff agent enable / disable <name>`	Toggle whether the Manager dispatches to it, without removing it.
`costaff agent model <name>`	View or set the LLM model for one agent.
`costaff agent tags <name>`	List the release tags available in the agent's repo (for pinning).

Pin to a version

Stick an agent to a specific git tag, branch, or SHA so rebuild doesn't quietly bump it. Useful once you've shipped to production and want releases to be intentional.

# Install pinned
costaff agent add coding \
  --github https://github.com/costaff-ai/costaff-agent-coding \
  --tag v0.1.0-alpha-2

# Subsequent rebuilds stay on the pin
costaff agent rebuild coding

# Bump the pin
costaff agent rebuild coding --tag v0.2.0

# Skip git entirely (built from working tree as-is)
costaff agent rebuild coding --no-pull

costaff agent list shows the active ref in the Ref column. See CLI → Version pinning for the full model.

Model per agent

Each specialist can run a different model. Point the coding agent at gemini-3-flash-preview, leave the BA agent on a smaller model, or wire one specific agent to a local Ollama via LiteLLM.

Write your own agent

Fork costaff-agent-template — it ships the ADK agent skeleton, an MCP server, the costaff.agent.json manifest, and a compose fragment. The contract your agent must honour (manifest schema, A2A behaviour, the four core MCP tools, workspace conventions) is specified in Agent Protocol v1.0. Develop with costaff agent add my-agent --local /path/to/my-agent, then publish to GitHub when it's ready.