Integration examples

AgentTrust ID governs an agent at the action boundary - where the agent touches a real system - across the three surfaces it supports: your API / tool handlers, MCP, and A2A. The model platform that runs the agent is irrelevant to these; the integration is the same whether the agent runs on Anthropic, OpenAI, a local model, or your own loop.

All examples use an org API key created in the dashboard (Settings → API Keys). It’s sent as X-API-Key: sk_live_…, scopes every call to your org automatically, and is exempt from the dashboard’s CSRF protection (CSRF guards cookie-session requests, not API-key requests). Base URL below is http://localhost:8080; swap in your deployment host.

Field names below match the current request structs in the code.

1. API / tool handlers - check before you execute

The core pattern: an agent has a verifiable identity and a capability ceiling; before your tool handler actually performs an action the agent requested, you ask AgentTrust ID whether it’s allowed.


curl -s -X POST http://localhost:8080/api/v1/actions/check \
  -H "X-API-Key: sk_live_…" -H "Content-Type: application/json" \
  -d '{
        "agent_id": "<AGENT_ID>",
        "action": "tool_call",
        "tool_name": "files:read",
        "tool_input_summary": "read config.yaml",
        "session_id": "sess-123"
      }'
# -> {"allowed":true,"guard_tier":"fast","confidence":0.95,
#     "reason":"tool 'files:read' is in agent capabilities","check_id":"…"}

Wrapping a tool handler (Python SDK):


from agenttrustid import AgentTrustClient
 
client = AgentTrustClient(base_url="http://localhost:8080", api_key="sk_live_…")
 
def handle_tool_call(agent_id, tool_name, args, session_id):
    decision = client.actions.check(
        agent_id=agent_id, action="tool_call",
        tool_name=tool_name, session_id=session_id,
    )
    if not decision.allowed:
        return {"error": f"blocked by AgentTrust ID: {decision.reason}"}
    return run_tool(tool_name, args)   # only runs if allowed

Allowed in-policy, denied out-of-policy - and every decision is recorded in the audit trail. This is exactly what you’d drop into a custom tool handler for an agent like Stage Pilot’s Scout: save_opportunity runs only after the check passes; an attempt to use a tool outside the agent’s capabilities is denied and logged.

2. MCP - put AgentTrust ID in front of an MCP server

Register an upstream MCP server once; then agents reach its tools through AgentTrust ID, and every tool call is authorized and (for gated tools) can require human approval. The agent doesn’t need to know AgentTrust ID is there.


curl -s -X POST http://localhost:8080/mcp/servers \
  -H "X-API-Key: sk_live_…" -H "Content-Type: application/json" \
  -d '{
        "name": "filesystem-mcp",
        "url": "https://mcp.example.com",
        "description": "Filesystem tools",
        "default_mode": "read_only",
        "tools": [
          {"name": "search"},
          {"name": "read_file"},
          {"name": "delete_file", "effect_override": "destructive", "require_approval": true}
        ]
      }'

default_mode is read_only (writes need elevation) or scoped. Per-tool, effect_override classifies the action (read / mutating / destructive / admin) and require_approval forces a human-in-the-loop gate regardless of effect.

Open a session, then make calls through the registry (POST /mcp/sessions/init, then the /mcp/{serverID} proxy):


curl -s -X POST http://localhost:8080/mcp/sessions/init \
  -H "X-API-Key: sk_live_…" -H "Content-Type: application/json" \
  -d '{"agent_id": "<AGENT_ID>", "server_id": "<SERVER_ID>"}'

From there, the agent’s tool calls flow through AgentTrust ID: in-ceiling calls pass, writes in read_only mode require elevation, and require_approval tools land in the Approvals queue for an operator to approve or deny. List/manage servers in the dashboard under MCP Registry.

3. A2A - delegate a narrowed slice of authority

One agent delegates a narrowed slice of its authority to another. The granted scope must be a subset of the granting agent’s authority - for a root delegation, a subset of the from-agent’s own capabilities; for a chained delegation, a subset of the parent delegation’s scope. Both are enforced. The delegate can never exceed the granted scope, chains have a maximum depth, both agents must be in the same org, and every step is audited.

Assume two registered agents (POST /api/v1/agents): agent-A (capabilities files:read, files:write) and agent-B.

Create the delegation (POST /api/v1/delegations). The scope must be a subset of the granting agent’s authority - for a root delegation, a subset of the from-agent’s capabilities; for a chained delegation (parent_delegation_id set), a subset of the parent’s scope. Both are enforced:


curl -s -X POST http://localhost:8080/api/v1/delegations \
  -H "X-API-Key: sk_live_…" -H "Content-Type: application/json" \
  -d '{
        "from_agent_id": "<AGENT_A_ID>",
        "to_agent_id": "<AGENT_B_ID>",
        "scope": ["files:read"],
        "ttl_seconds": 3600
      }'
# -> { "id": "<DELEGATION_ID>", ... }   and emits a delegation_created audit row

To extend an existing chain, pass parent_delegation_id; the new scope must be a subset of the parent’s, and the chain can’t exceed the max depth.

Open a delegated session (POST /api/v1/delegations/{id}/session):


curl -s -X POST http://localhost:8080/api/v1/delegations/<DELEGATION_ID>/session \
  -H "X-API-Key: sk_live_…" -H "Content-Type: application/json"

The delegate (agent-B) now acts inside that session, and its actions are checked against the delegated scope through the same guardian core as everything else - a request for files:write is denied because it isn’t in the delegated scope (files:read). Revoking the delegation cascades down the chain and is audited per link. Manage these under Delegations; agent-card discovery is available at GET /a2a/agents/{id}/agent.json.

What’s common to all three

Whichever surface an agent uses, it flows through one authorization core: identity → capability ceiling → runtime check (Fast → Spot → Deep) → approval gate when needed → audit record → instant revocation. You instrument the boundary once; the governance and the audit trail are consistent across API, MCP, and A2A.