An agent in Mandate is a registered identity for an AI system that makes payments on your behalf. Every payment proof, mandate, and transaction record is tied to a specific agent ID, giving you a clean audit trail that shows exactly which system spent what, where, and why. Before an agent can make any payment, you must register it and attach at least one mandate to it.
What an agent is
Agents represent AI systems — an autonomous worker, a background job, a function-calling model, or any software that will call paid APIs on your behalf. Mandate does not care what the agent does internally; it only cares about the agent’s registered identity and current status when evaluating whether a payment is allowed.
Each agent has a stable identifier in the format agt_xxx that you use in mandates, SDK calls, and payment proofs. This ID never changes after creation.
Agent fields
Agent statuses
active — the agent can make payments. Policy evaluation proceeds normally.revoked — the agent is permanently disabled. Any policy evaluation that references a revoked agent returns { "decision": "denied", "reason_code": "agent_revoked" } immediately, regardless of mandate settings.
There is no way to re-activate a revoked agent. If you need to re-enable an agent identity, create a new agent and update your mandates to reference the new ID.
Sandbox vs. production agents
Agents are created under the environment of the API key you use. Sandbox agents are isolated from production — they cannot be used with production API keys, and vice versa. The agent ID format is the same (agt_xxx) in both environments.
Creating an agent
Response (201 Created):
The id returned here is what you pass as agent_id when creating mandates and calling fetchWithPayment() in the SDK.
Revoking an agent
No request body is required. The response returns the updated agent object with status: "revoked" and a revoked_at timestamp.
Revoking an agent takes effect immediately. Any in-flight policy evaluation or payment proof that references the revoked agent will be denied. All mandates attached to the agent become inoperable — the agent cannot be re-activated, and its mandates cannot be transferred to a different agent. Revoke only when you intend the agent to be permanently decommissioned.
Use descriptive name values and populate capabilities even though Mandate does not enforce them in policy checks. The agent name appears in every audit log entry and transaction record — a name like "Market Research Agent v2 (prod)" is far more useful than "agent-1" when you are debugging a payment six months later.
