Skip to content
GitHub

Response Components API

Read and set, over the agents REST API, which response components an agent may show in the Web SDK and how often: the same switches and dial as the dashboard's Response components section.


On this page

An agent can attach a response component to its reply in the Web SDK — a clickable confirm, a select list, a formatted card, a list of results, a sortable table, a chart of numbers, or an mcp-app view from one of the agent's own MCP servers, which these settings don't govern (see MCP Apps). The public agents API carries two per-agent settings for them on one field, responseComponents:

  • frequency — how often the agent reaches for a component. It is the dashboard's Component frequency select.
  • components — which components the agent may use at all, one switch each. They are the dashboard's Web SDK components switches; see Choosing components.

Both live in the Response components section of the dashboard's agent settings; either path writes the one value, and this page covers the API.

Authenticate with a bearer API key, created under Settings → API keys (where available). If your organization doesn't show that item, open Settings → Members, which opens your organization's account page, and manage keys in its API Keys section; see API keys. Full request and response schemas live in the OpenAPI reference.

Endpoints#

EndpointPurpose
GET /v1/agents?ids=…Read the settings for several agents. ids is required — a comma-separated list of up to 100 agent ids; omitting it is a 400
GET /v1/agents/{id}Read the settings for one agent
PATCH /v1/agents/{id}Set the level, the per-component switches, or both

PATCH requires an API key with the manageAgents capability. Reads do not. That capability is the public-surface equivalent of the dashboard's feature:write permission, which is a per-user dashboard permission with no representation on an API key — so do not look for feature:write on a key, and do not expect a key to inherit the dashboard permissions of whoever created it. Keys are issued from the dashboard by an organization admin or owner.

The dashboard is the second write path. There the dial and the switches are gated by feature:write itself, and they follow the same rule as the 422 below: a non-off level, or a switch turned on, is refused on an agent type that cannot emit it.

POST /v1/agents does not accept responseComponents; the field is ignored rather than rejected, so a create carrying it still returns 201 with the dial at off. Create the agent, then set the dial with a follow-up PATCH.

Reading the level#

responseComponents is a required field on every agent payload — GET /v1/agents, GET /v1/agents/{id}, and the create and update responses. Abridged to the relevant fields:

{
  "id": "0f2b7d1e-9c34-4a5b-8f61-2ad0c5e7b913",
  "name": "Support agent",
  "longTermMemory": { "enabled": true },
  "responseComponents": {
    "frequency": "medium",
    "components": { "choiceButtons": true, "card": true, "list": false, "table": false, "chart": false }
  }
}

An agent that has never had the dial set reads back as "off". components is always the complete map: every switch, with its default filled in where nothing was set. New switches may be added to it later, so treat a key you do not recognize as one more switch rather than an error.

Configured, not effective#

responseComponents reports what is configured, not what a visitor will see. A switch reads true even on an agent whose type cannot use it. A gemini agent that was never configured reads:

"responseComponents": {
  "frequency": "off",
  "components": { "choiceButtons": true, "card": true, "list": false, "table": false, "chart": false }
}

That agent shows no components at all: its type emits none, and the dial cannot leave off there. Likewise a claude-agent-sdk agent reads card: true and never shows a card. To know what a visitor will actually get, combine the switches with the agent's type (Which agent types can use each switch) and the conditions in What else has to be true.

Sending the map you read back in a PATCH is always accepted: a value that does not change is never refused.

Setting the level#

curl -X PATCH https://api.runbear.io/v1/agents/0f2b7d1e-9c34-4a5b-8f61-2ad0c5e7b913 \
  -H "Authorization: Bearer $RUNBEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"responseComponents":{"frequency":"medium"}}'

The response is the full agent, with responseComponents.frequency reflecting the write. frequency is optional: a request can carry only components (see Choosing components), and an omitted frequency keeps its stored value. One request can also set both:

{"responseComponents":{"frequency":"medium","components":{"chart":true}}}

The levels#

LevelWhat it does
offThe agent is not offered the components at all on this channel. This is the default, and the value an unset or unrecognized stored level reads back as.
lowOffer buttons sparingly: only when the next reply is unambiguously one of a few concrete options, and at most once per turn.
mediumThe balanced setting. Offer buttons whenever the next reply is plausibly one of a few concrete options; answer in prose when the question is genuinely open-ended.
highOffer buttons at every reasonable opportunity — whenever the turn would end in a question, a list of suggestions, or any choice the visitor could type back.

Choosing components#

The per-component switches choose which components the agent may use on the Web SDK. Each switch covers one or more components:

SwitchComponentsDefault
choiceButtonsconfirm, selectOn
cardcardOn
listlistOff
tabletableOff
chartchartOff

Turn a switch on or off with a PATCH carrying only the switches you change. This turns on list and table for one agent and leaves everything else as stored:

curl -X PATCH https://api.runbear.io/v1/agents/0f2b7d1e-9c34-4a5b-8f61-2ad0c5e7b913 \
  -H "Authorization: Bearer $RUNBEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"responseComponents":{"components":{"list":true,"table":true}}}'

The response is the full agent. Abridged, with frequency unchanged:

"responseComponents": {
  "frequency": "medium",
  "components": { "choiceButtons": true, "card": true, "list": true, "table": true, "chart": false }
}
  • Only the switches you send change. Switches are merged one by one: the rest keep their stored value, and a switch you never set keeps following its default. There is no way to replace the whole map in one write.
  • The request is strict. An unknown switch, or a value that is not true or false, is rejected with 400 bad_request before anything is stored.
  • Turning on a component the agent's type cannot emit is refused with 422 unsupported_for_agent_type, and the message names the refused switches. A claude-agent-sdk agent supports only the choiceButtons switch, and a gemini agent supports none. Sending true for a switch that already reads back as true is accepted, so a map you read can be sent back unchanged.
  • Turning a switch off is always accepted, on every agent type.

