Skip to content

Agent Creation — Subject Creation & Infra

Set a base variable (optional):

export SUBJECT_DB_URL="https://subject-db.example.com"

1) Create a Subject

Minimal payload

curl -sS -X POST "$SUBJECT_DB_URL/subjects" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {
      "subject_name": "Policy Researcher",
      "subject_type": "researcher",
      "subject_version": { "version": "1.0.0", "release_tag": "stable" }
    },
    "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"] }
  }'

Example response

{
  "success": true,
  "data": { "subject_id": "b2f2f6e8-7d8a-4c3e-9c9a-1a2b3c4d5e6f" }
}

Get by ID

curl -sS "$SUBJECT_DB_URL/subjects/b2f2f6e8-7d8a-4c3e-9c9a-1a2b3c4d5e6f"

2) Create Subject Infra

Endpoint:

POST https://<subject-db-url>/infra/create

There are two modes:

A) Manual placement (explicit cluster & nodes)

Use when you already know the cluster and exact nodes.

curl -sS -X POST "$SUBJECT_DB_URL/infra/create" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "manual",
    "subject_id": "b2f2f6e8-7d8a-4c3e-9c9a-1a2b3c4d5e6f",
    "cluster_id": "gcp-cluster-2",
    "replicas": 2,
    "allocation_data": [
      { "node_id": "node-10" },
      { "node_id": "node-11" }
    ]
  }'

Sample response

{
  "success": true,
  "data": {
    "infra_id": "inf-8a2f6a",
    "mode": "manual",
    "replicas": 2,
    "cluster_id": "gcp-cluster-2"
  }
}

B) Policy-driven allocation (automatic; adhoc=true)

Use your Resource Allocation Policy to pick clusters/nodes. Required fields: adhoc=true, policy_rule_uri, and inputs.

Field reference

Field Type Required Description
adhoc boolean ✅ Must be true for policy-driven (ad-hoc) allocation.
policy_rule_uri string ✅ URI of the policy in Policy DB used for allocation.
clusters array ❌ Optional list of known cluster IDs to constrain selection.
filter object ❌ Filter query if clusters aren’t known.
search object ❌ Similarity/semantic search to find candidate clusters.
inputs object ✅ Policy-specific inputs (e.g., desired resources, SLA).
parameters object ❌ Override default policy parameters.
settings object ❌ Additional policy settings/flags.

Search payload shape (example) You can pass this inside the top-level search field.

{
  "matchType": "cluster",
  "clusterQuery": {
    "logicalOperator": "AND",
    "conditions": [
      { "variable": "regionId", "operator": "==", "value": "gcp-cluster-2" },
      { "variable": "vcpus.count", "operator": ">", "value": "3" }
    ]
  },
  "rankingPolicyRule": {
    "policyRuleURI": "policy://rankers/prefer-low-latency:1.0-stable",
    "parameters": { "latencyWeight": 0.7, "costWeight": 0.3 }
  }
}

Complete cURL (policy-driven)

curl -sS -X POST "$SUBJECT_DB_URL/infra/create" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "automatic",
    "subject_id": "b2f2f6e8-7d8a-4c3e-9c9a-1a2b3c4d5e6f",
    "replicas": 3,

    "adhoc": true,
    "policy_rule_uri": "policy://allocators/gpu-balanced:1.0-stable",

    "clusters": [],

    "search": {
      "matchType": "cluster",
      "clusterQuery": {
        "logicalOperator": "AND",
        "conditions": [
          { "variable": "regionId", "operator": "==", "value": "gcp-cluster-2" },
          { "variable": "vcpus.count", "operator": ">", "value": "3" }
        ]
      },
      "rankingPolicyRule": {
        "policyRuleURI": "policy://rankers/prefer-low-latency:1.0-stable",
        "parameters": { "latencyWeight": 0.7, "costWeight": 0.3 }
      }
    },

    "parameters": { "spread": "zone", "maxPerNode": 1 },
    "settings": { "dryRun": false, "respectMaintenanceWindows": true }
  }'

Sample response

{
  "success": true,
  "data": {
    "infra_id": "inf-c41a90",
    "mode": "automatic",
    "replicas": 3,
    "selected_cluster": "gcp-cluster-2",
    "placement": [
      {"node_id": "node-10"}, {"node_id": "node-12"}, {"node_id": "node-14"}
    ]
  }
}

Querying Running Agents (Runtime Subjects API)

Agents you create are persisted in the Agents Runtime DB. Use these endpoints to discover where an agent is running, how many replicas it has, and the connection URLs to manage or communicate with it.

Set a base URL (optional):

export SUBJECTS_DB_API_URL="http://<subjects-db-api-url>"

GET /runtime_subjects/<subject_id>

Fetch a single runtime subject (agent) by its ID or URI.

cURL

curl -sS "$SUBJECTS_DB_API_URL/runtime_subjects/sample.subject:1.0-stable"

Typical Response

{
  "success": true,
  "data": {
    "subject_id": "sample.subject:1.0-stable",
    "subject_type": "agent",
    "identity": {
      "subject_name": "Sample Agent",
      "subject_version": { "version": "1.0.0", "release_tag": "stable" }
    },
    "urls": {
      "subjectManagementURL": "http://agent1-agent-mgmt.svc.cluster.local:8080",
      "subjectNATSURL": "nats://agent1-nats.messaging.svc.cluster.local:4222",
      "subjectP2PURL": "http://agent1-agent-peer-id",
      "subjectConfigURL": "http://agent1.agent-config.svc.cluster.local:8081"
    },
    "runtime": {
      "cluster_id": "gcp-cluster-2",
      "replicas": [
        {
          "replica_id": "rep-0",
          "status": "Running",
          "node_id": "node-10",
          "pod_name": "agent-0-abc123",
          "pod_ip": "10.42.1.15",
          "ports": { "http": 8080, "metrics": 9090 },
          "resources": { "device": "gpu", "gpu_count": 1, "cpu_cores": 4.0, "memory_mb": 8192 },
          "started_at": "2025-08-13T09:20:11Z",
          "last_heartbeat_at": "2025-08-13T11:42:30Z",
          "labels": { "gpu.vendor": "nvidia" },
          "metrics": { "cpu_pct": 0.22, "mem_mb": 1230 }
        }
      ]
    }
  }
}

POST /runtime_subjects/query

Query runtime subjects with a structured (MongoDB-style) filter.

cURL (examples with MongoDB-style filters)

1) Agents whose name matches a prefix (case-insensitive)

curl -sS -X POST "$SUBJECTS_DB_API_URL/runtime_subjects/query" \
  -H "Content-Type: application/json" \
  -d '{
    "identity.subject_name": { "$regex": "^policy", "$options": "i" }
  }'

2) OR query across two regions

curl -sS -X POST "$SUBJECTS_DB_API_URL/runtime_subjects/query" \
  -H "Content-Type: application/json" \
  -d '{
    "$and": [
      { "subject_type": "agent" },
      { "$or": [
          { "runtime.cluster_id": "gcp-cluster-2" },
          { "runtime.cluster_id": "gcp-cluster-3" }
      ]}
    ]
  }'