Choose a model for an agent

Models are described by four objects, in two layers. Getting the layering right is most of the work; after that, pointing an agent at a model is one field.

Object	Layer	What it is
`provider-specs`	catalog	A provider that exists in the world — OpenAI, Anthropic
`model-specs`	catalog	A model that provider offers, with its context window and per-token costs
`provider-configs`	your workspace	Your credential and endpoint for a provider
`model-instances`	your workspace	A usable model: one provider config plus one model spec

An agent’s model_id is a model instance id. That indirection is the point: you can repoint an instance at a different provider config — a different key, a different endpoint, a proxy — without touching any agent.

Prerequisites

An access token.
An API key for the provider you intend to use.

Steps

Find the provider spec

curl -s http://localhost:8000/v1/workspaces/{workspace}/provider-specs/with-models \
  -H "Authorization: Bearer $TOKEN"

This returns providers together with the model specs each one offers, which is usually all you need to pick both ids in one call.

Create a provider config

This is where your credential lives. Store the key as a secret rather than inline where your deployment supports it — see pass secrets for the same pattern applied to MCP.

curl -X POST http://localhost:8000/v1/workspaces/{workspace}/provider-configs/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_spec_id": "<provider-spec-id>",
    "name": "OpenAI (team key)",
    "api_key": "<your-api-key>"
  }'

provider_spec_id and name are the only required fields. endpoint_url points at a compatible proxy or self-hosted gateway, which is also how you reach a provider that speaks neither protocol. Prefer api_key_secret_id, a reference to a stored secret, over an inline api_key.An endpoint_url that resolves to a private, loopback or link-local address is refused when the configuration is saved and on every call, and so is one with a query string or fragment. For a local model server such as Ollama, list its host in AGENTAREA_HTTP_PRIVATE_ALLOWLIST on the API and the worker (in Docker, localhost,host.docker.internal: localhost is what the configuration stores, and calls rewrite it to the host machine), or set AGENTAREA_HTTP_ALLOW_PRIVATE to allow every private address. Name each server: a wildcard such as *.svc.cluster.local lets every member reach every in-cluster service, the platform’s own included.

Create a model instance

curl -X POST http://localhost:8000/v1/workspaces/{workspace}/model-instances/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_id": "<provider-config-id>",
    "model_spec_id": "<model-spec-id>",
    "name": "gpt-4o (team)"
  }'

Point the agent at it

Set model_id on the agent to the instance id — at creation, or with a PATCH later. See create and configure an agent.

Verify

curl -X POST http://localhost:8000/v1/workspaces/{workspace}/model-instances/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_id": "<provider-config-id>",
    "model_spec_id": "<model-spec-id>",
    "test_message": "ping"
  }'

The test takes the config and spec ids rather than an instance id, so you can check a pairing before you create an instance for it. A failure here is a credential or endpoint problem, and it is much easier to read than the same failure surfacing mid-task.

Reach a provider that speaks neither protocol

The platform calls models over two protocols: the OpenAI HTTP API (/chat/completions, /images/generations) and Anthropic’s Messages API. A provider that speaks neither, such as Amazon Bedrock, Google Vertex AI, Azure OpenAI, SageMaker or IBM watsonx, is reached through an OpenAI-compatible gateway:

Gateway	Runs
LiteLLM proxy	on your infrastructure
Bifrost	on your infrastructure
OpenRouter	hosted; already a provider in the catalog

The gateway holds the cloud credentials (AWS keys, a GCP service account, an Azure deployment) and AgentArea holds only the gateway’s key. Create a provider config as in the steps above for an OpenAI-compatible provider spec, set endpoint_url to the gateway’s base URL (the part before /chat/completions, for example https://llm-gateway.internal.example.com/v1) and put the gateway’s key in the secret. Model names are the ones the gateway exposes. A gateway on a private address needs its host in AGENTAREA_HTTP_PRIVATE_ALLOWLIST, as a local model server does. The tradeoff is one more service to run and one more hop per call. Every workspace that uses the gateway shares the cloud identity it was configured with, so give workspaces that must not share one their own gateway.

What the model spec controls at runtime

Two fields do more than describe:

context_window seeds context management and compaction. It has no default — a task whose model declares no positive window fails at startup with InvalidExecutionSnapshot rather than running against a guess.
default_context_strategy sets the per-model default of static, hybrid or dynamic, which an agent may override.

Per-token costs drive budget accounting. Every paid call is metered, including context compaction, and a call that returns no token usage is an error rather than a free call.

Troubleshooting

The agent runs but always uses the wrong model. Check the agent’s model_id rather than the provider config — several instances can share one config. Changing a provider key did not take effect. The workflow resolves the model once at task start and caches it for the run. In-flight tasks keep the old resolution; new tasks pick up the change. A running task can be moved with the change_model command.

Create and configure an agent

Create an agent, bind it to a model instance, and give it instructions and tools

Context strategies

Three settings — static, hybrid and dynamic — decide whether large tool outputs are offloaded to

Set a budget

Cap monthly spend, per-run spend, service spend or tokens for a workspace, agent, user or single

Start here

Concepts

Guides

Self-host

Reference

API reference

API endpoints

Community

Choose a model for an agent

Prerequisites

Steps

Find the provider spec

Create a provider config

Create a model instance

Point the agent at it

Verify

Reach a provider that speaks neither protocol

What the model spec controls at runtime

Troubleshooting

Create and configure an agent

Context strategies

Set a budget

​Prerequisites

​Steps

Find the provider spec

Create a provider config

Create a model instance

Point the agent at it

​Verify

​Reach a provider that speaks neither protocol

​What the model spec controls at runtime

​Troubleshooting

​Related

Create and configure an agent

Context strategies

Set a budget

Prerequisites

Steps

Verify

Reach a provider that speaks neither protocol

What the model spec controls at runtime

Troubleshooting

Related