Agent Registration¶
Registration stores an agent's specification in the subjects registry as a Subject. Once registered, the agent:
- has a stable, versioned identity (
subject_id+subject_version), - can be discovered by people, planners and other agents through its type, description and search tags,
- can be deployed any number of times, to any registered cluster, without resending its specification,
- can be updated or replaced in one place through the subject endpoints.
Before registering, prepare the specification and container image as described in Agent Creation. The examples below use $SUBJECT_DB_URL, the URL of the subjects service.
Create a Subject¶
The body is a full Agent Specification. identity.subject_version is required. Set info.container_image_name to the agent's container image — the deployer runs this image for each agent instance.
Minimal payload¶
curl -sS -X POST "$SUBJECT_DB_URL/api/subjects" \
-H "Content-Type: application/json" \
-d '{
"identity": {
"subject_id": "policy-researcher-1",
"subject_name": "Policy Researcher",
"subject_type": "researcher",
"subject_version": { "version": "1.0.0", "release_tag": "stable" }
},
"info": {
"container_image_name": "registry.example.org/agents/policy-researcher:latest"
},
"metadata": {
"subject_description": "Analyzes policy proposals and drafts briefs",
"subject_search_tags": ["policy","analysis"]
},
"persona": {
"role": "Policy Analyst",
"goal": "Summarize and critique policy drafts",
"persona": "Pragmatic, neutral, cites sources",
"default_system_message": "Answer with citations and balanced tone."
},
"prompting": {},
"execution": { "logging_level": "INFO" },
"integrations": {},
"runtime": { "resources": { "device": "cpu", "cpu_cores": 1.0, "memory_mb": 2048 } },
"owner": { "org_name": "ExampleOrg", "owners": ["owner@example.org"] }
}'
identity.subject_id is optional. If you omit it, the service generates one (a MongoDB ObjectId string). Creating a subject with an existing subject_id fails with HTTP 400.
Example response (HTTP 201) — the stored subject, with all defaults filled in:
{
"success": true,
"data": {
"identity": {
"subject_id": "policy-researcher-1",
"subject_name": "Policy Researcher",
"subject_type": "researcher",
"subject_version": { "version": "1.0.0", "release_tag": "stable" }
},
"info": { "container_image_name": "registry.example.org/agents/policy-researcher:latest", "...": "..." },
"metadata": { "...": "..." },
"persona": { "...": "..." },
"prompting": { "...": "..." },
"execution": { "...": "..." },
"integrations": { "...": "..." },
"runtime": { "...": "..." },
"owner": { "...": "..." }
}
}
Other Subject endpoints¶
| Method & Path | Description |
|---|---|
GET /api/subjects/<subject_id> |
Get a subject (404 if not found) |
PUT /api/subjects/<subject_id> |
Replace a subject with a full specification |
PATCH /api/subjects/<subject_id> |
Update fields: body { "update": { "identity.subject_name": "New Name" } } |
DELETE /api/subjects/<subject_id> |
Delete a subject |
GET /api/subjects?subject_type=<type>&tags=<a,b>&limit=50&skip=0 |
List subjects, optionally filtered by type and search tags (any match) |
POST /api/subjects/query |
Query with a MongoDB filter: body { "query": {...}, "projection": {...}, "sort": [...], "limit": 50, "skip": 0 } |
GET /api/subjects/health |
Health check |
curl -sS "$SUBJECT_DB_URL/api/subjects/policy-researcher-1"
Checking the Registration¶
Registration only creates the agent's record in the registry. Nothing runs until you deploy it. To check that the record was stored:
1. Read the create response. A successful registration returns HTTP 201 with "success": true and the stored subject under data, as in the example above. A failed one returns "success": false and a message:
{
"success": false,
"message": "Subject already exists: policy-researcher-1"
}
| HTTP status | Meaning |
|---|---|
201 |
Registered. data is the stored subject, with defaults filled in |
400 |
Not registered: the subject_id already exists, or the specification is invalid. message says why |
2. Fetch the subject back. GET /api/subjects/<subject_id> returns HTTP 200 and the subject if it is registered, or HTTP 404 if it is not:
curl -sS "$SUBJECT_DB_URL/api/subjects/policy-researcher-1"
{
"success": false,
"message": "Subject not found"
}
3. Check that it can be discovered. Search for it by type or tags, as other agents and planners will (see Discovering Registered Agents). If it does not show up, check identity.subject_type and metadata.subject_search_tags.
Discovering Registered Agents¶
Subjects can be listed by type and search tags, or queried with a MongoDB-style filter, which makes good metadata.subject_description and metadata.subject_search_tags values important:
# All researcher agents tagged "policy"
curl -sS "$SUBJECT_DB_URL/api/subjects?subject_type=researcher&tags=policy"
# Agents whose name starts with "Policy"
curl -sS -X POST "$SUBJECT_DB_URL/api/subjects/query" \
-H "Content-Type: application/json" \
-d '{ "query": { "identity.subject_name": { "$regex": "^Policy" } }, "limit": 10 }'
Agents that need to find and work with other agents at runtime can use the Agents Association Registry.
Next Steps¶
- Deploy the agent to a cluster.
Related¶
- Agent Profiles: Specification & Customisation: every field you can register.
- Querying Running Agents: the runtime subjects registry, which records where deployed agents run.
- Agents Association Registry: registering and querying the relationships between agents.
- Agentic Task Exchange & Bidding: publishing agents to a task exchange so they can receive work.