Agent Configuration Reference

Agent configuration lives in agent_setups.json (local development and self-hosted) or in your tenant's chat_bot_setups (managed deployments). Both use the same structure.

info

For managed deployments, see Managing Agents in the Platform.

Basic Structure

[
  {
    "agent_identifier": "my-agent",
    "agent_name": "agent",
    "llm_client_configuration": { ... },
    "agent_configuration": { ... }
  }
]

agent_identifier - the identifier used in API calls and the platform UI
agent_name - use "agent" for the built-in composable agent (recommended for all new configurations)
llm_client_configuration - which model to use
agent_configuration - provider configuration for the built-in agent

LLM Configuration

The LLM configuration is split across two files: agent_setups.json contains non-secret model settings, while env/agent_setups.json holds credentials (see Secrets and Local Overrides).

agent_setups.json (committed to version control):

{
  "llm_client_configuration": {
    "vendor": "openai",
    "vendor_configuration": {},
    "model_configuration": {
      "name": "gpt-5.2",
      "type": "chat",
      "temperature": 0.0,
      "reasoning_effort": "medium",
      "json_output": false,
      "seed": null,
      "parallel_tool_calls": null
    }
  }
}

`vendor`

Which LLM provider to use. Determines which key under vendor_configuration must be populated with credentials.

Value	Description
`openai`	OpenAI API (GPT-4.1, o3, etc.)
`anthropic`	Anthropic API (Claude)
`azure_openai`	Azure OpenAI / Azure AI Services
`azure_anthropic`	Azure-hosted Anthropic models
`bedrock`	Amazon Bedrock (Converse API)
`ollama`	Local Ollama instance

`model_configuration`

Field	Type	Required	Description
`name`	string	yes	Model name (e.g. `"gpt-4.1-mini"`, `"claude-sonnet-4-20250514"`, `"o3"`)
`type`	string	yes	`"chat"` for chat models, `"prompt"` for completion models
`temperature`	float	yes	Sampling temperature (0.0 = deterministic)
`max_tokens`	integer	no	Maximum tokens in the response
`reasoning_effort`	string	no	Constrains effort for reasoning models: `"low"`, `"medium"`, `"high"`
`json_output`	boolean	no	Force JSON output format (default: `false`)
`seed`	integer	no	Seed for deterministic outputs (provider support varies)
`parallel_tool_calls`	boolean	no	Allow the model to call multiple tools in parallel

env/agent_setups.json (not committed — contains secrets):

[
  {
    "agent_identifier": "my-agent",
    "llm_client_configuration": {
      "vendor_configuration": {
        "openai": {
          "openai_api_key": "sk-real-key-here",
          "openai_org": "org-xxx"
        }
      }
    }
  }
]

Supported vendors: openai, anthropic, ollama, bedrock, azure_openai, azure_anthropic. For Azure OpenAI:

agent_setups.json:

{
  "llm_client_configuration": {
    "vendor": "azure_openai",
    "model_configuration": {
      "name": "gpt-4.1-mini",
      "type": "chat"
    }
  }
}

env/agent_setups.json:

[
  {
    "agent_identifier": "my-agent",
    "llm_client_configuration": {
      "vendor_configuration": {
        "azure_openai": {
          "endpoint": "https://your-resource.openai.azure.com/",
          "api_version": "2024-02-01",
          "auth_type": "api_key",
          "api_key": {
            "api_key": "your-azure-api-key"
          }
        }
      }
    }
  }
]

Built-in Agent Provider Configuration

The agent_configuration block controls which providers are active and how they behave. All fields are optional — omit a provider's config block to disable it.

Tools

Which tool sources are available to the agent:

{
  "tools_provider_configuration": {
    "enabled": true,
    "include_sources": ["index_tools", "document_tools", "tag_tools", "web_tools"],
    "exclude_sources": [],
    "include_tools": null,
    "exclude_tools": ["dangerous_tool_name"]
  }
}

Field	Type	Default	Description
`enabled`	boolean	`true`	Master switch for tool provider
`include_sources`	list	`null`	Only activate these tool sources
`exclude_sources`	list	`null`	Permanently disable these tool sources
`include_tools`	list	`null`	Only expose these specific tools (by name)
`exclude_tools`	list	`null`	Hide these specific tools (by name)

