Claude Managed Agents Integration¶

Pisama integrates with Claude Managed Agents to monitor agent sessions and detect failure modes in Anthropic-hosted agent systems.

Managed Agents runs on Anthropic's infrastructure, so Pisama supports both push (webhook) and pull (API sync) ingestion models.

Setup¶

1. Get a Bearer Token¶

Exchange your API key for a JWT:

curl -X POST https://pisama-api.fly.dev/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "pisama_your_api_key_here"}'

Save the access_token from the response:

export TOKEN="<access_token>"

2. Register a Connection¶

curl -X POST https://pisama-api.fly.dev/api/v1/managed-agents/connections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-managed-agents",
    "api_key": "<your_anthropic_api_key>",
    "organization_id": "<your_anthropic_org_id>"
  }'

Optional fields: ingestion_mode ("full" or "trace_only"), poll_enabled (bool), poll_interval_seconds (10-3600).

3. Register Agents¶

Register each Managed Agent you want to monitor:

curl -X POST https://pisama-api.fly.dev/api/v1/managed-agents/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<connection_id>",
    "agent_id": "<anthropic_agent_id>",
    "agent_name": "My Research Agent",
    "model": "claude-sonnet-4-6",
    "tool_allowlist": ["bash", "read", "write", "web_search"],
    "mcp_servers": ["linear", "github"],
    "allowed_hosts": ["api.github.com", "*.linear.app"]
  }'

The tool_allowlist, mcp_servers, and allowed_hosts fields enable platform-specific security detection. The response includes a webhook_secret for signing.

4a. Send Session Data via Webhook (Push Model)¶

Webhook URL: https://pisama-api.fly.dev/api/v1/managed-agents/webhook

Required headers:

Signature computation:

import hmac, hashlib, time

timestamp = str(int(time.time()))
message = f"{timestamp}.{request_body}"
signature = "sha256=" + hmac.new(
    webhook_secret.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()

Payload schema:

{
  "session_id": "sess_abc123",
  "agent_id": "agent_xyz",
  "agent_name": "My Research Agent",
  "status": "terminated",
  "started_at": "2026-04-08T10:00:00Z",
  "finished_at": "2026-04-08T10:05:00Z",
  "total_tokens": 15000,
  "total_cost_cents": 45,
  "events": [
    {"type": "user.message", "timestamp": "2026-04-08T10:00:00Z", "content": "Research topic X"},
    {"type": "agent.tool_use", "timestamp": "2026-04-08T10:00:05Z", "tool_name": "web_search", "tool_input": {"query": "topic X"}, "tool_source": "built_in"},
    {"type": "agent.message", "timestamp": "2026-04-08T10:00:15Z", "content": "Here are my findings...", "token_count": 500},
    {"type": "agent.tool_use", "timestamp": "2026-04-08T10:01:00Z", "tool_name": "query_db", "tool_source": "mcp", "mcp_server": "linear"},
    {"type": "session.status_idle", "timestamp": "2026-04-08T10:05:00Z"}
  ]
}

4b. Sync Sessions via API (Pull Model)¶

Because Managed Agents runs on Anthropic's infrastructure, Pisama can pull session data directly from the Anthropic API:

curl -X POST https://pisama-api.fly.dev/api/v1/managed-agents/sync \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<connection_id>",
    "limit": 20
  }'

Optionally filter by agent: "agent_id": "<anthropic_agent_id>".

5. Discover Agents¶

List all agents from the Anthropic API for registration:

curl -X POST https://pisama-api.fly.dev/api/v1/managed-agents/discover \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<connection_id>",
    "limit": 50
  }'

Detection Capabilities¶

Managed Agents-Specific Detectors¶

General Detectors (Also Applied)¶

All 20 core detectors also run on Managed Agents traces, including loop detection, hallucination, coordination failures, persona drift, and more.

OTEL Integration¶

If your Managed Agents sessions emit OpenTelemetry spans, Pisama auto-detects them via these attribute prefixes:

API Endpoints¶

Beta Notes¶

Claude Managed Agents is in public beta (managed-agents-2026-04-01). The API surface may change. Pisama pins the beta version and handles unknown event types gracefully.