Virtual Agent Identity

Each agent in the Gateway has a virtual identity that includes its upstream URL, required credentials, tenant association, and an active/disabled state. The agent invoke endpoint is protocol-agnostic -- the upstream can be an MCP server, or any custom HTTP service.

Agent Registration

Agents are registered by authorized admin/creator roles and linked to a tenant. Each agent has:

• Name -- human-readable identifier
• Upstream URL -- where the agent runtime is hosted
• Required Credentials -- credential types the agent needs (e.g., gateway_api, slack)
• Kill Switch -- ability to disable an agent immediately
• Runtime Token -- one-time art_... token for agent-to-gateway calls

POST /api/v1/admin/agents
{
  "name": "Finance Bot",
  "upstreamUrl": "https://finance-agent.internal/mcp",
  "requiredCredentials": [{ "serviceType": "gateway_api" }],
  "description": "Handles financial queries"
}

Agent Invocation Flow

When the Gateway invokes an agent (via /api/v1/agents/:id/invoke), it performs a full pre-flight:

1. Authenticate via flexible auth (JWT, API key + JWT/User-ID, or runtime token where applicable)
2. Load agent and check tenant isolation + kill switch
3. Resolve credentials -- if requiredCredentials are configured and any are missing, return 401 with auth URLs
4. Inject headers -- user identity + resolved credentials as X-Credential-*
5. Issue session token (when enabled) -- attach X-Gateway-Session-Token so downstream MCP calls can preserve end-user identity
6. Forward to the agent's upstreamUrl and stream the response back

Injected Headers

When forwarding requests to agent runtimes, the Gateway injects these headers:

For MCP callback routes, runtimes typically send X-Agent-Id plus X-Gateway-Session-Token, or authenticate directly with the agent runtime token (art_...).

Runtime Token Lifecycle

• Created once on POST /api/v1/admin/agents
• Can be rotated with POST /api/v1/admin/agents/:id/regenerate-token
• Stored hashed in the database; plaintext is returned only when created/rotated

Kill Switch

Admins can instantly disable or re-enable any agent:

# Disable agent
POST /api/v1/admin/agents/:id/disable

# Re-enable agent
POST /api/v1/admin/agents/:id/enable

When an agent is disabled, all requests to it are immediately rejected.