Available tool sources: index_tools, document_tools, tag_tools, web_tools, user_document_tools, sql_database_tools, dataframe_tools, platform_docs, sub_agent.

→ See Configuring Tools for index_tools_source_configuration, DataFrame tools, and platform docs.

Skills

{
  "skills_provider_configuration": {
    "enabled": true,
    "injection_mode": "both",
    "prompt_format": "text",
    "writable_source": null
  },
  "disk_skills_source_configuration": {
    "skills_directories": ["skills/"]
  },
  "tag_note_skills_source_configuration": {
    "tag_ids": ["your-tag-id"]
  }
}

Field	Type	Default	Description
`enabled`	boolean	`true`	Master switch
`injection_mode`	string	`"both"`	`"prompt"` (system message), `"tools"` (as callable tools), or `"both"`
`prompt_format`	string	`"text"`	`"text"` or `"xml"` for how skills appear in the prompt
`writable_source`	string	`null`	Which source can be written to for skill persistence

→ See Using Agent Skills.

Memory

{
  "memory_provider_configuration": {
    "enabled": false,
    "inject_context": true,
    "provide_tools": true,
    "writable_source": "tag_notes",
    "read_instructions": null,
    "write_instructions": null
  }
}

Field	Type	Default	Description
`enabled`	boolean	`false`	Master switch (disabled by default)
`inject_context`	boolean	`true`	Inject memory contents into conversation context
`provide_tools`	boolean	`true`	Expose memory read/write as tools
`writable_source`	string	`null`	Which backend to write to (`"tag_notes"`)
`read_instructions`	string	`null`	Custom instructions for the memory read tool
`write_instructions`	string	`null`	Custom instructions for the memory write tool

→ See Configuring Memory.

Context

{
  "context_provider_configuration": {
    "enabled": true,
    "injection_mode": "conversation",
    "content_format": "xml",
    "max_item_content_length": null,
    "document_context_source_configuration": {
      "metadata_fields": ["title", "source", "abstract"]
    },
    "tag_context_source_configuration": { "enabled": true },
    "user_document_context_source_configuration": { "enabled": true },
    "user_workspace_context_source_configuration": { "enabled": true }
  }
}

Field	Type	Default	Description
`enabled`	boolean	`true`	Master switch
`injection_mode`	string	`"conversation"`	`"prompt"` (system message), `"conversation"` (as messages), or `"both"`
`content_format`	string	`"xml"`	`"json"` or `"xml"` — how context items are formatted
`max_item_content_length`	integer	`null`	Truncate individual context items to this character length

Available context sources: documents, filters, tags, user_documents, user_workspace, images, custom, scheduled_task.

→ See Configuring Context.

Sub-Agent Delegation

{
  "agent_delegation_provider_configuration": {
    "enabled": true
  },
  "in_memory_delegable_agents_source_configuration": {
    "enabled": true,
    "agents": [
      {
        "agent_identifier": "specialist-agent",
        "description": "Specialized in X. Use for Y tasks."
      }
    ]
  }
}

→ See Configuring Delegation.

Context Window Management

{
  "context_window_configuration": {
    "enabled": false,
    "max_context_tokens": 120000,
    "preview_tokens": 200
  }
}

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable automatic context compaction
`max_context_tokens`	integer	`120000`	Start compacting when conversation exceeds this token budget
`preview_tokens`	integer	`200`	Keep this many tokens as a preview when compacting old messages

Instructions

{
  "instructions_provider_configuration": {
    "enabled": true,
    "include_sources": ["datetime", "user_instructions", "onboarding"]
  },
  "datetime_instruction_source_configuration": { "timezone": "Europe/Amsterdam" },
  "user_instruction_source_configuration": { "enabled": true, "instructions": "..." },
  "onboarding_instruction_source_configuration": { "enabled": true }
}

Available instruction sources: datetime, user_instructions, onboarding.

→ See Configuring Instructions.

Message Processing

{
  "message_processing_provider_configuration": {
    "enabled": true,
    "include_sources": ["citation_processor"]
  }
}

Runs post-processing steps on the agent's response (e.g. inserting citations).

→ See Configuring Message Processing.

User Instructions

Free-text behavioral guidance added to the system prompt:

{
  "user_instructions": "Always check for recent publications (last 6 months) before answering. Prefer primary sources over reviews."
}

