Skip to content

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