Which agent should
you leverage?

An agent here is three things: a narrow slice of the data plane, a prompt that knows that domain's traps, and a hard budget. Twenty-eight of them ship with the app. This page is the map — what each kind is for, when to reach for it, and one worked example end to end.

The short version: you rarely pick. Ask the orchestrator a question and it routes to whichever specialists fit, runs the independent parts in parallel and synthesises one answer. You pick deliberately when you want a specific desk — or when you're building an agent of your own and need to know what shape it should be.

Six kinds of agent

Not a taxonomy for its own sake. Each kind has a different failure mode, so each one is built differently — different tool surface, different model tier, different budget.

The full roster

Generated from the spec files in the agents repo. Every agent below ships in the free app — nothing here is held back. "Model" is the class the agent defaults to; you can pin a different model per agent or per conversation.

Product plane — the agents you talk to

Ops plane — maintains the platform itself

Worked example: the FPL Manager

The newest agent in the roster, and the clearest illustration of how a domain agent gets built. It is currently at version 0.1.0 — Phase 0 of a longer plan — and everything below is the real spec, not an illustration of one.

# src/sportsdata_agents/specs/fpl_manager.yaml
spec_version: 1
agent:
  id: fpl_manager
  display_name: "FPL Manager"
  version: 0.1.0
  model_tier: balanced
  system_prompt: |
    You advise on a Fantasy Premier
    League squad. You RECOMMEND;
    you never act. …
  tools:
    # groups, not capabilities — see right
    mcp_groups: [fpl.players, fpl.reference,
                 fpl.fixtures, fpl.managers]
    native: [run_python]
  forbidden_capabilities: [sport.transactions]
  sandbox: ephemeral
  context:
    retrieval: jit
    verify: true
  limits:
    max_tool_calls: 25
    max_tokens: 120000
    cost_ceiling_usd: 0.40

Why the tool budget is the whole ballgame

Every tool schema rides on every single call. The capability route spends ~115k of a 120k budget describing tools the agent will never use; the group route spends ~3k. Rule of thumb: if the agent plays one game on one platform, name the groups. If it genuinely spans providers, name capabilities.

What an answer looks like

Anatomy of a spec

Every agent in the roster — and every one you build — is this same YAML document. The schema is strict: an unknown field is an error, not a shrug, so a typo fails loudly at load time instead of being silently ignored.

id · display_name · version

Identity, and semver. Pinning matters: a workspace can pin an agent version, and loading a deprecated one still works — it warns rather than breaking.

plane: product | ops

The hard split. Product agents serve you through the gateway; ops agents run under the platform's identity with platform credentials and are reachable only from the operator CLI.

model_tier

fast, balanced, strong — or an explicit provider/model. Most desks are fast; only review and repo work justifies strong.

system_prompt

Where the domain knowledge lives. The good ones read as a list of the specific ways this domain makes an answer wrong, not as a personality.

tools: mcp_capabilities | mcp_groups | native

Capabilities span providers; groups scope to one. Native tools are deterministic in-process helpers — vig removal, Kelly fractions, lineup optimisation — that should never be an LLM's guess.

skills

Markdown playbooks loaded just in time. They guide the model; they cannot grant a tool or bypass a rule.

forbidden_capabilities

A hard deny-list, checked against the allow-list at validation. Defence in depth: it stops an agent quietly acquiring reach in a later edit.

can_delegate_to

Which other agents become callable tools. In practice only the orchestrator uses it.

sandbox: none | ephemeral

Whether the agent can execute code. Ephemeral means a fresh sandbox per run, discarded after.

context · limits

Retrieval policy, compaction on long runs, verification — and the ceilings: tool calls, steps, tokens, wall-clock, dollars. Every run is capped. There is no unbounded agent.

How to pick, in practice

Build your own

The FPL Manager started as a plain-English description of a recurring need. That's the intended path: describe the agent, let the builder draft the prompt, pick the data groups and set the budgets, then version it. It persists locally and runs with agents run --agent <id>. Nothing leaves your machine.