Configuration Reference

Controls LLM behavior, model selection, cost limits, and rate limiting.

Note: TypeScript SDK rate limit defaults differ significantly from Python: rateLimitMaxRetries defaults to 20 (vs 5 in Python) and rateLimitMaxDelay defaults to 300s (vs 30s in Python).

Per-Call Override

Every AIConfig field can be overridden on individual app.ai() calls:

# Agent defaults to GPT-4o
# This call uses Claude at temperature 0.0
result = await app.ai(
    user="Analyze this contract clause.",
    model="anthropic/claude-sonnet-4-20250514",
    temperature=0.0,
    max_tokens=8192,
)

Controls internal async execution behavior: adaptive polling intervals, connection pooling, timeouts, batching, and circuit breakers. This is a low-level tuning configuration -- most users do not need to modify it.

Async executions are initiated via the REST API (POST /api/v1/execute/async/:target). The Python SDK's AsyncConfig controls how the SDK internally polls for completion.

from agentfield.async_config import AsyncConfig

config = AsyncConfig(
    default_execution_timeout=600.0,
    max_concurrent_executions=2048,
    enable_event_stream=True,
)
# Or load from AGENTFIELD_ASYNC_* environment variables:
config = AsyncConfig.from_environment()

Controls memory behavior and scope configuration.

Python (MemoryConfig dataclass):

TypeScript (MemoryConfig interface):

Go: The Go SDK uses a pluggable MemoryBackend interface on the Config struct instead of a MemoryConfig. See the Go SDK docs for details on NewInMemoryBackend() and NewControlPlaneMemoryBackend().

Memory storage backends (Redis, PostgreSQL, etc.) are configured at the control plane level, not in the SDK memory config.

Controls harness orchestration -- provider, max turns, cost caps, and tool configuration.

provider is optional. Left unset, harness calls run AForge, AgentField's native harness, which is installed alongside the af binary and needs only OPENROUTER_API_KEY. Precedence: an explicit provider (per call, then on the config), then AGENTFIELD_HARNESS_PROVIDER, then "aforge".

# Harness with a tight turn cap for simple tasks -- default worker, nothing to install
simple_harness = HarnessConfig(
    max_turns=3,
)

# Harness with a deeper turn cap for complex analysis
deep_harness = HarnessConfig(
    max_turns=60,
)

# Bring your own coding agent -- one field, plus that provider's install and key
claude_harness = HarnessConfig(
    provider="claude-code",
    max_turns=20,
    max_budget_usd=5.0,
)

max_budget_usd reaches the claude-code provider only. AForge takes a token budget rather than a dollar cap, so bound an AForge run with max_turns and AGENTFIELD_HARNESS_TIMEOUT_SECONDS (default 1800), then read result.cost_usd after the run.

Controls webhook delivery for execution completion notifications.

Webhook retry behavior (max retries, backoff, timeouts) is configured at the control plane level, not in the SDK's WebhookConfig.

Controls tool calling behavior within app.ai() and harness runs.

from agentfield import ToolCallConfig

result = await app.ai(
    system="You are a data analyst with access to tools.",
    user="What were our top 5 products last quarter?",
    tools=ToolCallConfig(
        max_turns=3,
        max_tool_calls=10,
        tags=["database"],
        agent_ids=["data-agent"],
    ),
)

Agentic Resource Discovery (ARD) is configured at the control-plane level, not in an individual SDK agent.

Config says what the deployment is allowed to do. The database stores what operators have currently enabled in the UI: per-reasoner publish toggles, metadata overrides, imported external entries, callable bindings, and registry records.

agentfield:
  ard:
    enabled: true
    public_base_url: "https://control-plane.example.com"
    publisher_domain: "example.com"
    host:
      display_name: "Example AgentField Control Plane"
      identifier: "did:web:example.com"
      documentation_url: "https://example.com/docs/agents"
    publish:
      enabled: true
      include_health_statuses: ["active", "unknown"]
      default_type: "application/openapi+json"
    registry:
      enabled: true
      public: true
    external:
      search_enabled: true
      invocation_enabled: false
      allowed_registries:
        - "https://registry.partner.example/api/v1/ard"
      default_search_limit: 10

See Expose agents to external discovery for the operator workflow.

All config values can be set via environment variables. Explicit parameters take precedence over environment variables, which take precedence over defaults (i.e., explicit params > env vars > defaults).