Provider configuration

LLM and embedding calls route through ProviderConfig on each agent. The runtime reads API keys from environment variables named in api_key_env, never from workflow JSON or browser bundles. Provider failures map to typed errors and trace events shared across SDK and server.

Agent field reference: Defining agents. Install and env setup: Install and build.

ProviderConfig shape

{
 "provider": {
 "provider_id": "openai",
 "model": "gpt-4o-mini",
 "api_key_env": "OPENAI_API_KEY",
 "params": {
 "temperature": 0.3,
 "max_tokens": 4096
 }
 }
}

Supported chat providers

OpenAI example

{
 "provider_id": "openai",
 "model": "gpt-4o-mini",
 "api_key_env": "OPENAI_API_KEY"
}

Anthropic example

{
 "provider_id": "anthropic",
 "model": "claude-3-5-sonnet-20241022",
 "api_key_env": "ANTHROPIC_API_KEY"
}

Stub (local and CI)

{
 "provider_id": "stub",
 "model": "stub-v1",
 "api_key_env": ""
}

First workflow in five minutes uses stub implicitly when no provider is configured.

Embedding provider strings

Vector memory uses a separate embedding string on memory_config.embedding, not ProviderConfig:

{
 "memory_config": {
 "memory_type": "vector",
 "embedding": "openai/text-embedding-3-small",
 "namespace": "product-docs"
 }
}

Production also requires:

• ARCFLOW_QDRANT_URL
• ARCFLOW_EMBEDDING_PROVIDER (non-stub in prod)
• OPENAI_API_KEY (when embedding string uses OpenAI)

See Vector RAG pipeline.

Trace events

Example:

{
 "kind": "ProviderResponseReceived",
 "run_id": "r1",
 "step_id": "s1",
 "provider_id": "openai",
 "model_id": "gpt-4o-mini",
 "tokens": { "input": 120, "output": 45, "total": 165 },
 "latency_ms": 890
}

Error mapping

See Error codes for the full list.

Server deployment

Set keys in the server environment or secrets manager, not in Postgres:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export COHERE_API_KEY=... # rerank only

Docker Compose: docker/docker-compose.server.yml documents the expected service env block.

Security rules

• No API keys in workflow JSON, registry payloads, or static JS bundles
• Relay and static SDK never see LLM keys; server holds them
• Logs and traces are metadata-only trace only (Trace data policy)

Python and TypeScript shorthand

Python SDK often accepts provider="openai/gpt-4o-mini" with separate api_key_env.

TypeScript:

provider: {
 providerId: "openai",
 model: "gpt-4o-mini",
 apiKeyEnv: "OPENAI_API_KEY",
}

Related pages

• Tool execution loop
• Hybrid retrieval and reranking (Cohere rerank)
• Retry and backoff (ProviderRateLimited)
• Python quickstart