Agent Lifecycle

Manage agent states from creation to deletion.

Lifecycle States

State	Description
created	Agent exists but not yet activated
active	Agent can authenticate and use tools
suspended	Temporarily disabled, can be reactivated
revoked	Permanently disabled, cannot be reactivated

Creating Agents

Basic Creation

curl -X POST https://api.gateflow.ai/v1/mcp/agents \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "permissions": {
      "tools": ["llm/chat", "retrieval/search"],
      "models": ["gpt-5-mini"]
    }
  }'

Response:

{
  "agent_id": "agent_abc123",
  "name": "Support Bot",
  "status": "active",
  "api_key": "gf-agent-xyz789...",
  "mcp_endpoint": "https://mcp.gateflow.ai/agent_abc123",
  "created_at": "2026-02-16T10:00:00Z"
}

Create as Inactive

curl -X POST https://api.gateflow.ai/v1/mcp/agents \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "status": "created",
    "permissions": {...}
  }'

Activating Agents

curl -X POST https://api.gateflow.ai/v1/mcp/agents/agent_abc123/activate \
  -H "Authorization: Bearer gw_prod_admin_key"

Response:

{
  "agent_id": "agent_abc123",
  "status": "active",
  "activated_at": "2026-02-16T10:30:00Z"
}

Suspending Agents

Temporarily disable an agent:

curl -X POST https://api.gateflow.ai/v1/mcp/agents/agent_abc123/suspend \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Under investigation",
    "suspended_by": "admin@company.com"
  }'

Response:

{
  "agent_id": "agent_abc123",
  "status": "suspended",
  "suspended_at": "2026-02-16T11:00:00Z",
  "reason": "Under investigation"
}

Auto-Suspension

Configure automatic suspension triggers:

curl -X PATCH https://api.gateflow.ai/v1/mcp/agents/agent_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_suspend": {
      "on_cost_limit": true,
      "on_error_rate": 0.5,
      "on_suspicious_activity": true
    }
  }'

Reactivating Agents

curl -X POST https://api.gateflow.ai/v1/mcp/agents/agent_abc123/activate \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reactivated_by": "admin@company.com",
    "notes": "Investigation complete, cleared for use"
  }'

Revoking Agents

Permanently disable an agent:

curl -X POST https://api.gateflow.ai/v1/mcp/agents/agent_abc123/revoke \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security incident",
    "revoked_by": "security@company.com"
  }'

Response:

{
  "agent_id": "agent_abc123",
  "status": "revoked",
  "revoked_at": "2026-02-16T12:00:00Z",
  "reason": "Security incident"
}

WARNING

Revoking is permanent. The agent cannot be reactivated.

Deleting Agents

Remove an agent and all associated data:

curl -X DELETE https://api.gateflow.ai/v1/mcp/agents/agent_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key"

With Data Retention

curl -X DELETE https://api.gateflow.ai/v1/mcp/agents/agent_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "retain_audit_logs": true,
    "retention_days": 90
  }'

Session Management

List Active Sessions

curl https://api.gateflow.ai/v1/mcp/agents/agent_abc123/sessions \
  -H "Authorization: Bearer gw_prod_admin_key"

Response:

{
  "sessions": [
    {
      "session_id": "sess_xyz123",
      "started_at": "2026-02-16T10:00:00Z",
      "last_activity": "2026-02-16T10:15:00Z",
      "tool_calls": 15,
      "cost": 0.45
    }
  ]
}

Terminate Session

curl -X POST https://api.gateflow.ai/v1/mcp/agents/agent_abc123/sessions/sess_xyz123/terminate \
  -H "Authorization: Bearer gw_prod_admin_key"

Terminate All Sessions

curl -X POST https://api.gateflow.ai/v1/mcp/agents/agent_abc123/terminate-all-sessions \
  -H "Authorization: Bearer gw_prod_admin_key"

Lifecycle Events

List Events

curl https://api.gateflow.ai/v1/mcp/agents/agent_abc123/events \
  -H "Authorization: Bearer gw_prod_admin_key"

Response:

{
  "events": [
    {
      "type": "agent.activated",
      "timestamp": "2026-02-16T10:00:00Z",
      "actor": "admin@company.com"
    },
    {
      "type": "agent.suspended",
      "timestamp": "2026-02-16T11:00:00Z",
      "actor": "system",
      "reason": "Cost limit exceeded"
    },
    {
      "type": "agent.reactivated",
      "timestamp": "2026-02-16T11:30:00Z",
      "actor": "admin@company.com"
    }
  ]
}

Event Types

Event	Description
agent.created	Agent was created
agent.activated	Agent was activated
agent.suspended	Agent was suspended
agent.reactivated	Agent was reactivated
agent.revoked	Agent was revoked
agent.deleted	Agent was deleted
agent.key_rotated	API key was rotated
agent.permissions_updated	Permissions changed
agent.limits_updated	Limits changed

Webhooks

Get notified of lifecycle events:

curl -X POST https://api.gateflow.ai/v1/mcp/webhooks \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/agent-webhook",
    "events": [
      "agent.suspended",
      "agent.revoked",
      "agent.cost_limit_exceeded"
    ]
  }'

Webhook Payload:

{
  "event": "agent.suspended",
  "timestamp": "2026-02-16T11:00:00Z",
  "data": {
    "agent_id": "agent_abc123",
    "name": "Support Bot",
    "reason": "Cost limit exceeded",
    "suspended_by": "system"
  }
}

Best Practices

1. Start inactive - Create agents as inactive for testing
2. Set auto-suspend - Protect against runaway costs
3. Monitor events - Set up webhooks for important events
4. Regular audits - Review agent activity periodically
5. Clean up - Delete unused agents promptly
6. Document reasons - Always provide reasons for state changes

Next Steps

• Agent API Keys - Key management
• Agent Profiles - Profile configuration
• Audit Logging - Track agent activity