Configuration

About

Agent Command Center is configured at the organization level. Each organization has its own providers, guardrails, routing rules, rate limits, and budgets. Changes take effect in real time with no gateway restart required.

Configuration can be set in four places. When the same setting exists in multiple places, the most specific one wins:

Request headers  >  Virtual key config  >  Organization config  >  Global defaults

• Request headers: Per-request overrides sent via x-agentcc-* headers or GatewayConfig.to_headers(). See headers reference.
• Virtual key config: Settings attached to a specific virtual key (e.g. rate limits, allowed models, guardrails).
• Organization config: Org-level settings configured via the dashboard or admin API.
• Global defaults: Gateway-wide defaults. For self-hosted deployments, these come from config.yaml. For the cloud gateway, these are platform defaults.

For example, if the org sets cache TTL to 60 seconds but a request sends x-agentcc-cache-ttl: 300, that request uses a 300-second TTL.

Configuration sections

Each section has its own page with full configuration options. The rest of this page covers the config hierarchy and how to set config from code.

Example configuration

A minimal organization configuration with two providers, weighted routing, caching, and a monthly budget:

from agentcc import AgentCC

client = AgentCC(
    api_key="sk-agentcc-your-key",
    base_url="https://gateway.futureagi.com",
    control_plane_url="https://api.futureagi.com",
)

client.org_configs.create(
    org_id="your-org-id",
    config={
        "providers": {
            "openai": {
                "api_key": "sk-...",
                "models": ["gpt-4o", "gpt-4o-mini"],
            },
            "anthropic": {
                "api_key": "sk-ant-...",
                "models": ["claude-sonnet-4-6", "claude-haiku-4-5"],
            },
        },
        "routing": {
            "strategy": "weighted",
            "weights": {"openai": 70, "anthropic": 30},
            "failover": {
                "enabled": True,
                "providers": ["openai", "anthropic"],
            },
        },
        "cache": {
            "enabled": True,
            "mode": "exact",
            "ttl_seconds": 3600,
        },
        "budgets": {
            "limit": 500.00,
            "period": "monthly",
            "alert_threshold_percent": 80,
        },
    }
)

import { AgentCC } from "@futureagi/agentcc";

const client = new AgentCC({
    apiKey: "sk-agentcc-your-key",
    baseUrl: "https://gateway.futureagi.com",
    controlPlaneUrl: "https://api.futureagi.com",
});

await client.orgConfigs.create({
    orgId: "your-org-id",
    config: {
        providers: {
            openai: {
                api_key: "sk-...",
                models: ["gpt-4o", "gpt-4o-mini"],
            },
            anthropic: {
                api_key: "sk-ant-...",
                models: ["claude-sonnet-4-6", "claude-haiku-4-5"],
            },
        },
        routing: {
            strategy: "weighted",
            weights: { openai: 70, anthropic: 30 },
            failover: {
                enabled: true,
                providers: ["openai", "anthropic"],
            },
        },
        cache: {
            enabled: true,
            mode: "exact",
            ttl_seconds: 3600,
        },
        budgets: {
            limit: 500.0,
            period: "monthly",
            alert_threshold_percent: 80,
        },
    },
});

Self-hosted config.yaml:

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    models: ["gpt-4o", "gpt-4o-mini"]
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    models: ["claude-sonnet-4-6", "claude-haiku-4-5"]

routing:
  strategy: weighted
  weights:
    openai: 70
    anthropic: 30
  failover:
    enabled: true
    providers: ["openai", "anthropic"]

cache:
  enabled: true
  mode: exact
  ttl_seconds: 3600

budgets:
  limit: 500.00
  period: monthly
  alert_threshold_percent: 80

SDK configuration

The Agent Command Center SDK lets you set config at two levels: client-level (applies to every request) and per-request (overrides for a single call).

Client-level config

Pass a GatewayConfig to the client constructor:

from agentcc import AgentCC, GatewayConfig, CacheConfig, RetryConfig, FallbackConfig, FallbackTarget

client = AgentCC(
    api_key="sk-agentcc-your-key",
    base_url="https://gateway.futureagi.com",
    config=GatewayConfig(
        cache=CacheConfig(strategy="exact", ttl=300, namespace="prod"),
        retry=RetryConfig(max_retries=3, on_status_codes=[429, 500, 502, 503]),
        fallback=FallbackConfig(
            targets=[FallbackTarget(model="gpt-4o-mini")],
        ),
    ),
)

# All requests through this client use these settings
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

import { AgentCC } from "@futureagi/agentcc";

const client = new AgentCC({
  apiKey: "sk-agentcc-your-key",
  baseUrl: "https://gateway.futureagi.com",
  config: {
    cache: { strategy: "exact", ttl: 300, namespace: "prod" },
    retry: { maxRetries: 3, onStatusCodes: [429, 500, 502, 503] },
    fallback: {
      targets: [{ model: "gpt-4o-mini" }],
    },
  },
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

Per-request overrides

Override config for a single request using GatewayConfig.to_headers():

from agentcc import GatewayConfig, CacheConfig

override = GatewayConfig(cache=CacheConfig(force_refresh=True))

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What time is it?"}],
    extra_headers=override.to_headers(),
)

You can also set individual headers directly:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "x-agentcc-cache-force-refresh": "true",
        "x-agentcc-cache-namespace": "staging",
    },
)

Using with other clients

If you’re not using the Agent Command Center SDK, use create_headers() to generate x-agentcc-* headers for any OpenAI-compatible client (OpenAI SDK, LiteLLM, LangChain, cURL, etc.):

from openai import OpenAI
from agentcc import create_headers, GatewayConfig, CacheConfig

headers = create_headers(
    config=GatewayConfig(cache=CacheConfig(strategy="semantic", ttl=600)),
    trace_id="trace-abc",
    metadata={"team": "ml", "env": "production"},
)

client = OpenAI(
    api_key="sk-agentcc-your-key",
    base_url="https://gateway.futureagi.com/v1",
    default_headers=headers,
)

See Request & response headers for the full list of x-agentcc-* headers.

Model mapping

Model mapping creates aliases for model names. Send my-fast-model in API requests and the gateway resolves it to gpt-4o-mini (or whatever you mapped it to). Swap the underlying model any time without touching application code.

client.org_configs.update(
    org_id="your-org-id",
    config={
        "model_map": {
            "my-fast-model": "gpt-4o-mini",
            "my-smart-model": "claude-sonnet-4-6",
            "my-cheap-model": "gemini-2.0-flash",
        }
    }
)

await client.orgConfigs.update({
    orgId: "your-org-id",
    config: {
        model_map: {
            "my-fast-model": "gpt-4o-mini",
            "my-smart-model": "claude-sonnet-4-6",
            "my-cheap-model": "gemini-2.0-flash",
        },
    },
});

Self-hosted config.yaml:

model_map:
  my-fast-model: gpt-4o-mini
  my-smart-model: claude-sonnet-4-6
  my-cheap-model: gemini-2.0-flash

Then use the alias in requests:

response = client.chat.completions.create(
    model="my-fast-model",  # resolves to gpt-4o-mini
    messages=[{"role": "user", "content": "Hello"}],
)

GatewayConfig reference

The GatewayConfig dataclass groups all per-request config overrides:

GatewayConfig.to_headers() serializes the entire config to x-agentcc-config as a JSON header, plus individual backward-compatible headers for cache, guardrail, and timeout settings.

Next Steps