Agents
An agent is the actor. It is the unit of identity, governance, versioning, and execution — everything else (tools, connectors, skills, knowledge) is something an agent is granted or attached to.
The definition: Agent.md
An agent is defined by a markdown file with YAML frontmatter. The frontmatter declares capability; the body is the agent's role and instructions.
---
name: exec-assistant
description: Schedules meetings and keeps the calendar tidy.
model: default # a tier (default/cheap/strong) or a concrete model id
tools: # built-in tools + connectors this agent may call
- calendar
- current_time
skills: # reusable playbooks
- schedule-meeting
knowledge: # attached knowledge collections (enables search_knowledge)
- team-handbook
memory: user # user | agent | user+agent | none
autonomy: supervised # supervised | trusted | autonomous
---
# Role
You are an executive assistant. Book meetings, protect focus time, and
always confirm a proposed slot with the user before creating an event.
| Field | Purpose |
|---|---|
model | A routing tier (default, cheap, strong) or a concrete model id. Tiers let the org re-point models without editing agents. |
tools | Declarable built-in tools and connectors. This is the grant — nothing outside this list is callable. |
skills | Attached playbooks. Also switches on load_skill and run_skill_script. |
knowledge | Knowledge collections. Switches on search_knowledge and the citation contract. |
memory | Memory scope. Switches on remember / recall. |
mcp_servers | References to registered MCP servers in the Tools Library. |
autonomy | How much the agent may do without a human. Capped by the org's autonomy floor. |
Authoring a new agent
There are three ways to create an agent, and all of them produce the same
thing — a versioned Agent.md:
- The Agent Designer — compose it visually, or let the built-in Architect interview you and draft it. See the Agent Designer.
- The editor — write
Agent.mddirectly with live validation. - A template — start from a governance-ready template that already bundles a starter eval set, so it can pass the promotion floors on day one.
Whichever you use, the agent is created in your personal workspace at version 1, and a security scan runs on it automatically. Nothing is shared until you promote it. The usual path from here is: author → test and certify in the Playground → promote through team and org rings (Build & promote).
Agent.md,
which is what makes agents diffable, reviewable, and portable.
Kinds of agent
| Kind | Description |
|---|---|
| native | The normal case: an Agent.md running on the platform. |
| orchestrator | Built-in supervisor. Plans a goal, routes each step to the best visible agent, then synthesizes the result. It delegates rather than calling tools itself. |
| a2a | A remote agent registered from a signed agent card, invoked over the A2A protocol. It gets the same runs, budget, and kill-switch parity as a native agent. |
| architect | A meta-agent that helps author new Agent.md definitions. It drafts into a buffer and validates — it never saves to the registry itself. |
Rings and visibility
Every agent lives in a ring, which determines who can see and run it: personal → team → org → public. Visibility is enforced in the data layer, not in the UI: a repository query simply cannot return an agent the caller may not see. This holds everywhere — catalog search, the orchestrator's router, and the API.
Versions
Agent versions are immutable. Editing an agent creates a new version; the agent row carries a pointer to the current one.
- Rollback moves the pointer back — it never mutates or deletes a version.
- Diff compares any two versions.
- Every new version triggers a security scan (static analysis, dependency audit, secret detection, policy lint, tool-surface review).
- For shared-ring agents, a new version re-runs the evaluation set; a regression reverts the pointer and notifies the owner.
Promotion: personal → shared
Sharing an agent with your team or org is a reviewed promotion, not a toggle. The pipeline gates in order — see Build & promote for the evaluation sets and scanning behind these gates:
-
Propose
The owner proposes the personal agent for a target ring. -
Automated gates
The scan must have passed; the agent must meet its evaluation floors (a minimum number of cases, and — for write-capable agents — refusal, injection, and red-team categories); the eval run must be green. -
Human review
A reviewer sees the gate reports and the candidate definition, then approves, requests changes, or rejects. -
Approve
Approval copies the agent and version into the target ring and freezes its skill references to exact versions, so the shared copy can't drift when the author keeps editing their original. -
Staged rollout
Optionally approve to a pilot group first; the agent stays invisible to everyone else until it's rolled out.
Autonomy
Autonomy decides which actions need a human. The effective level is the lower of what the agent declares and the org's policy floor.
| Level | Behaviour |
|---|---|
| supervised | Every write parks for approval. The default. |
| trusted | Ordinary writes run; destructive operations still park. |
| autonomous | Writes run unattended — subject to explicit approval policies, which always win. |
requires_approval)
parks the action regardless of autonomy level. Autonomy can only relax the
baseline write-parking, never an explicit rule.
Runs
Every invocation creates a run with a strict state machine — only declared transitions are allowed, and every status write goes through that gate.
| Status | Meaning |
|---|---|
queued → running | Created, then picked up by a worker with a heartbeat lease. |
awaiting_approval | Parked on a write. Approve or deny to continue. |
awaiting_input | Parked on a question to the user, or a missing connector credential. |
paused | A long-running background run, resumable from its last checkpoint. |
succeeded / failed / canceled | Terminal. A worker that dies mid-run has its lease expire and is reaped to failed, never left hanging. |
Lifecycle controls
- Pause — the agent refuses new runs; existing ones finish.
- Kill — the agent disappears from the catalog, active and parked runs are force-cancelled, and pending approvals are withdrawn. A killed agent cannot be resumed.
- Emergency stop — an org-wide switch that refuses all new runs and cancels active ones.
- Deprovisioning — when a user is removed, their credentials are revoked, automations disabled, and runs cancelled in one cascade.