> ## 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 agent configuration
2. **Publish** the draft to freeze it and make it live
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"}
# Test against a draft version
aui apollo create-thread --version-id draft_abc123

# Production uses the active version
aui apollo create-thread
```

<Note>
  Agent configuration (entities, parameters, rules, tools, integrations) is versioned. 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>