Agent definitions¶
An agent definition is a portable, versioned description of one agent: a Markdown file whose YAML frontmatter says what the agent is and whose body is its system prompt. The CLI, saige serve and saige-mcp load definitions the same way, and so can your own host through the Go packages.
Four concerns stay separate:
| Layer | Package | Job |
|---|---|---|
| What a definition is | agent/definition |
Definition, strict Parse, the JSON Schema |
| Where it comes from | agent/definition, agent/definition/pgsource |
Source: a directory, an fs.FS, a reader, HTTPS, Postgres, and Layered over any of them |
| How a reference resolves | agent/definition |
Registry: name@range to one version, reference checks, cycles, digests, reload |
| How it becomes an agent | agent/definition/bind |
Bind: model, tools, skills, memory, sub-agents, approvals, compaction, guardrails and limits as agent options |
Loading a definition never connects to a server, reads a credential or runs a tool. Only Bind does, with what the host puts in its Env. D-43 records why.
A first definition¶
---
apiVersion: saige/v1
name: assistant
version: 1.0.0
description: A concise assistant that reads files in the workspace to answer questions.
model: anthropic/claude-haiku-5-5
dials:
creativity: focused
tools:
harness: [read]
limits:
max_iterations: 6
metadata:
owner: examples
---
You are a concise assistant working in a software repository.
Answer the question you are given in a few sentences. When the answer
depends on the files in the workspace, read them first with your tools
instead of guessing, and name the files you relied on.
Run it:
saige agent run --agents-dir examples/agents --agent assistant "What module path does go.mod declare?"
A definition with a sub-agent and approval rules:
---
apiVersion: saige/v1
name: repo-steward
version: 1.2.0
description: Answers questions about a repository's state, running read-only git commands and delegating file reading to the assistant.
model:
use: anthropic
fallback: [openai/gpt-6-luna]
tools:
harness: [read, exec]
subagents:
- ref: assistant@^1.0
description: Hand the assistant a question that needs files read and summarized.
budget:
max_iterations: 4
timeout: 2m
approval:
allow:
- Bash(git status:*)
- Bash(git log:*)
- Bash(git diff:*)
deny:
- Bash(git push:*)
- Bash(rm:*)
grant: tool
deny_after: 2
compaction:
strategy: clear_tool_results
keep_tool_results: 4
limits:
max_iterations: 10
budget:
max_cost: 0.25
---
You look after a git repository and answer questions about its state.
Use shell commands through execute_code with language shell for git: status,
log and diff run without asking, and anything else waits for a person to
approve it. Never push and never delete files.
When a question needs the contents of files rather than git history, delegate
it to the assistant and use its answer. Reply with a short summary and the
commands you ran.
File format¶
The file starts with a --- line, then YAML frontmatter, then a closing --- line. Everything after it is the system prompt. saige agent schema prints the JSON Schema of the frontmatter (also checked in as agent/definition/definition.schema.json) for editors.
Decoding is strict, as for the model catalog: an unknown key (with a suggestion for a likely typo), a duplicate key, a value of the wrong kind, null, and YAML anchors, aliases, tags and merge keys are errors. Every error names the file, the line and the field path, such as reviewer.agent.md: line 12: skills[1].mode: "lazzy" is not one of lazy, eager, pinned, search, trigger; did you mean "lazy"?.
The digest is sha256: over the file with line endings normalized, so a checkout with CRLF endings has the same digest.
| Field | Meaning |
|---|---|
apiVersion |
Required. saige/v1; any other value is rejected |
name |
Required. Lowercase letters, digits and hyphens, starting with a letter, at most 48 characters. Also the agent's name at run time |
version |
Required. A semantic version such as 1.4.0 |
description |
What the agent is for. A parent shows it in the sub-agent's tool |
model |
A catalog preset name or provider/model (vertex/ selects Vertex AI), or an object with use and a fallback list of provider/model. A fallback without credentials is dropped with a warning |
dials |
Dials: creativity, reasoning, max_output, tools, parallel, reproducible, cache |
tools |
harness groups (read, write, exec, web), mcp servers by the host's name for them (with an optional allow list of remote tool names), and registry tools by name |
skills |
Skill names, or objects with name, mode, triggers and hash (see below) |
memory |
store (a store the host names), recall (tool, inject, select or off), write kinds, budget, retention, namespace, read_only |
subagents |
References name@range, or objects with ref, mode (delegate, spawn or handoff), description and budget (max_iterations, timeout, max_cost, max_tokens, max_requests) |
approval |
capabilities, allow, ask and deny rules, grant, deny_after, ramp_after, hide_denied (see below) |
compaction |
The catalog's compaction form: strategy and its parameters, or a chain (see context management) |
guardrails |
input and output lists of built-ins: pii, regex (with patterns of label and expr), max_length (with max), classifier (with policy); redact and parallel where they apply |
limits |
max_iterations, llm_timeout, tool_timeout, and a budget with max_cost, max_tokens, max_requests, warn_at, on_exceed (stop or ask), allow_unpriced |
metadata |
Free-form strings. Never changes behavior |
Skill modes¶
| Mode | How the skill reaches the model |
|---|---|
lazy (default) |
Listed in the system prompt; the model loads it with load_skill |
eager |
Its instructions are in the system prompt, from the snapshot taken at bind time |
pinned |
eager for one exact snapshot: the skill's hash must equal hash, or binding fails. saige agent show prints the hash |
search |
Left out of the prompt; the model finds it with search_skills |
trigger |
Listed like lazy, and its instructions are put in front of any user message that matches one of triggers (Go regular expressions) |
Only the skills a definition names are reachable, as skills.AllowNames makes them. Skills supply content and never grant permission (D-28).
Approval rules¶
Rules use the permission syntax of Claude Code. A rule is a tool name, optionally ending in *, with an optional specifier in parentheses:
| Rule | Covers |
|---|---|
read_file |
Every call of read_file |
mcp_github_* |
Every tool whose name starts with mcp_github_ |
Bash(git status:*) |
Shell commands that start with git status, through bash or execute_code with language shell |
Bash(npm test) |
Exactly the command npm test |
Read(src/**) |
File tools reading a path under src/ |
WebFetch(domain:go.dev) |
fetch_url for go.dev and its subdomains |
deploy(env:staging) |
Calls of deploy whose env argument is staging |
deploy(branch:fix/*) |
Calls whose branch argument starts with fix/ |
deploy(dir:/srv/app/**) |
Calls whose dir argument is a path at or below /srv/app |
The Claude Code names Bash, Read, Write, Edit, Glob, Grep, LS and WebFetch name saige's bash and execute_code, read_file, write_file, edit_file, glob, grep, list_dir and fetch_url.
Any other tool, including a registry or MCP tool, takes a field:pattern specifier that is matched against one argument. The pattern is an exact value (3 and true match a number and a boolean), a text prefix ending in *, or a path prefix ending in /**. Dots in the field step into nested objects, as in deploy(target.env:staging), and a call without the argument never matches. Use the /** form for paths: it cleans the value first, so /srv/app/../etc does not match /srv/app/**, where a * prefix compares the text as written.
A call is decided in this order: a deny rule refuses it, an ask rule asks, an allow rule runs it, a tool that carried an approval marker asks, and anything else falls to its capability class. capabilities sets the class defaults; without it reads run and writes, destructive and undeclared tools ask.
An allow rule matches a shell command only when it is one simple command, so Bash(git status:*) never allows git status && rm -rf ~, git status; curl … or a command with a redirect or substitution: those ask. ask and deny rules match when any command in a compound one matches.
With an approval block the tools give their approval markers to the gate, so an allow rule can run execute_code without a prompt. Delegating to a sub-agent is never held; the sub-agent's own calls are. The host's own gate (Env.ToolGate) still applies to every call.
grant caps the scope a person may attach to an approval (approval policy): once, args, tool or session. deny_after, ramp_after and hide_denied map onto agent.ApprovalPolicy.
Sources and layers¶
| Source | Reads |
|---|---|
DirSource(dir) |
Every *.agent.md under dir, recursively, and every .md file directly inside a directory named agents. The walk is confined to dir |
FSSource(name, fsys, root) |
The same files in an fs.FS, such as definitions compiled in with embed |
ReaderSource(name, open) |
One file from any reader: an object store, a blob, a fixture |
HTTPSource(url, opts) |
One file over HTTPS, with ETag and If-None-Match so an unchanged file costs a 304 |
pgsource.New(pool, notifier) |
Rows of saige_agent_definitions (name, version, body, digest) |
Layered(sources...) |
Its sources lowest first. A later definition with the same name and version replaces an earlier one; other versions stay side by side |
Untrusted(src) marks a source whose definitions arrived with a cloned repository. Such a definition is checked against the allowlist in definition.UntrustedFields, as an untrusted catalog layer is. It may not set tools.mcp, memory, dials, compaction, approval.allow, approval.capabilities, approval.ramp_after or limits.budget.allow_unpriced, and it may use only the read and write harness groups. A field added to the format stays closed to untrusted definitions until someone decides.
Postgres¶
postgres.RunMigrations creates saige_agent_definitions and a trigger that announces every change on the saige_agent_definitions channel, including edits made with plain SQL. Source.Put parses a definition before it writes anything, and Load rejects a row whose body does not match its name, version or digest.
notifier := postgres.NewNotifier(pool, postgres.NotifierOptions{})
src := pgsource.New(pool, notifier)
reg := definition.NewRegistry(src, definition.Checks{})
if _, err := reg.Load(ctx); err != nil { ... }
stop, err := reg.Watch(ctx, definition.WatchOptions{}) // reloads on NOTIFY
Resolution and pinning¶
Registry.Resolve("reviewer@^1.2") returns the highest version the range admits. Ranges use npm syntax: exact (1.2.3), partial (1.2, 1.x), caret (^1.2), tilde (~1.2.3), comparators (>=1.0.0 <2.0.0), hyphen ranges and ||. A pre-release matches only a range that names a pre-release of the same version.
Load checks the whole set before it replaces what the registry holds: every sub-agent reference resolves, there is no cycle, and the Checks you pass accept every model and skill (bind.ModelCheck and bind.SkillCheck check them against a catalog and a skill catalog). A failed reload keeps the previous set. The errors name what is missing and what is available:
invalid agent definition lead@1.0.0: subagents[0].ref: no version of helper matches "^2" (available: 1.4.0, 1.0.0)
invalid agent definition a@1.0.0: subagents: sub-agent cycle: a@1.0.0 -> b@1.0.0 -> a@1.0.0
A resolution is pinned. Its Digest covers the definition and every sub-agent it resolved to, and a reload never changes a Resolved already handed out, so a running agent keeps the definition it started with. Registry.Pinned(digest) finds the same resolution again. bind.Bound.Pin() returns the name, version and digest to record with a run; saige serve --agent returns it as agent when a session is created.
Registry.Watch reloads when the source is a Watcher (Postgres with a notifier) and every WatchOptions.Interval otherwise.
Binding¶
res, err := reg.Resolve("repo-steward@^1")
b, err := bind.Bind(ctx, res, bind.Env{
Catalog: catalog.Default(),
Harness: tools.HarnessOptions{Root: "."},
Skills: skillCatalog,
})
defer b.Close(ctx)
a, err := b.NewAgent()
| Definition | Becomes |
|---|---|
model |
A preset.Build bundle, applied with agent.WithPreset. Env.Preset overrides the root agent's model |
dials |
agent.Config.Dials |
tools.harness |
A tools.Harness toolset under Env.Harness.Root, one per agent |
tools.mcp |
An mcp.Pool over Env.MCPServers, its tools and its gate. allow may only narrow the host's own allow list |
tools.registry |
Tools from Env.Tools |
skills |
The skill tools and prompt section over Env.Skills; a UserInput hook for triggers |
memory |
memory.Tools over Env.MemoryStores and Env.MemoryScope; a UserInput hook for inject and select |
subagents |
agent.SubAgentDef (delegate, spawn) or agent.HandoffDef (handoff) |
approval |
A ToolGate behind Env.ToolGate, and agent.ApprovalPolicy |
compaction |
agent.Config.CompactCfg |
guardrails |
agent.InputGuardrail and agent.OutputGuardrail from agent/guardrail; a classifier runs on the agent's model |
limits |
MaxIter, LLMTimeout, ToolTimeout, and a types.Budget. Each Bound.NewAgent call, and each delegation, gets a budget of its own |
A sub-agent inherits its parent's run policy as every sub-agent does (see delegation), and its own definition replaces what it declares: its approval rules (still behind the host's gate), compaction, dials, timeouts and budget. A sub-agent with no approval block keeps its parent's. A handoff member shares its entry agent's run, so a definition used with mode: handoff may not declare approval, skills, memory, compaction, guardrails, MCP servers, sub-agents, a budget or timeouts; binding says which.
Everything a definition names by reference must be in the Env. A missing preset, tool, MCP server, skill catalog or memory store fails with bind.ErrUnsupported and says what is missing.
CLI¶
Directories are searched lowest precedence first: ~/.config/saige/agents, the project's .saige/agents (untrusted unless SAIGE_TRUST_PROJECT_AGENTS=1, or named with --agents-dir), then each --agents-dir.
saige agent list # every definition, highest version first
saige agent show repo-steward@^1 # source, digests, sub-agents, skill hashes, the file
saige agent validate [PATH...] # offline checks; exits 2 when anything is invalid
saige agent schema # JSON Schema of the frontmatter
saige agent run --agent assistant "question" # also serve
saige agent run --agent repo-steward --model claude-haiku-5-5 --provider anthropic "question"
saige serve --agent repo-steward --workspace . --agents-reload 10s
saige agent run --agent researcher --mcp-config .mcp.json "question"
With --agent, the harness tools work under --workspace with the CLI's sandbox flags, registry tools come from --rag-db and --kg-db, MCP servers from --mcp-config, and skills from .agents/skills, .claude/skills, Cursor rules (.cursor/rules/*.mdc and .cursorrules), ~/.agents/skills and ~/.claude/skills. --preset, --model and --provider override the definition's model; --tools and --system cannot be combined with --agent. The CLI provides no memory store, so a definition with a memory block runs only in a host that provides one. saige serve --agent binds a fresh agent for each session from the definition the registry resolves when the session starts; --agents-reload lets new sessions see edits while running sessions keep their pin.
saige-mcp --agents-dir DIR --agent NAME publishes the definition as the agent tool, named after the definition unless --agent-tool says otherwise. Its harness tools work under --root, and its registry tools are the packs the server exposes. A name the directory does not hold falls back to a preset or provider/model, as before. Each call binds the pinned resolution afresh, so calls share no scratch workspace or budget.