> ## 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 accounts and provides the overarching identity for all agents within it.

## Account

A workspace for a team or project. Each account lives within an organization and houses multiple agents. Accounts 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 an account 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** — Locked snapshot. Once published, a version becomes immutable and can be activated for production use.
* **Active** — The live version users interact with. Only one version can be active at a time.
* **Archived** — Preserved but inactive. Archived versions remain in history but are not available for activation.

**Version Lifecycle:**

1. Create a **draft** version and edit agent configuration
2. **Publish** the draft when ready (locks it permanently)
3. **Activate** the published version to make it live
4. **Archive** old versions to clean up while preserving history

```
Organization
├── Account A
│   ├── Agent 1
│   │   ├── Version v1.0 (Active)
│   │   ├── Version v1.1 (Published)
│   │   ├── Version v2.0 (Draft)
│   │   └── Version v0.9 (Archived)
│   └── Agent 2
│       ├── Version v1.0 (Active)
│       └── Version v1.1 (Draft)
└── Account 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 active version is used

This enables testing changes before promotion:

```bash theme={null}
# 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 active version until you publish and activate.
</Note>