curl -X POST http://localhost:4700/api/v1/agents \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8" \
-H "Content-Type: application/json" \
-d '{ "name": "customer-support-agent" }'
agent = client.monitor.create_agent("customer-support-agent")
print(agent["_id"])
{
"agent": {
"_id": "aG5kR8sLp3WvX1nC7qZtB",
"name": "customer-support-agent",
"createdAt": "2026-08-27T10:30:00.000Z"
}
}
{
"error": "name is required"
}
Agent Registry
Register Agent
Explicitly register an agent identity in the project
POST
/
api
/
v1
/
agents
curl -X POST http://localhost:4700/api/v1/agents \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8" \
-H "Content-Type: application/json" \
-d '{ "name": "customer-support-agent" }'
agent = client.monitor.create_agent("customer-support-agent")
print(agent["_id"])
{
"agent": {
"_id": "aG5kR8sLp3WvX1nC7qZtB",
"name": "customer-support-agent",
"createdAt": "2026-08-27T10:30:00.000Z"
}
}
{
"error": "name is required"
}
Creates a new agent row and returns its id. Registration is optional: tracing under a bare
name auto-registers a single stable agent per distinct name. Register explicitly when you
want a real id up front, or when you deliberately need two agents sharing one display name
(the only way that can happen) - from then on, disambiguate them by passing the returned _id
as agentId on Submit Trace.
This endpoint always creates a new row, even if an agent with this name already exists.
The implicit path (tracing under a name with no explicit
agentId) keeps resolving to the
oldest agent registered under that name, so existing callers never change behavior.Authentication
string
required
Project API key.
Body
string
required
Agent display name. Leading/trailing whitespace is trimmed.
Response
Returns201 Created.
object
The created agent:
{ "_id": string, "name": string, "createdAt": string }.Errors
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "name is required" } | name missing, not a string, or blank |
curl -X POST http://localhost:4700/api/v1/agents \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8" \
-H "Content-Type: application/json" \
-d '{ "name": "customer-support-agent" }'
agent = client.monitor.create_agent("customer-support-agent")
print(agent["_id"])
{
"agent": {
"_id": "aG5kR8sLp3WvX1nC7qZtB",
"name": "customer-support-agent",
"createdAt": "2026-08-27T10:30:00.000Z"
}
}
{
"error": "name is required"
}