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:

# Test against a draft version
aui apollo create-thread --version-id draft_abc123

# Production uses the active version
aui apollo create-thread

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.