Read how it is designed before it ships.
Concepts, data model, API design and error codes, published early so that engineers can tell us what is wrong with them.
Status of this documentation
This is a design preview. It describes how AEGIS is intended to work, so engineers can evaluate and challenge the design. No public API, SDK or package exists yet. Everything here may change.
| Material | Status |
|---|---|
| Core concepts, data model and invariants | Preview |
| REST API design and error codes | Preview |
| Quickstart, tutorials and SDK reference | Documentation in development |
| Interactive demo | Simulated |
Core concepts
- Agent
- A stable identity with immutable versions. A version holds instructions, a model route, tool grants, requested authority and limits.
- Objective
- What a principal asked for, with its stated limits. It is the starting point of an execution.
- Plan
- A versioned, validated graph of steps compiled from an objective. Replanning creates a new version.
- Step
- One unit of work assigned to one agent version, with inputs, dependencies and a failure policy.
- Mandate
- The authority granted to a step: tools, resources, amount limits, data classes and a time limit. A child must be a subset of its parent.
- Action
- A concrete, side-effecting tool call in canonical form, with a digest and an idempotency key.
- Decision
- The result of checking an action: allow, require_approval or deny, with the rule, Mandate and reason code.
- Approval
- A human decision bound to an action digest. It expires and can be used only once.
- Execution Record
- The ordered, tamper-evident event log. State, traces, audit and replay all derive from it.
- Route
- A named model choice with ordered fallbacks and a budget. Agents reference routes rather than vendors.
- Governed step
- One model call or tool action processed through the gateway, with a recorded decision. The proposed billing unit.
Getting started structure
The intended first path through the product. These steps cannot be followed yet, since no account or API exists.
- Create a project. Each project has dev and production environments.
- Run the sample. Run the invoice sample with synthetic tools and no keys.
- Hit a gate. See a denial and an approval, and approve an exact action.
- Add a model provider. Use your own key, then create a route.
- Register a read-only tool. Test it through the gateway.
- Publish an agent version. Give it the route and the tool.
- Submit a task from code. Follow its event stream and handle a denial.
- Inspect the record. Open the Mandate Map and verify the chain.
Data model
Every tenant table carries an organization key. Versions are immutable, and execution_event is the source of truth.
| Domain | Entities |
|---|---|
| Tenancy | organization, user, membership, role, project, environment, api_key |
| Build | agent, agent_version, model_provider, model, model_route, tool, tool_version, integration, credential, orchestration, orchestration_version |
| Run | session, execution, execution_plan, step, step_attempt, action, execution_event |
| Control | mandate, policy, policy_version, decision, approval, audit_event |
| Knowledge (Phase 2) | knowledge_source, document_chunk, memory_record |
| Assure | trace_span, eval_suite, eval_case, eval_run, evaluation_result |
| Commercial | usage_record, subscription |
Invariants
Properties the system must always hold. They are planned as the first automated tests.
- A child Mandate scope is always a subset of its parent.
- No tool call happens without a committed decision.
- An approval applies only to a matching digest, before expiry, once.
- A non-idempotent action with an unknown outcome is never automatically re-executed.
- Event sequence numbers are gapless within an execution, and each previous digest matches.
- A request under one tenant returns no rows from another tenant.
- Published agent and policy versions never change.
API overview
REST and JSON over HTTPS, with bearer keys scoped to a project and environment, idempotency keys on creating requests, cursor pagination and server-sent events for streams. Proposed design. No public endpoint exists.
| Resource | Responsibility | Operations |
|---|---|---|
| /v1/agents | Stable agent identities | POST, GET, GET /{id}, PATCH /{id}, POST /{id}/archive |
| /v1/agents/{id}/versions | Immutable configuration | POST, GET, POST /{v}/publish, POST /{v}/test |
| /v1/orchestrations | Reusable plan definitions | POST, GET, POST /{id}/versions, POST /{id}/versions/{v}/validate |
| /v1/tasks | Submit an objective with a requested Mandate | POST (returns an execution id), GET /{id} |
| /v1/executions | Runs and control | GET, GET /{id}, GET /{id}/plan, GET /{id}/steps, GET /{id}/events, POST /{id}/cancel, POST /{id}/retry, POST /{id}/steps/{s}/reconcile |
| /v1/mandates | Inspect and simulate authority | GET /{id}, GET /{id}/lineage, POST /derive:dry-run |
| /v1/tools | Tool definitions | POST, GET, POST /{id}/versions, POST /{id}/test, POST /{id}/grants |
| /v1/integrations | Connections and credentials | POST, GET, POST /{id}/credential (write only), POST /{id}/rotate, POST /{id}/discover |
| /v1/models | Providers and routes | GET, POST /providers, POST /routes, POST /routes/{id}/test |
| /v1/memory | Sources, records, retrieval (Phase 2) | POST /sources, POST /records, POST /query, DELETE /records/{id} |
| /v1/policies | Policy as code | POST, POST /{id}/versions, POST /{id}/versions/{v}/activate, POST /simulate |
| /v1/approvals | Human queue | GET, GET /{id}, POST /{id}/approve, POST /{id}/reject |
| /v1/traces | Read model of runs | GET /{execution_id}, GET /{execution_id}/spans, POST /export |
| /v1/evaluations | Suites and runs (Phase 2) | POST /suites, POST /suites/{id}/cases, POST /runs, GET /runs/{id} |
| /v1/audit | The ledger | GET /events, POST /exports, GET /verify |
| /v1/usage | Metering | GET /summary, GET /by-project, GET /by-model |
Proposed webhooks: execution.completed, execution.failed, approval.requested, approval.resolved, step.outcome_unknown, policy.activated.
Error codes
Stable codes with a clear next step. Good error codes are part of how a developer learns the model.
| Code | When | What to do |
|---|---|---|
| mandate_exceeded | The action or delegation goes beyond the Mandate. | Fix the plan or request narrower work. Do not retry. |
| policy_denied | A policy rule denied the action. | Read the reason. Do not retry unchanged. |
| approval_required | A person must decide first. | The step parks. Listen for approval.resolved. |
| approval_hash_mismatch | The action differs from what was approved. | Request a new approval. |
| approval_expired | The approval lapsed before use. | Request a new approval. |
| outcome_unknown | A non-idempotent call may or may not have applied. | A person reconciles it. Never retried automatically. |
| budget_exceeded | A run or project budget is used up. | Raise the budget, or change the route. |
| provider_unavailable | No model in the route could serve the call. | Retry later, or add a fallback. |
| tool_timeout | A tool did not respond in time. | Handled according to the tool's retry class. |
SDK roadmap
| Item | Status | Note |
|---|---|---|
| REST API design | Preview | Readable on this site. Not a live service. |
| Python SDK | Coming soon | Generated from the API definition. |
| TypeScript SDK | Coming soon | Generated from the API definition. |
| Sandbox with synthetic tools | Coming soon | No credentials needed. |
| Framework adapter (LangGraph first) | Planned | Phase 2. |
| CLI | Planned | Later phase. |