Source Filtering (All Providers)

Every provider supports include_sources and exclude_sources for fine-grained control over which sources are active. This is a cross-cutting pattern - it works the same way for tools, skills, context, instructions, and message processing.

{
  "tools_provider_configuration": {
    "include_sources": ["index_tools", "document_tools"],
    "exclude_sources": ["web_tools"]
  }
}

The filtering follows a valve-chain:

Exclude - if a source name is in exclude_sources, it is always off (hard veto)
Include - if include_sources is defined and the source name is listed, it is on (overrides the source's own enabled flag)
Default - if neither list applies, the source's own enabled field determines whether it's active

This lets you precisely control which sources are active without modifying their individual configurations. For example, you can disable a source for one agent while keeping it enabled for another, using the same shared configuration.

Policies

Policies are top-level keys that affect multiple lifecycle phases simultaneously. They are not nested under any provider.

Citations

{
  "citation_configuration": {
    "strategy": "inline_url"
  }
}

Strategy	Description
`inline_url`	LLM cites as `[[N]](source_url "text")` — best for web UIs
`short_id`	LLM cites as `[[short_id]]` — 8 hex chars of doc hash
`deferred`	LLM doesn't cite inline; post-processing inserts citations
`sup_numeric`	Superscript numeric citations

→ See Configuring Policies.

Full Example

agent_setups.json:

[
  {
    "agent_identifier": "research-agent",
    "agent_name": "agent",
    "llm_client_configuration": {
      "vendor": "openai",
      "vendor_configuration": {},
      "model_configuration": {
        "name": "gpt-5.2",
        "type": "chat",
        "temperature": 0.0,
        "reasoning_effort": "medium"
      }
    },
    "agent_configuration": {
      "tools_provider_configuration": {
        "include_sources": ["index_tools", "document_tools", "tag_tools", "web_tools", "dataframe_tools"]
      },
      "index_tools_source_configuration": {
        "description": "R&D papers from ArXiv and top ML conferences, 2000–2026",
        "known_filters": [
          { "field_path": "source", "description": "Publication venue" },
          { "field_path": "year", "description": "Publication year" }
        ],
        "sort_field_mapping": { "date": "date", "citations": "citations" }
      },
      "citation_configuration": {
        "strategy": "inline_url"
      },
      "skills_provider_configuration": {
        "injection_mode": "both"
      },
      "disk_skills_source_configuration": {
        "skills_directories": ["skills/"]
      },
      "memory_provider_configuration": {
        "enabled": true,
        "writable_source": "tag_notes",
        "inject_context": true,
        "provide_tools": true
      },
      "context_provider_configuration": {
        "injection_mode": "conversation",
        "content_format": "xml",
        "tag_context_source_configuration": { "enabled": true },
        "user_document_context_source_configuration": { "enabled": true },
        "user_workspace_context_source_configuration": { "enabled": true }
      },
      "instructions_provider_configuration": {
        "include_sources": ["datetime", "onboarding"]
      },
      "datetime_instruction_source_configuration": { "timezone": "Europe/Amsterdam" },
      "onboarding_instruction_source_configuration": { "enabled": true },
      "context_window_configuration": {
        "enabled": true,
        "max_context_tokens": 120000
      },
      "user_instructions": "Focus on peer-reviewed research. Cite your sources."
    }
  }
]

Secrets and Local Overrides

Put secrets in env/agent_setups.json (not committed to version control). The two files are merged - the env/ file takes precedence for matching fields:

[
  {
    "agent_identifier": "research-agent",
    "llm_client_configuration": {
      "vendor_configuration": {
        "openai": { "openai_api_key": "sk-real-key-here", "openai_org": "org-xxx" }
      }
    }
  }
]

Custom Agent Classes (Advanced)

If you need to build a custom agent class rather than configure the built-in one, the agent_configuration keys are matched to your agent class __init__ parameters - see Custom Agent Development.

Basic Structure​

LLM Configuration​

vendor​

model_configuration​

Built-in Agent Provider Configuration​

Tools​

Skills​

Memory​

Context​

Sub-Agent Delegation​

Context Window Management​

Instructions​

Message Processing​

User Instructions​

Source Filtering (All Providers)​

Policies​

Citations​

Full Example​

Secrets and Local Overrides​

Custom Agent Classes (Advanced)​