---
title: "Create agent"
method: POST
path: "/v1/agents"
---

# Create agent

`POST /v1/agents`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents`
- Auth: HTTP bearer

Create a new agent with the specified configuration. Only Anthropic, OpenAI Responses, Gemini, and Claude Agent SDK providers are supported.

## Request body

- AgentCreateRequest
  - `name` string, required: Name of the agent
  - `systemPrompt` string: The system prompt for this agent. Limited to 200000 characters; put reference material in a knowledge base rather than in the prompt.
  - `provider` union, required: Provider configuration for creating an agent
    - union
      - object
        - `type` 'anthropic', required
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `thinking` union: Extended thinking configuration. `disabled` is stored on any model but has no effect on the models that always think (claude-fable-5-1, claude-opus-5-5, claude-fable-5): they reject an explicit opt-out, so those agents run with adaptive thinking regardless. On claude-sonnet-5-5, `disabled` (or no thinking) runs with between-tools thinking only, at `high` effort or below.
          - object
            - `type` 'enabled', required
            - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max': How much reasoning the model spends per turn when extended thinking is enabled. Defaults to `medium` when omitted, which is what every agent ran at before this field existed. `xhigh` and `max` consume substantially more thinking tokens — on Runbear's managed key that shows up directly as higher credit usage. Only the adaptive-thinking models (claude-haiku-5-5, claude-sonnet-5-5, claude-fable-5-1, claude-opus-5-5, claude-opus-5, claude-fable-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7) act on this; older models use a token budget instead and store the value without effect, so it applies if the agent is later moved to an adaptive model.
          - object
            - `type` 'disabled', required
        - `temperature` number, nullable: Temperature value for response generation
        - `model` 'claude-haiku-5-5' | 'claude-sonnet-5-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-opus-4-5-20251101' | 'claude-opus-4-1' | 'claude-opus-4-1-20250805' | 'claude-opus-4-0' | 'claude-opus-4-20250514' | 'claude-sonnet-4-6' | 'claude-sonnet-4-5' | 'claude-haiku-4-5' | 'claude-sonnet-4-0': Anthropic models available with Runbear's managed API key
        - `useOwnApiKey` false: Use managed API key (default)
      - object
        - `type` 'anthropic', required
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `thinking` union: Extended thinking configuration. `disabled` is stored on any model but has no effect on the models that always think (claude-fable-5-1, claude-opus-5-5, claude-fable-5): they reject an explicit opt-out, so those agents run with adaptive thinking regardless. On claude-sonnet-5-5, `disabled` (or no thinking) runs with between-tools thinking only, at `high` effort or below.
          - object
            - `type` 'enabled', required
            - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max': How much reasoning the model spends per turn when extended thinking is enabled. Defaults to `medium` when omitted, which is what every agent ran at before this field existed. `xhigh` and `max` consume substantially more thinking tokens — on Runbear's managed key that shows up directly as higher credit usage. Only the adaptive-thinking models (claude-haiku-5-5, claude-sonnet-5-5, claude-fable-5-1, claude-opus-5-5, claude-opus-5, claude-fable-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7) act on this; older models use a token budget instead and store the value without effect, so it applies if the agent is later moved to an adaptive model.
          - object
            - `type` 'disabled', required
        - `temperature` number, nullable: Temperature value for response generation
        - `model` 'claude-haiku-5-5' | 'claude-sonnet-5-5' | 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-opus-4-5-20251101' | 'claude-sonnet-4-6' | 'claude-sonnet-4-5' | 'claude-haiku-4-5' | 'claude-opus-4-1' | 'claude-opus-4-1-20250805' | 'claude-sonnet-4-0' | 'claude-opus-4-0' | 'claude-opus-4-20250514': All supported Anthropic models. Opus-class models are billable at ~5x the per-token rate of Sonnet — credit usage will be correspondingly higher on the managed key.
        - `useOwnApiKey` true, required: Use your own API key
        - `apiKey` string, required: Your Anthropic API key (required when useOwnApiKey is true)
    - union
      - object
        - `type` 'openai-responses', required
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `reasoning` object
          - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
        - `text` object
          - `verbosity` 'low' | 'medium' | 'high', nullable
        - `model` 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6.1-terra' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.5' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5-mini' | 'gpt-5-nano': OpenAI models available with Runbear's managed API key
        - `useOwnApiKey` false: Use managed API key (default)
      - object
        - `type` 'openai-responses', required
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `reasoning` object
          - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
        - `text` object
          - `verbosity` 'low' | 'medium' | 'high', nullable
        - `model` 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6.1-terra' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.5' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.5-pro' | 'gpt-5.4-pro' | 'gpt-5' | 'gpt-5.2' | 'gpt-4o': Any supported OpenAI Responses model, including those available only with your own API key (`gpt-5.5-pro`, `gpt-5.4-pro`, `gpt-5`, `gpt-5.2`, `gpt-4o`)
        - `useOwnApiKey` true, required: Use your own API key
        - `apiKey` string, required: Your OpenAI API key (required when useOwnApiKey is true)
    - union
      - object
        - `type` 'gemini', required
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `model` 'gemini-4-argon' | 'gemini-3.1-pro-preview' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite': Available Gemini models for managed API key
        - `useOwnApiKey` false: Use managed API key (default)
      - object
        - `type` 'gemini', required
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `model` 'gemini-4-argon' | 'gemini-3.1-pro-preview' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite': Available Gemini models for managed API key
        - `useOwnApiKey` true, required: Use your own API key
        - `apiKey` string, required: Your Gemini API key (required when useOwnApiKey is true)
    - union
      - object
        - `type` 'claude-agent-sdk', required
        - `model` union: Supported Claude models, these Gemini models: `gemini-3.1-pro-preview`, `gemini-3.8-flash`, `gemini-3.5-flash-lite`, and these OpenAI models: `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-sol`, `gpt-6.1-terra`, `gpt-5.6-terra`, `gpt-6-luna`, `gpt-5.6-luna`. Runbear-provided access uses Runbear credits.
          - 'claude-haiku-5-5' | 'claude-sonnet-5-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-opus-4-5-20251101' | 'claude-opus-4-1' | 'claude-opus-4-1-20250805' | 'claude-opus-4-0' | 'claude-opus-4-20250514' | 'claude-sonnet-4-6' | 'claude-sonnet-4-5' | 'claude-haiku-4-5' | 'claude-sonnet-4-0': Anthropic models available with Runbear's managed API key
          - 'gemini-3.1-pro-preview' | 'gemini-3.8-flash' | 'gemini-3.5-flash-lite'
          - 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-5.6-sol' | 'gpt-6.1-terra' | 'gpt-5.6-terra' | 'gpt-6-luna' | 'gpt-5.6-luna'
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `useOwnApiKey` false: Use Runbear-provided access and Runbear credits (default)
      - object
        - `type` 'claude-agent-sdk', required
        - `model` union: Supported Claude models, these Gemini models: `gemini-3.1-pro-preview`, `gemini-3.8-flash`, `gemini-3.5-flash-lite`, and these OpenAI models: `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-sol`, `gpt-6.1-terra`, `gpt-5.6-terra`, `gpt-6-luna`, `gpt-5.6-luna`. On Runbear-provided access these run on Runbear credits. With your own key, Claude models require an Anthropic API key, Gemini models require a Google AI Studio API key, and OpenAI models require an OpenAI API key, and that provider bills the usage.
          - 'claude-haiku-5-5' | 'claude-sonnet-5-5' | 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-opus-4-5-20251101' | 'claude-sonnet-4-6' | 'claude-sonnet-4-5' | 'claude-haiku-4-5' | 'claude-opus-4-1' | 'claude-opus-4-1-20250805' | 'claude-sonnet-4-0' | 'claude-opus-4-0' | 'claude-opus-4-20250514': All supported Anthropic models. Opus-class models are billable at ~5x the per-token rate of Sonnet — credit usage will be correspondingly higher on the managed key.
          - 'gemini-3.1-pro-preview' | 'gemini-3.8-flash' | 'gemini-3.5-flash-lite'
          - 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-5.6-sol' | 'gpt-6.1-terra' | 'gpt-5.6-terra' | 'gpt-6-luna' | 'gpt-5.6-luna'
        - `pinModelVersion` boolean: `true` holds `model` exactly (a specific version); `false` follows Runbear's current stable model in the same family or tier (automatic latest). When omitted, sending `model` pins it and omitting `model` leaves the pin as it is (unpinned on create). When sent with `model`, this field decides. `true` without `model` holds the stored `model`, not `effectiveModel`, so an agent that was floating onto a newer model moves back to the stored one; to freeze the model it runs on today, send `model` set to the current `effectiveModel` with `pinModelVersion: true`. Unpinning can move the agent to a newer model with different defaults: a Claude model that always thinks ignores a disabled-thinking setting, and a `maxTokens` still at the old model's default moves to the new model's default.
        - `useOwnApiKey` true, required: Use your own API key. Anthropic, Google, or OpenAI bills usage to that key.
        - `apiKey` string, required: Your Anthropic API key for a Claude model, Google AI Studio API key for a Gemini model, or OpenAI API key for an OpenAI model. Required when useOwnApiKey is true.
  - `tools` object
    - `requireApprovalForResourceChanges` boolean: Whether approval is required for resource changes
    - `requireApprovalBeforeToolCalls` boolean: Whether approval is required before any tool call. When enabled, supersedes requireApprovalForResourceChanges.
    - `integrations` string[]: List of managed integrations to enable (Anthropic only: webSearch)
  - `longTermMemory` object: Long-term memory configuration. Defaults to enabled if not provided.
    - `enabled` boolean, required: Whether long-term memory is enabled
  - `toolProgress` object: Tool activity configuration. Defaults to enabled if not provided.
    - `enabled` boolean, required: Whether tool activity is surfaced to the caller
  - `knowledgeSearch` KnowledgeSearchInput: Knowledge base search tuning parameters. Controls how knowledge base search results are ranked and filtered.
    - `maxResults` integer: Maximum documents returned per knowledge base search (1–50). Default: 5.
    - `scoreThreshold` number: Minimum relevance score to include a result (0–1). Lower means higher recall. Default: 0.444.
    - `semanticWeight` number: Weight for semantic/embedding matching vs keyword matching (0–1). 0 = all keyword, 1 = all semantic. Default: 0.4. Only effective for providers that support hybrid search (Anthropic, Gemini, Upstage). OpenAI Responses agents ignore this value.
  - `aiGateway` union: Cloudflare AI Gateway configuration for a single Anthropic or OpenAI agent, overriding the organization-level default. Set `enabled: true` with full config to override it, or `enabled: false` to opt this agent out of it.
    - object
      - `cloudflareAccountId` string, required: Cloudflare account ID
      - `gatewayName` string, required: Cloudflare AI Gateway name
      - `cfApiToken` string, required: Cloudflare API token with AI Gateway permissions
      - `enabled` true, required
    - object
      - `enabled` false, required: Explicitly opt out of org-level gateway default
  - `timeoutMinutes` integer: Maximum execution time in minutes for a single chat completion. Defaults to 6 minutes if omitted; capped at 20 minutes.

## Response `201`

Default Response

- AgentInformation: Detailed configuration information about an agent
  - `id` string, uuid, required: Unique identifier for the agent
  - `name` string, required: Name of the agent
  - `systemPrompt` string, nullable, required: The system prompt stored for this agent on Runbear. This is the configured prompt, not the fully composed one: agents that support context blocks append them to it at invocation time.
  - `provider` union, required: Provider-specific options
    - object
      - `type` 'anthropic', required
      - `model` string, required
      - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
      - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
      - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
      - `thinking` union: Extended thinking configuration
        - object
          - `type` 'enabled', required
          - `budgetTokens` number, required
          - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max': How much reasoning the model spends per turn when extended thinking is enabled. Defaults to `medium` when omitted, which is what every agent ran at before this field existed. `xhigh` and `max` consume substantially more thinking tokens — on Runbear's managed key that shows up directly as higher credit usage. Only the adaptive-thinking models (claude-haiku-5-5, claude-sonnet-5-5, claude-fable-5-1, claude-opus-5-5, claude-opus-5, claude-fable-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7) act on this; older models use a token budget instead and store the value without effect, so it applies if the agent is later moved to an adaptive model.
        - object
          - `type` 'disabled', required
      - `temperature` number, nullable: Temperature value for response generation
    - object
      - `type` 'openai-responses', required
      - `model` string, required
      - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
      - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
      - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
      - `reasoning` object: Reasoning configuration for reasoning models
        - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
        - `summary` 'auto' | 'concise' | 'detailed', nullable: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process.
      - `text` object: Configuration for response text output
        - `format` union: Response format configuration
          - object
            - `type` 'text', required
          - object
            - `type` 'json_object', required
          - object
            - `type` 'json_schema', required
            - `jsonSchema` object, required
              - …
        - `verbosity` 'low' | 'medium' | 'high', nullable: The verbosity level of the response text. Can be low, medium, or high.
    - object
      - `type` 'gemini', required
      - `model` string, required
      - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
      - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
      - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
    - object
      - `type` 'claude-agent-sdk', required
      - `model` string, required
      - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
      - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
      - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
  - `tools` ToolsConfig, required
    - `requireApprovalForResourceChanges` boolean: Whether approval is required for resource changes
    - `requireApprovalBeforeToolCalls` boolean: Whether approval is required before any tool call. When enabled, supersedes requireApprovalForResourceChanges.
    - `integrations` ManagedToolIntegration[]: List of enabled managed tool integrations
      - `type` 'managed', required
      - `id` 'webSearch' | 'codeInterpreter' | 'imageInterpretation' | 'dalleImageGeneration' | 'urlFetch' | 'currentDateFetching', required: Managed tool integration ID
      - `name` string, required: Name of the integration
  - `longTermMemory` object, required: Long-term memory configuration. When enabled, the agent remembers user preferences and frequently referenced resources across conversations.
    - `enabled` boolean, required: Whether long-term memory is enabled
  - `toolProgress` object, required: Tool activity configuration. When disabled, `thread.tool_call.progress` events are withheld from the streaming API and no tool cards are posted to the chat channels; the agent still runs the same tools and the run trace still records them. Enabled does not guarantee events — a runtime that reports no tool activity has none to send.
    - `enabled` boolean, required: Whether tool activity is surfaced to the caller
  - `responseComponents` ResponseComponents, required: Interactive response component configuration: how often the agent answers with a component (`frequency`; absent from storage means "off") and which components it may use (`components`).
    - `frequency` string, required: How often the agent is nudged to answer with an interactive response component. Currently one of: off, low, medium, high. New levels may be appended, so treat this as an open string rather than a closed union. "off" withholds the tool entirely; an agent whose type cannot emit response components reports "off" unless the dial was set while its type still supported them.
    - `components` ResponseComponentToggles, required: Resolved per-component switches: always every switch this deployment knows, with defaults filled in. New switches may be appended; treat unknown keys as additional switches, not an error. A switch is configuration, not a promise: the agent's type, the frequency dial and the agent's Choice Buttons setting also apply.
      - `choiceButtons` boolean, required: The confirm and select components on the Web SDK (one tool). Default on. Web only; the agent's global Choice Buttons setting (disableInteractivePrompts) still overrides it.
      - `card` boolean, required: The card component on the Web SDK. Default on.
      - `list` boolean, required: The list component on the Web SDK. Default off.
      - `table` boolean, required: The table component on the Web SDK. Default off.
      - `chart` boolean, required: The chart component on the Web SDK. Default off.
  - `knowledgeSearch` KnowledgeSearch, required: Knowledge base search tuning parameters. Controls how knowledge base search results are ranked and filtered.
    - `maxResults` integer, required: Maximum documents returned per knowledge base search (1–50).
    - `scoreThreshold` number, required: Minimum relevance score to include a result (0–1). Lower means higher recall.
    - `semanticWeight` number, required: Weight for semantic/embedding matching vs keyword matching (0–1). 0 = all keyword, 1 = all semantic. Only effective for providers that support hybrid search (Anthropic, Gemini, Upstage). OpenAI Responses agents ignore this value.
  - `aiGateway` AiGatewayResponse
    - `cloudflareAccountId` string, required: Cloudflare account ID
    - `gatewayName` string, required: Cloudflare AI Gateway name
    - `enabled` boolean, required: Whether routing through the gateway is active
    - `source` 'agent' | 'organization', required: Where the active gateway config comes from — agent-level override or organization default
  - `timeoutMinutes` integer, required: Maximum execution time in minutes for a single chat completion. Defaults to 6 minutes; capped at 20 minutes.
  - `createdAt` string, required: ISO 8601 timestamp when the agent was created
  - `lastModifiedAt` string, required: ISO 8601 timestamp of the last update to the agent record. May reflect system-driven updates, not only user edits.
  - `channels` string[], required: Connected communication channels (slack, teams, discord, hubspot, zendesk)
  - `toolIntegrations` ToolIntegration[], required: User-attached MCP, Pipedream, and Custom MCP integrations. Distinct from `tools.integrations`, which lists provider-builtin tools (webSearch, codeInterpreter, ...). Empty for agent types that don't support tool integrations.
    - union: A tool integration attached to an agent. Discriminated on `type`: `managed-mcp` (Runbear-managed MCP server), `pipedream` (Pipedream connector), or `custom-mcp` (caller-hosted MCP server).
      - object
        - `id` string, uuid, required: Tool integration ID.
        - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
        - `createdAt` string, required
        - `updatedAt` string, required
        - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
        - `type` 'managed-mcp', required
        - `app` string, required: Managed MCP catalog slug (e.g., "notion").
      - object
        - `id` string, uuid, required: Tool integration ID.
        - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
        - `createdAt` string, required
        - `updatedAt` string, required
        - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
        - `type` 'pipedream', required
        - `nameSlug` string, required: Pipedream app slug (e.g., "firecrawl", "aws").
        - `authType` 'keys' | 'oauth' | 'none', nullable, required: Authentication style required by the Pipedream app.
      - object
        - `id` string, uuid, required: Tool integration ID.
        - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
        - `createdAt` string, required
        - `updatedAt` string, required
        - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
        - `type` 'custom-mcp', required
        - `app` string, required: Display label for the MCP server.
        - `url` string, required: Remote MCP server URL.
        - `transportType` 'sse' | 'streamableHttp', required
        - `auth` union, required
          - object
            - `type` 'oauth', required
          - object
            - `type` 'none', required
          - object
            - `type` 'static', required
            - `headerKey` string, required
        - `httpHeaders` object: HTTP headers forwarded to the MCP server. Vault-backed values expose only `keyName`, never the secret value.

## Other responses

- `400`: Default Response
- `403`: The organization is not entitled to AI Gateway. Same plan/flag decision the org-level `/v1/ai-gateway` endpoints refuse with; `code` is `forbidden_ai_gateway_not_permitted`. Terminal until the plan changes.

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)