Agents Endpoint Object Structure

This page applies to the agents endpoint.

Example

endpoints:
  agents:
    recursionLimit: 50
    maxRecursionLimit: 100
    disableBuilder: false
    # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
    # capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr", "memory", "ask_user_question"]
    # (optional) File citation configuration for file_search capability
    maxCitations: 30 # Maximum total citations in responses (1-50)
    maxCitationsPerFile: 7 # Maximum citations from each file (1-10)
    minRelevanceScore: 0.45 # Minimum relevance score threshold (0.0-1.0)
    titleTiming: immediate
    skills:
      maxCatalogSkills: 20

This configuration enables the builder interface for agents.

recursionLimit

Default: 25

Example:

recursionLimit: 50

For more information about agent steps, see Max Agent Steps.

maxRecursionLimit

Default: If omitted, defaults to the value of recursionLimit or 50 if recursionLimit is also omitted.

Example:

maxRecursionLimit: 100

For more information about agent steps, see Max Agent Steps.

titleTiming

Default: "immediate"

Available Values:

• "immediate": Generates the title as soon as the request starts, in parallel with the model response, using the user's first message.
• "final": Defers title generation until the full response completes. This preserves the legacy behavior.

Example:

titleTiming: immediate

disableBuilder

Default: false

Example:

disableBuilder: false

allowedProviders

Default: [] (empty list, all providers allowed)

Note: Must be one of the following, or a custom endpoint name as defined in your configuration: - openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock

Example:

allowedProviders:
  - openAI
  - google

capabilities

Default: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr", "memory", "ask_user_question"]

Example:

capabilities:
  - 'deferred_tools'
  - 'execute_code'
  - 'file_search'
  - 'web_search'
  - 'artifacts'
  - 'subagents'
  - 'actions'
  - 'context'
  - 'skills'
  - 'tools'
  - 'chain'
  - 'ocr'
  - 'memory'
  - 'ask_user_question'

Note: This field is optional. If omitted, the default behavior is to include all the capabilities listed in the default. The opt-in capabilities stateful_code_sessions, run_in_background, and tool_intents are not in the default list and must be added explicitly.

skills

Controls endpoint-level Skills settings for agents.

Default: No configured cap beyond the runtime catalog limit.

Example:

skills:
  maxCatalogSkills: 20

This does not disable Skills. Use the skills capability and per-agent/model-spec skill scoping to control whether Skills are available.

maxCitations

Default: 30

Range: 1-50

Example:

maxCitations: 30

maxCitationsPerFile

Default: 7

Range: 1-10

Example:

maxCitationsPerFile: 7

minRelevanceScore

Default: 0.45 (45% relevance threshold)

Range: 0.0-1.0

Example:

minRelevanceScore: 0.45

File Citation Configuration Examples

Default Configuration (Balanced)

endpoints:
  agents:
    maxCitations: 30
    maxCitationsPerFile: 7
    minRelevanceScore: 0.45

Provides comprehensive citations while preventing overwhelming responses and filtering out low-quality matches.

Strict Configuration (High Quality)

endpoints:
  agents:
    maxCitations: 10
    maxCitationsPerFile: 3
    minRelevanceScore: 0.7

Only includes highly relevant citations with strict limits for focused responses.

Comprehensive Configuration (Research)

endpoints:
  agents:
    maxCitations: 50
    maxCitationsPerFile: 10
    minRelevanceScore: 0.0

Maximum information extraction for exhaustive research tasks, including all sources regardless of relevance.

Agent Capabilities

The capabilities field allows you to enable or disable specific functionalities for agents. The available capabilities are:

• deferred_tools: Allows agents to discover deferred MCP tools at runtime instead of loading every tool into context upfront.
• execute_code: Allows the agent to execute code.
• file_search: Enables the agent to search and interact with files. When enabled, citation behavior is controlled by maxCitations, maxCitationsPerFile, and minRelevanceScore settings.
• web_search: Enables web search functionality for agents, allowing them to search and retrieve information from the internet.
• artifacts: Enables the agent to generate interactive artifacts (React components, HTML, Mermaid diagrams).
• subagents: Enables isolated-context child agent runs. See Subagents.
• actions: Permits the agent to perform predefined actions.
• context: Enables "Upload as Text" functionality in chat, and "File Context" for agents, allowing users to upload files and have their content extracted and included directly in the conversation.
• skills: Enables Skills in the side panel, manual $ invocation, model-invoked skills, and agent skill allowlists. See Skills.
• tools: Grants the agent access to various tools.
• chain: Enables Beta feature for agent chaining, also known as Mixture-of-Agents (MoA) workflows.
• ocr: Optionally enhances "Upload as Text" in chat, and "File Context" for agents, allowing files to be uploaded and processed with OCR. Requires an OCR service to be configured.
• memory: Equips the agent with memory tools so it can store and recall information across conversations. Included in the default list. See Memory.
• ask_user_question: Enables durable question-and-resume flows, letting the agent pause a run to ask the user a question and continue once answered. Included in the default list.
• stateful_code_sessions (opt-in, experimental): Enables reusable Code Interpreter workspaces across tool calls. Highly experimental — behavior and configuration may change substantially. Not in the default list.
• run_in_background (opt-in): Allows eligible tool calls to run in the background. Code Interpreter tools are background-eligible by default when enabled, while MCP tools remain per-tool opt-ins. Not in the default list.
• tool_intents (opt-in): Enables live, model-written labels describing native and selected MCP tool calls as they run. Not in the default list.

