How to Configure Policies

Policies are cross-cutting settings that affect multiple lifecycle phases simultaneously. Unlike providers — which each own a single phase — a policy coordinates behavior across tools, instructions, and post-processing.

Policies live at the top level of agent_setups.json, not nested under any provider. For the full JSON schema, see the Agent Configuration Reference.

List Policies

za agents policies list

Policy	Description
Citations	Controls how the agent references search results in responses
Model	Selects a named LLM configuration for the request, within the setup's allowed names

---

Model

The model policy selects which named LLM configuration a request runs on. It is the only channel through which model choice travels at runtime, and it carries a name, never a configuration.

"llm_selection_configuration": { "llm_configuration_name": "fast" }

Selection rules:

• The agent's default is its own llm_configuration_name. A requested name is honored only when it is the default or listed in the setup's allowed_llm_configuration_names; otherwise the default applies.
• Pinned in the agent's configuration, the block cannot be moved by callers. Left out, callers may supply it per request through bot_params, and a parent agent may pass it to a sub-agent the same way; each agent validates against its own allowed names.
• Every LLM consumer in the request follows the selection: the agent's own client and every LLM-using tool.
• The task and delegate tools expose an llm_configuration_name parameter to the agent when the configurator opts in (allow_llm_selection on sub_agent_tool_source_configuration, agent_delegation_provider_configuration, or per delegable agent).

za agents policies show model
za agents policies configure model

---

Citations

Citation policy controls how the agent references search results in its responses. It spans three phases:

Phase	What happens
🔧 Tools	IndexToolsSource registers each search hit in the CitationStore
📋 Prompt	CitationInstructionSource tells the LLM how to format references
📝 Post-process	CitationProcessor resolves citation markers into structured evidence

All three components share the same CitationConfiguration instance through DI — changing the strategy changes behavior across all phases at once.

za agents policies show citations        # show citation fields, current values, defaults
za agents policies configure citations   # interactively set citation strategy

Available Strategies

Strategy	How it works	When to use
inline_url	LLM cites as [[N]](url "extract")	Production default — web UIs that render markdown
short_id	LLM uses 8-char hex IDs; processor resolves to URLs	When URLs are too long for context
deferred	LLM writes naturally; processor matches text to results	When you want clean prose with citations added after
sup_numeric	LLM uses superscript [^N] notation	Academic-style footnotes

How It Works

The CitationStore is a request-scoped singleton — the same instance is shared by all components within a single request. During tool execution, every search hit is registered with its metadata, short ID, and source URL. After the LLM generates its response, the CitationProcessor reads from the same store to resolve inline markers into structured evidence objects with source URLs, page ranges, and relevance scores.

The citation instruction source reads the configured strategy and injects the appropriate formatting rules into the system prompt, so the LLM knows which citation format to use.

For architecture details, see Cross-Cutting Concerns.