Integrating Agents

Agent Lifecycle

1Register agentPOST /agents

2Provision API keyReturned in registration response

3Create MCP bindingPOST /agents/:id/mcp-bindings

4Write policiesPOST /policies

5Route trafficAgent connects to proxy endpoint

6Monitor & auditDashboard + audit API

Register an Agent

bash

curl -X POST https://api.shieldagent.io/agents \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin-key>' \
  -d '{
    "tenantId": "<tenant-id>",
    "name": "coding-agent",
    "description": "Claude in VS Code via Cursor",
    "riskTier": "medium"
  }'

Response

json

{
  "id": "agt_01HXYZ...",
  "name": "coding-agent",
  "tenantId": "ten_01HXYZ...",
  "riskTier": "medium",
  "agentKey": "shld_agent_eyJ..."  // ← send this to your agent
}

Create an MCP Binding

Bindings map an agent to an upstream MCP server. You can have multiple bindings per agent (e.g., filesystem, database, web-search).

bash

curl -X POST https://api.shieldagent.io/agents/<agent-id>/mcp-bindings \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin-key>' \
  -d '{
    "upstreamUrl": "http://filesystem-mcp:8080",
    "shadowMode": false,
    "label": "filesystem"
  }'

Shadow Mode

Set shadowMode: true to log all traffic from this binding without applying enforcement. Useful for observing agent behavior before writing policies.

Multi-Agent Setup

Register multiple agents per tenant — each with its own key, risk tier, and bindings. Policies can be scoped per-agent or tenant-wide.

bash

# Register a second agent (higher risk tier)
curl -X POST https://api.shieldagent.io/agents \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin-key>' \
  -d '{
    "tenantId": "<tenant-id>",
    "name": "ops-agent",
    "description": "Infrastructure automation agent",
    "riskTier": "high"
  }'

# List all agents in a tenant
curl "https://api.shieldagent.io/agents?tenantId=<tenant-id>" \
  -H 'Authorization: Bearer <admin-key>'

Credential Rotation

Rotate an agent's API key without downtime. The old key remains valid for 60 seconds after rotation to allow graceful handover.

bash

curl -X POST https://api.shieldagent.io/agents/<agent-id>/rotate-key \
  -H 'Authorization: Bearer <admin-key>'

Risk Tiers

Tier	Use Case	Enforcement
low	Read-only, trusted internal agents	Lenient — monitor only
medium	Standard development agents	Standard policy evaluation
high	Agents with write/execute access	Strict + human review triggers
critical	Prod infra, financial, PII access	Auto-block anomalies, mandatory review