The switches choose among components only while the dial is on. frequency set to "off" still withholds every component on the Web SDK, whatever the switches say. With the choiceButtons switch off, the low, medium and high levels read the same: their guidance is about confirm and select.

The choiceButtons switch is not the agent's Choice buttons (all channels) switch (disableInteractivePrompts). That switch is the agent-wide opt-out: turning it off withdraws every component on every surface, whatever these switches say, and it wins. The choiceButtons switch only decides whether confirm and select are offered on the Web SDK, and it never affects Slack.

Before switching a component on, check that your visitors' widgets render it — see which SDK release renders what. The full order of checks is under What else has to be true, and what each switch adds to a turn is under What each switch costs.

Which agent types can use each switch#

Agent typechoiceButtonscardlisttablechart
anthropicYesYesYesYesYes
openai-responsesYesYesYesYesYes
mastraYesYesYesYesYes
claude-agent-sdkYesNoNoNoNo
geminiNoNoNoNoNo
perplexityNoNoNoNoNo
upstageNoNoNoNoNo
openai-assistantNoNoNoNoNo
  • mastra agents are configured from the dashboard, because mastra is not exposed on /v1/agents.
  • perplexity, upstage and openai-assistant agents are not exposed on /v1/agents at all.
  • Turning on a switch in a "No" cell is refused with 422; turning it off is always accepted.
  • The dashboard hides the switches an agent's type cannot use.

What each switch costs#

A switched-on component costs a fixed amount of prompt on every eligible web turn, whether or not the agent uses it: its definition and a short usage guide travel with the agent's instructions.

SwitchAdds to each eligible turnApprox. tokens per turnStarts
choiceButtonsThe buttons' definition and guide, including the frequency wording≈ 2,650On
cardThe card's definition and guide≈ 2,250On
listThe list's definition and guide≈ 2,100Off
tableThe table's definition and guide≈ 1,900Off
chartThe chart's definition and guide≈ 1,950Off

A card, list, table or chart costs slightly less when choiceButtons is off, because its guide is shorter then.

ConfigurationApprox. tokens per turn
Default agent (buttons and cards)≈ 4,900
Defaults plus one new component≈ 6,850 to 7,000
Everything on≈ 10,900

These are estimates, not billed figures: they are measured from the exact prompt text and definitions sent to Anthropic models, at about 2.7 characters per token as calibrated against Claude's own token counter. OpenAI Responses and Mastra agents are within a few percent.

  • What does not change the cost: the low, medium and high levels (see The levels); a Slack turn, which never carries these components; and a turn where frequency is off, the component's switch is off, or another server-side condition in What else has to be true fails (conditions 1 to 6), which adds nothing for that component. The visitor's SDK release does not change the cost: an older widget still receives the component and shows its fallback.
  • What adds on top: when the agent does show a component, the model writes its content, which is billed as output like the prose it replaces. A 30-row table costs more than a two-line answer.
  • Caching: repeated turns usually read the fixed part from the prompt cache rather than paying for it as fresh input; see What drove the cost for input versus cacheRead. A guide change in a Runbear release invalidates the cache once.

Turn on only the components this agent needs.

What else has to be true#

The settings are necessary but not sufficient. A component reaches a visitor only when every one of these holds. They are independent conditions, not an order of evaluation: conditions 1 to 6 decide on the server whether the agent is offered the component at all, and condition 7 decides in the visitor's browser how it is shown.

  1. The agent's Choice buttons (all channels) switch is on (disableInteractivePrompts is not true). Turning it off withdraws interactive prompts and every component on every surface, whatever the settings on this page say.
  2. The run has someone waiting on it. Scheduled and other automated runs never offer components, whatever the settings say.
  3. Response components are enabled for your organization. They are in limited availability, and Runbear turns them on per organization (see the callout at the top of this page). Until then the settings store and read back correctly and produce nothing.
  4. frequency is not off.
  5. The component's switch in components is on.
  6. The agent's type can use it — see Which agent types can use each switch.
  7. The visitor's widget runs an SDK release that renders it. On an earlier release the component arrives on the wire and the widget shows its plain-text fallback — see which SDK release renders what.

With choiceButtons set to false, low, medium and high behave identically, and cards, lists, tables and charts are offered whenever frequency is not off; the level does not change how often they appear.

Because the per-organization enablement, the Choice buttons (all channels) switch and the agent's type are separate from these settings, a GET returning "frequency": "high" or "chart": true is a statement about this agent's configuration, not a promise that a visitor will see a button or a chart.

Errors#

StatusBodyCause
400{ "error": "bad_request", … }frequency is not one of off, low, medium, high.
400{ "error": "bad_request", … }components names an unknown switch, or a switch's value is not true or false.
422{ "error": "unsupported_for_agent_type", "message": … }A non-off level was written to an agent whose type cannot emit response components, or components turned on a switch the agent's type cannot emit. The message names the refused switches.

The 422 is terminal for that agent: the dial is only meaningful on a type that supports the components, and no retry changes that. On the public agents API this is refused for gemini, which registers no tools at all. The agent types that predate this API — perplexity, upstage and openai-assistant — also cannot emit components, but they are not exposed on /v1/agents and so cannot be reached to be refused.

A switch refusal can also reach a claude-agent-sdk agent, for any switch but choiceButtons. The message names the refused switches for a person to read; branch on error, not on the message text, which may change.

Writing "off", or false for a switch, is accepted on every type, so an agent can always be returned to the default even if it could not be given a level in the first place.