Agents

Agents are auto-registered the first time they send a request through the proxy (upsert_agent() runs in the hot path). The agent registry lets you inspect every agent, update its status, and pull its event history.

`GET /api/v1/agents`

List all agents registered with the proxy.

Auth required: Yes


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/agents

Response 200 OK:


[
  {
    "id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
    "name": "billing-agent",
    "source_ip": "172.18.0.5",
    "status": "active",
    "metadata": {},
    "created_at": "2026-03-01T09:00:00Z",
    "updated_at": "2026-03-05T14:22:11Z"
  },
  {
    "id": "agt_02jy0a3l4nr5o6q7s8t9u1w2x",
    "name": "support-agent",
    "source_ip": "172.18.0.6",
    "status": "blocked",
    "metadata": { "team": "cx" },
    "created_at": "2026-03-02T11:30:00Z",
    "updated_at": "2026-03-04T08:15:44Z"
  }
]

`GET /api/v1/agents/{id}`

Retrieve a single agent by ID.

Auth required: Yes

Path parameters:

Parameter	Type	Description
`id`	string	Agent ID (prefix `agt_`)


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/agents/agt_01hx9z2k3mq4n5p6r7s8t9u0v

Response 200 OK:


{
  "id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
  "name": "billing-agent",
  "source_ip": "172.18.0.5",
  "status": "active",
  "metadata": {},
  "created_at": "2026-03-01T09:00:00Z",
  "updated_at": "2026-03-05T14:22:11Z"
}

Response 404 Not Found:


{ "error": "agent not found" }

`PUT /api/v1/agents/{id}`

Update an agent’s status and/or metadata. This is the primary endpoint for the kill switch — set status to "blocked" and the proxy immediately starts returning HTTP 403 for that agent’s requests.

Auth required: Yes

Path parameters:

Parameter	Type	Description
`id`	string	Agent ID

Request body:

Field	Type	Values	Description
`status`	string	`"active"`, `"blocked"`, `"retired"`	Agent lifecycle status
`metadata`	object	any JSON object	Arbitrary key-value metadata


# Block a rogue agent
curl -X PUT \
  -H "Authorization: Bearer $GOVRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked", "metadata": {"reason": "unexpected PII exfiltration"}}' \
  http://localhost:4001/api/v1/agents/agt_01hx9z2k3mq4n5p6r7s8t9u0v

Response 200 OK:


{
  "id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
  "name": "billing-agent",
  "source_ip": "172.18.0.5",
  "status": "blocked",
  "metadata": { "reason": "unexpected PII exfiltration" },
  "created_at": "2026-03-01T09:00:00Z",
  "updated_at": "2026-03-05T15:01:33Z"
}

The kill switch takes effect on the next request from that agent. There is currently no in-process cache TTL — the proxy queries the DB once per request. For sustained high-RPS workloads, a short TTL cache is on the roadmap.

`POST /api/v1/agents/{id}/retire`

Retire an agent. Equivalent to PUT with {"status": "retired"} but more explicit in intent — retired agents are excluded from active dashboards.

Auth required: Yes

Path parameters:

Parameter	Type	Description
`id`	string	Agent ID


curl -X POST \
  -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/agents/agt_01hx9z2k3mq4n5p6r7s8t9u0v/retire

Response 200 OK:


{
  "id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
  "status": "retired",
  "updated_at": "2026-03-05T15:05:00Z"
}

`GET /api/v1/agents/{id}/events`

List all events recorded for a specific agent. Returns the same event schema as /api/v1/events.

Auth required: Yes

Path parameters:

Parameter	Type	Description
`id`	string	Agent ID


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/agents/agt_01hx9z2k3mq4n5p6r7s8t9u0v/events

Response 200 OK:


[
  {
    "id": "evt_03kz1b4m5os6p7r8t9u0v2x3y",
    "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
    "session_id": "ses_07pa5f8q9tw0u1v2x3y4z5a6b",
    "timestamp": "2026-03-05T14:20:00Z",
    "model": "gpt-4o",
    "prompt_tokens": 512,
    "completion_tokens": 128,
    "cost_usd": 0.00384,
    "compliance_tag": "default",
    "lineage_hash": "sha256:a3f1c2d4e5b6...",
    "pii_detected": false
  }
]