curl http://localhost:4700/api/v1/agents \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
agents = client.monitor.list_agents()
for agent in agents:
print(agent["_id"], agent["name"])
{
"agents": [
{
"_id": "aG5kR8sLp3WvX1nC7qZtB",
"name": "customer-support-agent",
"kind": "agent",
"agentType": "external",
"monitoringAgentId": "aG5kR8sLp3WvX1nC7qZtB",
"monitoringProfile": null,
"createdAt": "2026-08-27T10:30:00.000Z"
}
]
}
Agent Registry
List Agents
List every agent the project knows about, with each one’s monitoring profile
GET
/
api
/
v1
/
agents
curl http://localhost:4700/api/v1/agents \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
agents = client.monitor.list_agents()
for agent in agents:
print(agent["_id"], agent["name"])
{
"agents": [
{
"_id": "aG5kR8sLp3WvX1nC7qZtB",
"name": "customer-support-agent",
"kind": "agent",
"agentType": "external",
"monitoringAgentId": "aG5kR8sLp3WvX1nC7qZtB",
"monitoringProfile": null,
"createdAt": "2026-08-27T10:30:00.000Z"
}
]
}
Returns the project’s agent registry, sorted by name. An agent row exists for every distinct
agent the engine has seen: agents are auto-registered the first time a root trace arrives
under a new name, and can also be registered explicitly with
Register Agent. Use this list to find the agent ids that
monitoring profiles, patterns, and online-evaluator scopes key off.
There is no separate “tracked agents” list on the self-host engine - every registered agent’s
traces appear in Live Traces. This endpoint replaces the hosted platform’s
/ingest/tracked-agents surface.Authentication
string
required
Project API key.
Response
array
Array of agent objects, sorted by name. Each has:
| Field | Type | Description |
|---|---|---|
_id | string | Agent ID - pass as agentId on trace ingest, monitoring profiles, and scope arrays |
name | string | Display name (two agents may deliberately share one; see Register Agent) |
kind | string | Always "agent" |
agentType | string | Always "external" on self-host (agents arrive via SDK/dashboard registration, never a native agent builder) |
monitoringAgentId | string | Same value as _id |
monitoringProfile | object | null | The agent’s monitoring profile, or null when none has been configured. Includes _id, agentId, enabled, failureDetectionEnabled, infoDetectionEnabled, topicsEnabled, sampleRate, retentionDays, thresholdOverrides, channels, coverageMode, approvalPolicy, timestamps, and hosted-compatibility constants (workspaceId: "local", billingMode: "credits", pausedForCredits: false) |
createdAt | string | ISO 8601 timestamp |
curl http://localhost:4700/api/v1/agents \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
agents = client.monitor.list_agents()
for agent in agents:
print(agent["_id"], agent["name"])
{
"agents": [
{
"_id": "aG5kR8sLp3WvX1nC7qZtB",
"name": "customer-support-agent",
"kind": "agent",
"agentType": "external",
"monitoringAgentId": "aG5kR8sLp3WvX1nC7qZtB",
"monitoringProfile": null,
"createdAt": "2026-08-27T10:30:00.000Z"
}
]
}