---
title: "Retrieve agent"
method: GET
path: "/v1/agents/{id}"
---

# Retrieve agent

`GET /v1/agents/{id}`

## Request

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

Retrieve detailed configuration information for a single agent. Returns agent settings including LLM provider, system prompt, advanced options, and integration status.

## Path parameters

- `id` string, uuid, required: The ID of the agent to retrieve

## Response `200`

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.

---

[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)