By specifying the capabilities, you can control the features available to users when interacting with agents.

Example Configuration

Here is an example of configuring the agents endpoint with custom capabilities and file citation settings:

endpoints:
  agents:
    disableBuilder: false
    # File citation configuration
    maxCitations: 20
    maxCitationsPerFile: 5
    minRelevanceScore: 0.6
    # Custom capabilities
    capabilities:
      - 'execute_code'
      - 'file_search'
      - 'skills'
      - 'subagents'
      - 'actions'
      - 'artifacts'
      - 'context'
      - 'ocr'
      - 'web_search'

In this example:

• The builder interface is enabled
• File citations are limited to 20 total, with maximum 5 per file
• Only sources with 60%+ relevance are included
• IntelliAsk Agents have access to code execution, file search (with citations), Skills, Subagents, actions, artifacts, file context, ocr services if configured, and web search capabilities

Subagents

The subagents field controls which isolated child agents a parent agent can spawn when the subagents capability is available.

subagents:
  enabled: true
  allowSelf: true
  agent_ids:
    - 'agent_researcher'
    - 'agent_reviewer'

For user-facing behavior and limits, see Subagents.

Activity labels

Activity labels generate short, one-line headers summarizing contiguous blocks of reasoning and tool calls, so a long run reads as a sequence of labelled activities.

Precedence: These fields can be set under endpoints.all, endpoints.agents, or the backing provider/custom endpoint, and resolve independently by precedence (most specific wins).

Example:

endpoints:
  agents:
    activityLabel: true
    activityModel: gpt-4o-mini
    activityMaxPerRun: 20
    activityCharLimit: 2000

Activity phases

Activity phases group a run's activity blocks into higher-level phases and generate a collapsed summary for each. A phase is created for run segments that contain at least two logical activities.

Behavior: Short progress remains grouped; substantial answer text closes the active phase before the result; and later activity blocks can open another phase in the same run. Persisted phase boundaries are rebased after content compaction so they stay aligned after reload. Phase-summary evidence is also bounded by activityCharLimit.

Example:

endpoints:
  agents:
    activityPhaseLabel: true
    activityPhaseMaxPerRun: 5

toolApproval

Enables human-in-the-loop approval for matching Agent tool calls before they execute.

Programmatic hooks: Trusted programmatic hooks can provide context-aware approval policy. Hooks can only make the static policy stricter — they cannot loosen an ask/deny decision into an auto-approval.

Paused approval runs can be resumed later when a checkpointer is configured.

Example:

endpoints:
  agents:
    toolApproval:
      mode: default
      allow:
        - 'web_search'
      ask:
        - 'execute_code'
      deny:
        - 'delete_*'

checkpointer

Persists paused runs — those waiting on an Ask User question or a tool approval — so they can resume later instead of being lost.

Example:

endpoints:
  agents:
    checkpointer:
      type: mongo
      ttl: 86400

Stream circuit breakers

These limits protect the server from runaway streamed generations by capping the volume a single model turn or tool call can emit.

Example:

endpoints:
  agents:
    maxToolCallArgBytes: 65536
    maxDeltaEventsPerTurn: 10000
    maxToolCallArgBytesByTool:
      create_file: 131072

Notes

• It's not recommended to disable the builder interface unless you are using modelSpecs to define a list of agents to choose from.
• File citation configuration (maxCitations, maxCitationsPerFile, minRelevanceScore) only applies when the file_search capability is enabled.
• The relevance score is calculated using vector similarity, where 1.0 represents a perfect match and 0.0 represents no similarity.
• Citation limits help balance comprehensive information retrieval with response quality and performance.
• The context capability works without OCR configuration using text parsing methods. OCR enhances extraction quality when configured.
• The ocr capability requires an OCR service to be configured (see OCR Configuration).