Agents, organizations, and projects

An agent is a long-lived software identity in an Extrovert project. Humans sign in to the console. Agents use limited agent keys or an OAuth grant and never receive a human session.

Resource hierarchy

organization
└── project
    ├── agents
    │   └── inboxes
    ├── credentials
    ├── domains
    ├── webhooks
    ├── review requests
    └── writing rules

The organization owns membership, plan capacity, billing, and organization-wide settings.
A project is the resource namespace for agents, credentials, inboxes, domains, and Review Loop state.
An agent owns inboxes and performs actions through one or more limited keys.

Every account starts with a default project. A request’s organization, project, and customer identity are derived from the credential. Client input cannot switch them. Cross-project and cross-organization resource lookups return 404 instead of revealing whether another resource exists.

Call whoami to inspect the key’s fixed org_id, project_id, agent id, key id, and permissions. server-enforced

Create or connect an agent

The console distinguishes two credential jobs:

Credential	Use it when	What happens
Enrollment key	Setup needs to create the agent	Redeeming the key creates or finds the agent by `agent_handle`, then returns an agent key
API key	The agent already exists	The console creates another limited key for that agent

Enrollment redemption is idempotent on agent_handle. A runtime can redeem with the same handle after a restart without creating a duplicate agent.

Ownership and access

Resource	Ownership rule
Inbox	Owned by the creating agent and stored in its project
Agent key	Bound to one agent and a fixed organization, project, or inbox ceiling
Review request	Bound to the composing agent, inbox, and project
Audit event	Records the actor type, agent id, key id, action, and affected resource

An agent cannot use project membership alone to open another agent’s inbox. Ownership checks apply in addition to project and organization checks.

Lifecycle

Agents are active or disabled. Disabling an agent stops its keys from creating inboxes or sending mail. Existing inboxes remain until they are deleted. Re-enabling the agent restores its existing key access unless a key was revoked separately.

Revoking an enrollment key stops future redemption but does not revoke agent keys already issued from it. Revoke the agent keys or disable the agent when existing access must stop.