Integrating Agents

Agent Lifecycle

In the Dashboard

Register and configure agents without writing any code:

1. 1Go to Agents in the left sidebar and click Add Agent.
2. 2Enter a name, optional description, and choose a risk tier (low / medium / high / critical).
3. 3Click Create. Copy the API key shown — it is displayed only once.
4. 4On the agent detail page, go to MCP Servers → Add Server. Enter the upstream URL and a label.
5. 5Optionally toggle Shadow Mode on the binding to observe traffic before enforcing policies.

Register an Agent

import ShieldAgent from '@shieldagent/sdk';

const client = new ShieldAgent();

const agent = await client.agents.create({
  name: "coding-agent",
  description: "Claude in VS Code via Cursor",
  riskTier: "medium",
});

{
  "id": "agt_01HXYZ...",
  "name": "coding-agent",
  "tenantId": "ten_01HXYZ...",
  "riskTier": "medium",
  "agentKey": "shld_agent_<token>"  // ← 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).

const binding = await client.agents.createBinding(agent.id, {
  upstreamUrl: "http://<your-mcp-server>:<port>",
  shadowMode: false,
  label: "filesystem",
});

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.

// Register a second agent (higher risk tier)
const opsAgent = await client.agents.create({
  name: "ops-agent",
  description: "Infrastructure automation agent",
  riskTier: "high",
});

// List all agents
const agents = await client.agents.list();

Credential Rotation

Rotate an agent's API key without downtime. The old key remains valid for a brief grace period after rotation to allow graceful handover.

const newKey = await client.agents.rotateKey(agent.id);