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 unless one of its revisions is made live.
- Published — Frozen snapshot that takes no more revisions (the CLI shows this state as
locked). Publishing a version makes its newest revision the agent’s live revision — the one conversations run against. - Archived — Preserved but retired. Archived versions remain in history; the version holding the live revision can’t be archived.
- Create a draft version and edit the agent’s program — every
apollo pushmints a new revision of it, addressed by its tag (e.g.v3.2) - Publish the draft to freeze it and make it live — pushing is not publishing
- Publish another version to switch or roll back — re-publishing a previous version re-activates it
- Archive old versions to clean up while preserving history
apollo version live <tag> makes one exact revision live — any revision of a version that isn’t archived, an older one included, which is also the rollback — and apollo version lock freezes a version without changing what callers get. (The CLI’s own help calls these apollo branch commands; it’s the same command.)
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.14to reference revisions - Default behavior — If no version is specified, the agent’s live version is used
The whole 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 callers until you publish it — or, from the CLI, make one of its revisions live.