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

# Agent Hierarchy

> Understanding Apollo-1's three-level organizational structure

Apollo-1 organizes agents across three levels, providing a clear separation of scope and configuration.

## Organization

The top-level entity representing your company. An organization contains multiple projects and provides the overarching identity for all agents within it.

## Project

A workspace for a team or product. Each project lives within an organization and houses multiple agents. Projects allow teams to manage their own set of agents independently.

## Agent

An individual conversational AI with its own configuration, settings, entities, and tools. Each agent operates within a project and represents a specific use case or domain.

### Agent Versions

Every agent has multiple versions that track changes to its configuration over time. Versions enable safe iteration, testing, and deployment of agent behavior.

**Version States:**

* **Draft** — Editable working version. You can modify configuration, test changes, and iterate freely. Not live.
* **Published** — Frozen snapshot. Exactly one published version is the agent's **live** version — the one conversations run against.
* **Archived** — Preserved but retired. Archived versions remain in history; the live version can't be archived.

**Version Lifecycle:**

1. Create a **draft** version and edit the agent's program — every `apollo push` mints a new draft version, addressed by its tag (e.g. `v3.2`)
2. **Publish** the draft to freeze it and make it live — pushing is not publishing
3. Publish another version to switch or roll back — re-publishing a previous version re-activates it
4. **Archive** old versions to clean up while preserving history

```
Organization
├── Project A
│   ├── Agent 1
│   │   ├── Version v1.0 (Published — live)
│   │   ├── Version v1.1 (Published)
│   │   ├── Version v2.0 (Draft)
│   │   └── Version v0.9 (Archived)
│   └── Agent 2
│       ├── Version v1.0 (Published — live)
│       └── Version v1.1 (Draft)
└── Project B
    ├── Agent 3
    └── Agent 4
```

### Version Pinning

When creating conversation threads or sending messages, you can pin to specific versions:

* **By version ID** — Pin to a specific draft or published version
* **By version tag** — Use semantic labels like `v8.14` to reference revisions
* **Default behavior** — If no version is specified, the agent's live version is used

This enables testing changes before promotion:

```bash theme={"dark"}
# Bind the checkout to a draft tag, then chat against it
apollo version use v2.0
apollo chat "Where is my order?"

# Without a bound tag, sends target the agent's live version
```

<Note>
  The whole [program](/overview/agent-program) — vocabulary, capabilities, policies, sources — is versioned together. When you edit an agent, you're editing a specific version. Changes to a draft don't affect the live version until you publish it.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.