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 |
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.