> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.
# The Agent Program
> An agent is a folder of typed YAML that states a business — what it can know, what it may do, what it must never do, and what it says.
An Apollo-1 agent **is its program**: a folder of typed YAML files that states a business, not a runtime. You never describe stages, prompts, or models. You describe what the agent can **know**, what it may **do**, what it must **never** do, and what it **says** — and the runtime turns that into behavior, turn by turn.
Each concern lives in its own file, so the program stays readable end to end:
| File | What it states |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `program.yaml` | Who the agent **is** — identity, voice, welcome, caller context (the only required file) |
| `vocabulary.yaml` | The **nouns** — the [facts and records](/overview/vocabulary) the agent can know and hold |
| `sources.yaml` | Where facts come from and what changes the world — every read and write |
| `derivations.yaml` | [Facts worked out from other facts](/overview/derivations) — business arithmetic, thresholds, lookups |
| `situations.yaml` | Standing truths about the world, projected as `state.*` for gates to read |
| `capabilities/` | One folder per thing the agent can **do** — see [Capabilities & Policies](/overview/capabilities-and-policies) |
| `policies/` | The gates and guardrails — what must hold before an action proceeds |
| `connections.yaml` | Live wiring for sources (endpoints, auth, knowledge hubs); credential values stay in the vault |
A handful of more specialized files cover advanced ground — conversation places, procedures, plans, approval chains, org roles — but every program starts with the table above, and only `program.yaml` is required.
## Identity: `program.yaml`
`program.yaml` holds what the agent *is*, not what it can do:
```yaml theme={"dark"}
id: returns-desk
caller:
fields: [customer.id]
context:
given: [customer.id] # supplied by the host at session open
voice:
tone: >
Warm and direct. Lead with the answer, then the reason.
never_say: [ "as an AI", "unfortunately" ]
welcome:
say: "Hi! I can help with returns, refunds, and order status."
```
* **`voice`** — the agent's register: `tone`, `brevity`, and phrases it must `never_say`.
* **`welcome`** — the opening line, before the caller says anything.
* **`caller` and `context`** — who is on the line and which facts the host supplies at session open (`given`), refreshes, or loads.
* **`clock`** — what "today" means when rules are read against dates.
## Where the goal and guardrails live
There is no goal prompt. What the agent does is stated by its **capabilities**, each with its own intent; what it must never do is stated by its **policies and obligations** — enforced predicates, not advisory text. That separation is the point: identity is declared once, behavior is declared per capability, and constraints are rules the runtime evaluates rather than suggestions a model may forget.
## How the parts meet at runtime
A caller's message is routed to a capability by its `use_when`. The capability names the facts it `needs`; the runtime establishes them — from context, from sources, from derivations, or by asking the caller in the fact's own words. Policies gate the action before it proceeds, obligations check the reply before it ships, and every decision lands in the trace with the rule that produced it.
Facts and records — the nouns everything else is built on.
What the agent can do, and the gates that govern it.