Agent Deployment¶
Deployment turns a registered Subject into running workloads on Kubernetes. It involves two parts:
- an Agent Deployer, installed once per Kubernetes cluster, which creates and removes agent workloads in that cluster;
- a deploy request, sent for each agent, which tells a deployer which subject to run, how many instances to create, and which meshes they join.
Each successful deployment is recorded as a Runtime Subject, which tells the rest of the platform where the agent is running.
Before deploying, register the agent.
1) Register an Agent Deployer¶
An agent deployer is a service running inside a Kubernetes cluster that creates agent workloads. Register one per cluster:
curl -sS -X POST "$SUBJECT_DB_URL/api/agent-deployers" \
-H "Content-Type: application/json" \
-d '{
"kubeconfig": { "...": "kubeconfig of the target cluster, as JSON" },
"deployer_id": "deployer-111",
"deployer_name": "deployer-111",
"deployer_cluster_id": "gcp-cluster-2",
"deployer_public_ip": "35.223.239.192"
}'
| Field | Required | Description |
|---|---|---|
kubeconfig |
Yes | Kubeconfig (as a JSON object) used to install the deployer into the cluster |
deployer_id |
Yes | Unique ID of the deployer |
deployer_name |
Yes | Human-readable name |
deployer_cluster_id |
Yes | ID of the cluster |
deployer_public_ip |
Yes | Not checked by the API, but needed. Public IP of a cluster node. The deployer is exposed on NodePort 30777, so its URL becomes http://<deployer_public_ip>:30777. Agent and workflow URLs are built from this IP |
The deployer is installed in the agent-deployer namespace. If saving the record fails, the installed Kubernetes resources are rolled back.
| Method & Path | Description |
|---|---|
GET /api/agent-deployers?cluster_id=<id>&limit=50&skip=0 |
List deployers |
POST /api/agent-deployers/query |
Query deployers (same body as subject queries) |
PUT / PATCH /api/agent-deployers/<deployer_id> |
Replace / update a deployer record |
DELETE /api/agent-deployers/<deployer_id> |
Uninstall the deployer (body: { "kubeconfig": {...} }) and delete its record |
Cluster Topologies¶
The platform services are installed once, in the platform services cluster (see Install & Setup). Agents run in agent clusters, each onboarded by registering a deployer for it. The same platform supports these layouts:
| Topology | Layout | Use it for |
|---|---|---|
| Single cluster | Platform services and agents in one cluster. Register one deployer whose kubeconfig points at that cluster | Development, testing and small installations |
| Separate platform and agent clusters | Platform services in one cluster, agents in another | Keeping agent workloads and their resource use away from the shared services |
| Multiple agent clusters | One platform services cluster and several agent clusters, for example per region, per cloud, per team, or for CPU and GPU workloads | Scale, locality and isolation |
| Highly available (multi-master) clusters | Any of the above, with several control plane nodes in a cluster | Keeping a cluster manageable when a control plane node fails |
Multiple Agent Clusters¶
Deployers are registered per cluster. Register one deployer for each agent cluster, each with its own deployer_cluster_id. Choose the cluster for each agent by sending its deploy request to that cluster's deployer (/api/deploy-agent/<deployer_id>). List the deployers of a cluster with GET /api/agent-deployers?cluster_id=<id>.
Agents in different clusters work together through the shared platform services: the Delegate API reaches every agent through its runtime subject's executor URL, and P2P meshes (NATS) can span clusters as long as each instance can reach the mesh URL.
Within a cluster, use node_selector on individual instances (see Deploy the Agent) to place them on specific node pools.
Highly Available (Multi-Master) Clusters¶
The platform does not depend on how many control plane nodes a cluster has. For a multi-master cluster:
- Set the
serverin the kubeconfig you register to the load-balanced API server endpoint of the control plane, not to a single master. The subjects service uses this kubeconfig to install and remove the deployer, and the deployer uses the in-cluster API to create agents, so both keep working when one master fails. - Set
deployer_public_ipto the address of a stable worker node or a load balancer in front of the workers. Deployer, executor and scouter URLs are built from it, and NodePort services are reachable on every node. - Open the control plane ports on every master (see Ports).
Onboarding an Agent Cluster¶
For each new agent cluster:
- Open the required ports on its nodes.
- Configure containerd on every node to trust the platform's container registry (step 3 of Install & Setup), so it can pull agent images.
- Grant the deployer its permissions:
kubectl --kubeconfig <cluster-kubeconfig> apply -f src/rbac/binding.yaml(from theagent-automationrepository). - Register its deployer, as shown in Register an Agent Deployer.
- Make sure the instances can reach the platform services: the subjects service, the Delegate API and, if used, the NATS meshes and the task exchange.
2) Deploy the Agent¶
curl -sS -X POST "$SUBJECT_DB_URL/api/deploy-agent/deployer-111" \
-H "Content-Type: application/json" \
-d '{
"subject_id": "policy-researcher-1",
"allocation": {
"delegate_api_url": "http://35.223.239.192:30725",
"instances": [
{ "instance_id": "i1", "subject_id": "policy-researcher-1" },
{ "instance_id": "i2", "subject_id": "policy-researcher-1", "node_selector": { "pool": "cpu" } }
],
"meshes": [
{ "mesh_id": "mesh-a", "url": "nats://10.104.140.46:4222" }
]
}
}'
| Field | Required | Description |
|---|---|---|
subject_id |
Yes | Subject to deploy |
allocation.instances |
Yes | Agent instances to create. Each needs instance_id and subject_id; node_selector is optional |
allocation.meshes |
No | P2P meshes (NATS) to join, as { "mesh_id", "url" } |
allocation.delegate_api_url |
Yes* | Delegate API URL given to the agent instances (AGENT_DELEGATE_URL), used by context.delegator. *Not checked by the API, but agent instances built on the agents SDK fail to start without it |
The deployer creates the following in the agents namespace:
- Agent executor — one Deployment with the executor, a scouter and Redis, exposed through two
NodePortservices: executor port9000and scouter port10000. The executor receives tasks (/submitTask), applies the subject's policies and load-balances tasks across instances. - Agent instances — one Deployment per instance, running the image from
info.container_image_namewith a Redis sidecar. Each instance getsSUBJECT_ID,INSTANCE_ID,SUBJECT_DB_URL,MESH_LIST,AGENT_DELEGATE_URLandJOB_EXCHANGE_API_URL. It exposes ports8765(WebSocket) and9090(metrics).
On success a Runtime Subject is stored with runtime_subject_id = subject_id:
{
"success": true,
"data": {
"runtime_subject_id": "policy-researcher-1",
"subject_id": "policy-researcher-1",
"runtime_status": "active",
"runtime_info": {
"executor": "http://35.223.239.192:31412",
"scouter": "http://35.223.239.192:31413",
"deployment_data": {
"executor": { "port": 9000, "node_port": 31412, "...": "..." },
"scouter": { "port": 10000, "node_port": 31413, "...": "..." }
}
}
}
}
runtime_info.executor is the URL the Delegate API uses to send tasks to this agent. Deploying a subject that already has a runtime subject fails with HTTP 400 (the record already exists).
Remove an Agent¶
curl -sS -X POST "$SUBJECT_DB_URL/api/remove-agent/deployer-111/policy-researcher-1"
This removes the agent's executor and related Kubernetes resources and deletes the runtime subject.
Configuring the Agent Environment¶
An agent's runtime environment is controlled from three places:
| Where | What you configure |
|---|---|
Specification — runtime.resources |
Device (cpu/gpu/tpu), CPU cores, memory, storage, GPU count and memory per instance, default node_selector, and extra env variables. See Agent Specification |
Deploy request — allocation |
Number of instances, per-instance node_selector, the P2P meshes to join and the Delegate API URL |
| Platform | The variables injected into every instance (SUBJECT_ID, INSTANCE_ID, SUBJECT_DB_URL, MESH_LIST, AGENT_DELEGATE_URL, JOB_EXCHANGE_API_URL); see Agent Creation |
Runtime-tunable values that should change without a redeploy (thresholds, modes, feature flags) belong in the Profile Manager.
Querying Running Agents (Runtime Subjects API)¶
Deployed agents are recorded as runtime subjects. Use these endpoints to find where an agent is running.
GET /api/runtime-subjects/<runtime_subject_id>¶
curl -sS "$SUBJECT_DB_URL/api/runtime-subjects/policy-researcher-1"
The response has the same shape as the deploy response above.
GET /api/runtime-subjects¶
List runtime subjects. All query parameters are optional:
| Parameter | Description |
|---|---|
subject_id |
Filter by subject ID |
runtime_status |
Filter by status (e.g. active) |
sort |
<field>:asc or <field>:desc |
limit, skip |
Paging (defaults 50, 0) |
curl -sS "$SUBJECT_DB_URL/api/runtime-subjects?runtime_status=active&limit=20"
POST /api/runtime-subjects/query¶
Query runtime subjects with a MongoDB-style filter. The filter goes in query:
1) Runtime subjects of one subject that are active
curl -sS -X POST "$SUBJECT_DB_URL/api/runtime-subjects/query" \
-H "Content-Type: application/json" \
-d '{
"query": { "subject_id": "policy-researcher-1", "runtime_status": "active" }
}'
2) Runtime subjects whose ID matches a prefix (case-insensitive)
curl -sS -X POST "$SUBJECT_DB_URL/api/runtime-subjects/query" \
-H "Content-Type: application/json" \
-d '{
"query": { "runtime_subject_id": { "$regex": "^policy", "$options": "i" } },
"limit": 10
}'
Other Runtime Subject endpoints¶
| Method & Path | Description |
|---|---|
POST /api/runtime-subjects |
Create a runtime subject: { "runtime_subject_id", "subject_id", "runtime_info", "runtime_status" } |
PUT /api/runtime-subjects/<id> |
Replace a runtime subject |
PATCH /api/runtime-subjects/<id> |
Update fields: body { "update": { ... } } |
DELETE /api/runtime-subjects/<id> |
Delete the record only (Kubernetes resources are not removed) |
GET /api/runtime-subjects/health |
Health check |