reference
agentfile.yaml Schema
Complete schema reference for agentfile.yaml — every field, type, and allowed value.
The full JSON Schema is at schema/v1/agentfile.schema.json. The agents key is required; everything else is optional.
Validate before building
Run
ninetrix validate to check your file against the schema before running ninetrix build.Top-level fields
| Field | Type | Required | Description |
|---|---|---|---|
agents | map | yes | Map of agent name → AgentDef. First key = entry agent. |
governance | object | no | Global budget + approval config (overridable per agent) |
triggers | array | no | Global webhook + schedule triggers (routeable per agent) |
AgentDef
| Field | Type | Required | Description |
|---|---|---|---|
metadata.role | string | yes | Short role description for the system prompt |
metadata.goal | string | yes | What the agent is trying to achieve |
metadata.instructions | string | no | Multi-line behavior instructions |
metadata.constraints | string[] | no | Hard rules the agent must not violate |
runtime.provider | enum | yes | anthropic | openai | google | deepseek | mistral | groq | together_ai | openrouter | cerebras | fireworks_ai | bedrock | azure | minimax |
runtime.model | string | yes | Model identifier string |
runtime.temperature | float | no | 0.0–2.0, default 0.2 |
tools | Tool[] | "all" | no | List of tools. Use plain strings for built-ins (bash, filesystem, etc.), objects for external tools, or tools: all to enable all built-ins. |
packages | string[] | no | System packages to install via apt-get install -y at build time (e.g. git, ffmpeg, chromium) |
collaborators | string[] | no | Agent keys this agent can hand off to |
execution | Execution | no | Execution mode and verification config |
governance | Governance | no | Agent-level override |
triggers | Trigger[] | no | Agent-level triggers |
runtime.resources.cpu | string | no | Docker --cpus e.g. "1.0" |
runtime.resources.memory | string | no | Docker memory e.g. "2Gi" |
runtime.resources.base_image | string | no | Override Dockerfile FROM |
runtime.resources.warm_pool | bool | no | Keep container alive after completion |
Tool
The tools: field accepts three forms:
YAML
# 1. Plain string — built-in tool name (simplest form)
tools:
- bash
- filesystem
- web_search
# 2. All built-ins at once
tools: all
# 3. Object — required for external tools (MCP, OpenAPI, Composio, hub://)
tools:
- bash # built-in plain string
- name: github
source: mcp://github # MCP tool
- name: stripe
source: openapi://https://stripe.com/spec.json
- name: gh
source: hub://gh # Tool Hub
| Built-in name | Description |
|---|---|
bash | Run shell commands inside the container (alias: shell) |
filesystem | Read and write files inside the container |
memory | Persistent key-value memory store |
scheduler | Schedule deferred tasks |
web_search | Web search via the configured search provider |
web_browse | Fetch and read web pages |
notify | Send notifications to the user |
ask_user | Pause and prompt the user for input |
sub_agent | Spawn a lightweight LLM sub-agent inside the container |
code_interpreter | Execute Python code in a sandboxed environment |
Deprecated syntax
source: builtin://{name} and the top-level builtin: true flag still work for backward compatibility but are deprecated. Use plain string names (- bash) or tools: all instead.Object-form fields for external tools:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Local name for the tool (used in logs and traces) |
source | string | yes | Tool URI: mcp://{server}, composio://{APP}, openapi://{url}, hub://{name}, ./path/to/tool.py |
actions | string[] | no | Limit to specific actions (Composio only) |
auth.type | string | no | Auth type: bearer, basic, header, query |
auth.token | string | no | Bearer token (supports ${ENV_VAR}) |
dependencies.pip | string[] | no | Python packages to install at build time |
dependencies.apt | string[] | no | System packages to install at build time |
base_url | string | no | Base URL override for OpenAPI tools |
Governance
| Field | Type | Description |
|---|---|---|
max_budget_per_run | float | USD spending limit per run |
human_approval.enabled | bool | Enable HITL approval gates |
human_approval.actions | string[] | Tool names requiring approval |
rate_limit | string | Rate limit string e.g. "10_requests_per_minute" |
Execution
| Field | Type | Default | Description |
|---|---|---|---|
mode | direct | planned | direct | Execution strategy |
max_steps | int | 10 | Max tool-use iterations |
verify_steps | bool | false | Verify each step result (planned mode only) |
on_step_failure | abort | continue | retry_once | continue | Failure policy |
verifier.provider | string | — | Provider for the verifier LLM |
verifier.model | string | — | Model for the verifier LLM |
verifier.max_tokens | int | 128 | Max tokens for verifier response |
thinking.enabled | bool | false | Enable pre-run reasoning step |
thinking.provider | string | — | Provider for the thinking LLM |
thinking.model | string | — | Model for the thinking LLM |
thinking.max_tokens | int | 2048 | Max tokens for thinking output |
thinking.prompt | string | — | Custom reasoning instruction |
durability | bool | true | When true (default), the agent automatically restarts and resumes from the last API checkpoint if it crashes. Set to false to disable. |
Trigger
| Field | Type | Description |
|---|---|---|
type | webhook | schedule | channel | Trigger type |
endpoint | string | (webhook) HTTP path, e.g. /run |
port | int | (webhook) Port to expose, default 9100 |
cron | string | (schedule) 5-field cron expression |
message | string | (schedule) Message sent to agent on each fire |
target_agent | string | Route to a specific agent key (default: entry agent) |
channels | string[] | (channel) Messaging platforms to accept, e.g. ["telegram", "whatsapp"]. Required when type: channel. |
session_mode | per_chat | per_message | (channel) per_chat maintains a persistent thread per conversation (default); per_message starts a new run for every inbound message. |
Channel triggers render as webhooks
A
type: channel trigger is compiled into the same webhook handler infrastructure as type: webhook. The agent container exposes an HTTP endpoint; the local API server receives inbound messages from Telegram (and other platforms) and dispatches them to the running agent. Register the webhook URL with the platform via POST /v1/channels/{id}/setup-webhook.