Agents

Each entry under agents: is a schema.Agent.

Minimal

yaml

agents:
  - id: assistant
    role: assistant
    brain:
      provider: deepseek
      model: deepseek-chat
      backend: openai_compat
      config:
        api_key: "{{env.DEEPSEEK_API_KEY}}"
    system_prompt: |
      You are a helpful assistant.

Fields (schema.Agent)

Field	Notes
id	Required. Referenced by runtime.entry_agent, delegate_to, agent_spawn.agent, and tools.modules.channels...activation.agent.
role	Open text - any label works (developer, researcher, ...). assistant, worker, coordinator, specialist (schema.KnownRoles) are just the common ones the builder suggests. Only the exact value coordinator changes runtime behavior (see below); every other value, known or custom, is a label for the reader, not a switch the daemon branches on.
brain	Required (Brain - see below).
max_tool_iterations	Optional cap on tool calls within one turn for this agent.
system_prompt / prompt	The agent's instructions. Either key works (prompt is an alias).
plan_first	Optional bool - ask the agent to plan before acting.
specialty	One-line description of what this agent is for. Only meaningful on a specialist that's also named in a coordinator's delegate_to - that's the text the coordinator actually sees. A specialty on an agent nobody delegates to is inert.
delegate_to	List of specialist agent ids. Required on the coordinator for agent_spawn to know its team exists - see Multi-agent → delegate_to.
capabilities	Skill names to auto-load into this agent's prompt - see Skills.
modules	Which modules this agent can call - a list of module ids, or a map of module: [tool, ...] to grant specific tools only.
pool	max_workers (parallel spawn concurrency cap), progress (bool, surface per-worker progress), auto_retry (int, retries on a failed spawned run). Only relevant on a coordinator that spawns many specialists in one turn.
instructions.file	Path to a file merged into system_prompt at compile time - a missing file is a compile error. A way to keep a long prompt in its own file.
context	Per-agent context window policy, overriding the app-level runtime.context.
hooks	Per-agent lifecycle hooks, overriding/extending runtime.hooks for this agent only.

delegate_to and pool are both direct fields on the agent, not nested under anything.

Brain

Field	Notes
provider / provider_id	Free-form string (openai, deepseek, anthropic, ...) - not validated against a catalog, a typo compiles clean and just means the wrong (or no) provider at runtime. The compiler only checks whether a non-local provider has some form of auth set (credential, provider_id, or config.api_key) - not that the name itself is real.
model	The model id the provider/backend expects.
backend	One of openai_compat, anthropic, github_copilot (schema.AllBackends) - which wire protocol the runtime LLM stack speaks to reach it. Most providers (including local/gateway routing) go through openai_compat.
config	Backend-specific connection settings - api_key, base_url, and anything else the backend reads.
credential	Credential reference (scoped/shared) instead of an inline key in config.
temperature, max_tokens, top_p	Standard sampling controls.
reasoning_effort	Forwarded verbatim to the provider (minimal/low/medium/high on OpenAI reasoning models; other providers vary) - only the default a fresh session starts with, a live session can override it.
timeout	Per-call timeout, seconds.
context	Brain-level context window policy.
fallback	A full nested Brain the runtime switches to, for the rest of the turn, the moment this one fails with a billing/quota error - see Brain fallback.
vision, image_detail, max_images_per_turn	Multimodal image input controls.

Where the model runs: the Digitorn gateway (default), BYOK, or local

Most apps should use the Digitorn gateway - the managed models Digitorn provides, billed to the user's Digitorn account, with no API key of the user's own to manage. This is the default and the recommended path. The gateway shape:

yaml

brain:
  provider: openai
  backend: openai_compat
  model: mimo-v2.5-free   # a model id the gateway serves
  config:
    api_key: placeholder  # required by the compiler, ignored in gateway mode

The provider: openai + backend: openai_compat + a placeholder api_key is what routes through the gateway: the runtime overrides the base URL to the gateway and injects the user's own auth. The api_key value is never used - it only satisfies the compiler's "a non-local provider must have some auth field" check. Pick the model from the gateway's catalog (the model picker in Studio, or catalog.list_models).

Only depart from the gateway when the user asks for it:

• BYOK (bring your own key) - the user pays their own provider directly. Put a real key in config.api_key (via {{secret.X}}) or a credential reference, with the matching provider/backend for that vendor.
• Local - a model served on the user's own machine (Ollama, LM Studio, vLLM). Set config.base_url to the local endpoint; no gateway, no key.

Roles and spawn

agent_spawn availability is a module grant, not a role check - any agent with the agent_spawn module can call Agent(...). What role: coordinator actually does: combined with a non-empty delegate_to, it injects the {id, specialty} roster into that agent's context, so it knows which specialists exist and what each is for. Without both conditions, spawn still works if granted, but the agent has to be told who to spawn - it won't know on its own. See Multi-agent.

Tool surface

Per-agent modules plus app tools.capabilities decide what the agent may call. Injection mode: Tools.

Related

• App config
• Multi-agent
• Behavior
• YAML building blocks