Appearance
Agents
An agent is an AI worker with its own identity. It pairs a model configuration (provider, model, version) with a registered identity in your identity provider, so everything the agent does is attributable to the agent acting on behalf of a user — never to an anonymous API key.
What creating an agent does
When you create an agent (Agents → Create, or POST /api/agents, permission create-agent), Agentfleet:
- Registers it in the identity provider as a delegated agent — it can only ever act on behalf of a delegating user, not independently.
- Creates a confidential client for it with no client secret. The agent authenticates using
private_key_jwt— short-lived assertions signed with a per-agent key held in a key vault. Private key material never touches the application. - Records the model it runs on: a provider (for example
Groq,OpenAI,Anthropic;Groqwhen the API request names none), a model that provider offers, and a version label. The model is validated against the provider's model list, and a sunset model is refused.
Updates to name, description, or model propagate to the identity provider registration. A step or workflow step can override the model for itself; the agent's model is the fallback.
Agent types
| Type | Meaning |
|---|---|
Delegated | Acts on behalf of the user who started the run or chat. Every agent created through the console or API is Delegated. |
Orchestrator | A delegated agent that can also call published workflows as tools from its model steps. |
Autonomous | Acts without a user. Not usable for chats (assistant profiles refuse it). |
An Orchestrator agent has an allowlist of up to 20 workflow tools (agent page, or PUT /api/agents/workflow-tools, permission update-agent). Each names a published workflow (optionally a pinned version), a tool name, a description telling the model when to call it, and the input keys the model supplies. A call starts a child run of that workflow as the same agent, delegated from the same user, so it can do nothing the parent could not. Tool names cannot reuse a built-in tool's name. See Sub-workflows.
Orchestrator type is set outside the console
The console and API create Delegated agents and do not let you choose the type. An agent becomes an Orchestrator only through an operator change. Saving an Orchestrator agent's details through PUT /api/agents (the console's Edit) currently resets its type to Delegated and clears its workflow tools, so ask an operator before editing one.
Lifecycle
| State | Meaning |
|---|---|
| Active | Can be assigned to runs. |
| Inactive | Deactivated; existing history is preserved, no new runs. |
| Deleted | Soft-deleted. |
Activate, deactivate, and delete from the agent's page.
Default agents
A workflow's run policy can name a default agent (PUT /api/workflows/run-policy, field defaultAgentId). A run launched without an agent — from the API, an MCP client, a schedule or a trigger — uses the default agent of the version it runs; a draft run uses the live workflow's. If the launch names no agent and the workflow has no default, the launch is refused (Workflow.NoDefaultAgent). The console's Run dialog always asks for an agent. The default agent is part of each published version, so changing it takes effect for pinned runs only after the next publish.
Key rotation
Each agent's signing key can be rotated with zero downtime: a new key version is minted and registered while the previous one remains valid during the overlap, then superseded keys are revoked, so token exchange never fails mid-rotation. Rotation is an operator task; there is no console button or REST endpoint for it. Rotate on your normal credential-rotation cadence or immediately on suspicion of compromise.
Agent instances
You never run "the agent" directly. Each execution creates an agent instance — a single, short-lived execution with its own delegated tokens, its own lifecycle (Idle → Running → Completed/Failed/Cancelled), and its own audit trail. This is what makes work individually attributable and revocable.
- In a run, each step execution gets an agent instance owned by the run. Its temporary access grants are revoked when the step ends.
- In a chat, each turn of a conversation thread gets an agent instance with no run. A turn that resumes after a tool confirmation runs under a fresh instance.
Open an instance from a run's step view (/agent-instances/:id in the console).
Related
- Identity & Security — what the delegated token carries.
- Runs — how agent instances fit into a run.
- Conversations — the agent an assistant profile chats as.
- Model Providers — the models an agent can run on.