YAML configuration

Declaring agents, models and tool directories in a file.

Agent identity — model, prompt, which tools it may call — is configuration. Behaviour stays in Python.

# agents.yml
agents:
  reviewer:
    model: gpt-5.4-codex
    instructions_file: prompts/reviewer.md
    tools: [read_file, grep, shell]
    knowledge:
      dir: ./knowledge

agentino run agents.yml                    # REPL
agentino run agents.yml --agent reviewer   # pick one
agentino run agents.yml -m "Review PR #42" # one shot
agentino run agents.yml --serve 8080       # HTTP

Why the split

The things you change while tuning an agent — the wording of a prompt, which model it runs on, how many turns it gets — are the things you want to change without a deploy, and the things a non-Python colleague can reasonably own. The things you change while building a capability are functions.

So a new prompt is a text edit. A new capability is a new decorated function. Neither requires touching the other.

Environment interpolation

Any value can reference the environment:

model: ${AGENT_MODEL:-gpt-5.4-codex}
api_key: ${AI_API_KEY}

${VAR:-default} expands at load time. This is how one config file runs in a sandbox and in production without a branch — and why no deployment-specific variable name is baked into either package.

Tool discovery

tools: takes either a list of names or a directory path. A directory is scanned for @tool-decorated functions and all of them are offered. A list names them explicitly, which is what you want when several agents share one directory and should not share all of it.

Every per-agent key

	Default
`instructions`	—	The prompt, inline
`instructions_file`	—	The prompt, in its own file — better, because prompts get long
`model`	provider default	A name, or a mapping with `primary` and `fallbacks`
`provider`	detected	`openai`, `openai-codex` or `anthropic`
`base_url` · `api_key`	from the environment	Endpoint for this agent alone
`auth`	—	`setup-token` to use a stored OAuth credential instead of a key
`temperature`	`0.7`
`max_turns`	`20`	Cap on the tool-calling loop
`tool_result_cap`	`4000`	Characters of a tool result the model sees
`require_tool_use`	`false`	Reject a turn that answers without calling a tool
`tools`	—	Names, or a directory
`tools_dir`	—	Directory, when you also want a name list
`tool_description` · `tool_description_file`	—	How this agent is described when another agent can call it
`tool_instructions`	—	Extra instructions injected around tool use
`sanitize`	—	Argument sanitisers applied before a tool runs. `sanitize.path_args` lists the parameters that hold a path, so they are checked for traversal before the tool sees them
`skills` · `skills_dir`	—	Named skills to load, and where from
`context_files`	—	Files pasted into the prompt at load
`knowledge`	—	Retrieval settings, below

A defaults: block at the top of the file supplies any of these for every agent, and an agent's own value wins.

Knowledge

	Default
`dir`	—	Directory of markdown to index
`top_k`	`5`	Passages returned per search
`min_score`	—	Floor below which a match is dropped
`dense_weight`	—	Balance between TF-IDF and embedding scores
`language_boost`	—	Weight for matching the query's language
`embedding_base_url` · `embedding_api_key` · `embedding_model`	—	Embedding endpoint for this agent

agents:
  support:
    instructions_file: prompts/support.md
    max_turns: 12
    require_tool_use: true
    knowledge:
      dir: ./knowledge
      top_k: 8
      dense_weight: 0.6