Choose a model provider

An agent’s model is a single string in agent.toml, written as provider/model-id:

[agent]
model = "openai/gpt-4o-mini"

The part before the / selects the backend; the part after is passed to that backend as the model id. maiden wraps every backend behind one Provider seam, so the agent loop is identical no matter which you pick.

OpenAI

model = "openai/gpt-4o-mini"

Requires OPENAI_API_KEY in the environment. maiden uses the Chat Completions API, which round-trips the tool-call IDs maiden’s manual loop supplies.

export OPENAI_API_KEY="sk-..."
maiden run my-agent "hello"

Anthropic

model = "anthropic/claude-3-5-sonnet-latest"

Requires ANTHROPIC_API_KEY in the environment. The Anthropic backend sets a max_tokens ceiling on each request (the Messages API requires one).

Caution

The Anthropic backend compiles and routes, but has not yet been verified against a live key. Treat it as experimental until it has real-world coverage.

Override at run time

--model overrides the model in agent.toml for the top-level agent (it does not propagate into subagents, which keep their own):

maiden run my-agent "hello" --model "openai/gpt-4o"

Run offline with the mock

The --mock flag bypasses every real backend with a scripted provider — no API key, no network, fully deterministic. It calls the agent’s first tool once, then returns a final answer quoting the tool’s output. It’s what powers offline runs and reproducible evals:

maiden run my-agent "echo hello" --mock
maiden eval my-agent --mock

Streaming

Both real backends stream tokens over SSE. A backend without native streaming still drives the same path by emitting the final answer as one token, so streaming behaves consistently across providers.

Adding another provider

Because backends live behind the Provider seam, adding one is contained: wrap its client, map maiden’s conversation to its request, and route a new provider/ prefix to it. Nothing in the runtime, serving, or tool layers has to change.