Agents

An agent is an AI system you run — a support bot, a coding assistant, an autonomous workflow. Task Guard, Govern, and Secure accept an agent identity so tasks, decisions, and incidents can be attributed to the right agent.

Good to know Registering agents is optional. You can call every endpoint with just a free-text agent_name. Registering an agent gives you a stable agent_id and richer reporting — but it is never a prerequisite for using the API.

Registered vs. unregistered#

Task Guard task starts and every Govern and Secure call accept two optional identity fields:

You can send either, both, or neither. Passing agent_id links activity to the registered agent; agent_name is a human-readable label. Start with agent_name, and switch to agent_id once you register.

How Govern resolves policy scope#

For normal active-policy evaluation, agent_id is optional. Govern still evaluates the action when a REST or MCP request sends only agent_name.

Pass agent_id when you can; use agent_name when an agent is not registered yet or when an MCP client does not have a registered ID. If you pass policy_ids or policy_group_ids on a checkpoint, Maetra evaluates the policies you explicitly selected.

When to register

• You want per-agent dashboards, findings, and audit trails.
• You want to scope rules or policies to specific agents.
• You're onboarding an agent to formal governance.

When you don't need to

• You're integrating quickly or prototyping.
• The caller is a one-off script or a product surface, not a tracked agent.

Registering an agent#

Register agents in the dashboard under Discover → Agent registry → Register agent. Only a name is required; everything else (owner, environment, framework, autonomy level, tools) is optional context. On save, Maetra assigns the agent_id you pass to the API.

List agents#

GET /v1/agents — returns the agents in your workspace, newest first, with a minimal public projection. Requires the discover:agents:read scope.

Query parameters

curl "https://api.maetra.io/v1/agents?limit=20" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Response

{
  "agents": [
    {
      "id": "agt_5Ab2",
      "name": "billing-bot",
      "description": "Handles customer refunds.",
      "status": "registered",
      "autonomy_level": "L3",
      "risk_level": "medium",
      "environment": "production",
      "created_at": "2026-07-01T09:12:00.000Z",
      "updated_at": "2026-07-06T22:04:00.000Z"
    }
  ]
}