Agent configs

An agent config is the entire definition of an agent: its prompt, its model, and the tools it can call. You create a config once via POST /api/v1/configs and from then on, your app calls POST /api/v1/chat/{config_id} to talk to it.

Anatomy of a config

{
  "name": "Site Editor",
  "agent_type": "client-side",
  "system_prompt": "You edit websites for {tenant_name}. Today is {date}.",
  "model_config": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "tools_config": [
    "read_file",
    "write_file",
    "build_site"
  ]
}

Field	Type	What it does
`name`	string	Human-readable label. Shows in the dashboard.
`agent_type`	string	`client-side` (your app runs the tools) or `sandboxed` (we run a managed sandbox per config). Defaults to `client-side`. See Agent execution modes.
`system_prompt`	string	The agent's instructions. Supports `{variable}` interpolation.
`model_config`	object	Provider, model, and inference parameters.
`tools_config`	string[]	Names of tools the agent is allowed to call.
`workspace_image`	string	Sandboxed only. Container image. Defaults to the Nimblesite reference image.
`workspace_secrets`	object	Sandboxed only. Credentials injected into the sandbox at boot. Write-only.

Prompt variables

The system prompt is a template. These variables are resolved at runtime:

{tenant_name} — the tenant the chat call belongs to
{agent_name} — the name field of the config
{date} — today's date in ISO format

You can add custom variables by passing a template_vars object on the chat request.

Creating a config

curl -X POST https://api.nimblesite.dev/api/v1/configs \
  -H "X-API-Key: $NIMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d @config.json

The response includes the config_id you'll use for every chat call.

Listing configs

curl https://api.nimblesite.dev/api/v1/configs \
  -H "X-API-Key: $NIMBLE_KEY"

Returns every config belonging to the authenticated tenant. Other tenants' configs are never returned.

Updating a config

Configs are immutable in the current version. To change one, create a new config and switch your app over. We're tracking versioned config updates as a roadmap item — see the roadmap.

Why "config", not "agent"?

A config is a definition. An agent is what you get when you call the chat endpoint with that config. The same config can run thousands of concurrent conversations, each with its own memory. The config is the blueprint; the conversation is the running instance.