Agent Profiles

Configure agent metadata, settings, and behavioral constraints.

Profile Structure

{
  "agent_id": "agent_abc123",
  "name": "Support Bot",
  "description": "Customer support assistant for help desk",
  "version": "1.0.0",
  "permissions": {
    "tools": ["llm/chat", "retrieval/search"],
    "models": ["gpt-5-mini", "gpt-5.2"],
    "data_classification": ["public", "internal"]
  },
  "limits": {
    "cost_per_session": 5.00,
    "cost_daily": 100.00,
    "requests_per_minute": 60
  },
  "metadata": {
    "team": "support",
    "environment": "production"
  }
}

Creating a Profile

curl -X POST https://api.gateflow.ai/v1/mcp/agents \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "description": "Agent for researching and summarizing documents",
    "permissions": {
      "tools": [
        "llm/chat",
        "retrieval/search",
        "retrieval/rerank",
        "document/ocr"
      ],
      "models": ["gpt-5.2", "claude-sonnet-4-5-20250929"],
      "data_classification": ["public", "internal", "confidential"]
    },
    "limits": {
      "cost_per_session": 10.00,
      "cost_daily": 500.00,
      "requests_per_minute": 30
    },
    "metadata": {
      "team": "research",
      "owner": "jane@company.com"
    }
  }'

Profile Fields

Basic Information

Field	Type	Description
name	string	Human-readable name
description	string	Agent purpose and capabilities
version	string	Version identifier
tags	array	Categorization tags

Permissions

Field	Type	Description
tools	array	Allowed tool patterns
models	array	Allowed AI models
data_classification	array	Accessible data levels
collections	array	Accessible document collections

Limits

Field	Type	Description
cost_per_session	number	Max cost per session (USD)
cost_daily	number	Max daily cost (USD)
cost_monthly	number	Max monthly cost (USD)
requests_per_minute	number	Request rate limit
concurrent_sessions	number	Max simultaneous sessions

Metadata

Custom key-value pairs for organization:

{
  "metadata": {
    "team": "engineering",
    "owner": "alice@company.com",
    "project": "customer-portal",
    "environment": "production",
    "compliance": ["hipaa", "soc2"]
  }
}

Updating Profiles

Update Permissions

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 '{
    "permissions": {
      "tools": ["llm/chat", "retrieval/search", "voice/transcribe"],
      "models": ["gpt-5.2", "gpt-5-mini", "whisper-1"]
    }
  }'

Update Limits

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 '{
    "limits": {
      "cost_daily": 200.00,
      "requests_per_minute": 120
    }
  }'

Update Metadata

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 '{
    "metadata": {
      "version": "2.0.0",
      "updated_by": "admin@company.com"
    }
  }'

Profile Templates

Support Agent

{
  "name": "Support Agent",
  "template": "support",
  "permissions": {
    "tools": ["llm/chat", "retrieval/search"],
    "models": ["gpt-5-mini"],
    "data_classification": ["public"]
  },
  "limits": {
    "cost_per_session": 1.00,
    "cost_daily": 50.00
  }
}

Research Agent

{
  "name": "Research Agent",
  "template": "research",
  "permissions": {
    "tools": ["llm/chat", "retrieval/search", "retrieval/rerank", "document/ocr"],
    "models": ["gpt-5.2", "claude-sonnet-4-5-20250929"],
    "data_classification": ["public", "internal", "confidential"]
  },
  "limits": {
    "cost_per_session": 20.00,
    "cost_daily": 500.00
  }
}

Voice Agent

{
  "name": "Voice Agent",
  "template": "voice",
  "permissions": {
    "tools": ["voice/transcribe", "voice/synthesize", "voice/pipeline", "llm/chat"],
    "models": ["whisper-1", "gpt-5-mini", "eleven_turbo_v2_5"],
    "pipelines": ["voice-agent-fast"]
  },
  "limits": {
    "cost_per_session": 5.00,
    "audio_minutes_daily": 60
  }
}

Viewing Profiles

Get Profile

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

From Agent (Self-Inspect)

from gateflow_mcp import MCPClient

client = MCPClient(agent_id="agent_abc123", api_key="gf-agent-xyz...")

# Get own profile
profile = client.call_tool("self_inspect/whoami", {})

print(f"Agent: {profile['name']}")
print(f"Permissions: {profile['permissions']}")
print(f"Limits: {profile['limits']}")

Profile Versioning

Track profile changes:

# Get profile history
curl https://api.gateflow.ai/v1/mcp/agents/agent_abc123/history \
  -H "Authorization: Bearer gw_prod_admin_key"

Response:

{
  "versions": [
    {
      "version": 3,
      "changed_at": "2026-02-16T10:00:00Z",
      "changed_by": "admin@company.com",
      "changes": ["Added voice/transcribe permission"]
    },
    {
      "version": 2,
      "changed_at": "2026-02-10T10:00:00Z",
      "changed_by": "admin@company.com",
      "changes": ["Increased daily cost limit"]
    }
  ]
}

Profile Inheritance

Create agents from templates:

curl -X POST https://api.gateflow.ai/v1/mcp/agents \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Support Bot",
    "extends": "template:support",
    "overrides": {
      "limits": {
        "cost_daily": 100.00
      }
    }
  }'

Best Practices

1. Use templates - Start from predefined templates
2. Minimum permissions - Only grant what's needed
3. Set cost limits - Prevent runaway costs
4. Add metadata - Track ownership and purpose
5. Version control - Track profile changes
6. Regular reviews - Audit permissions periodically

Next Steps

• Agent Lifecycle - Manage agent state
• Tool Permissions - Permission details
• Cost Transparency - Monitor costs