Document inference_id parameter for Agent Builder model routing (#7287)

Closes elastic/docs-content-internal#1255

Documents the `inference_id` / `connector_id` parameters for per-request
model routing on the Agent Builder Converse API.

## Context

elastic/kibana#262014 shipped a public alias for `connector_id` used for
**agent model routing** on the **Converse API** and the **`ai.agent`
workflow step**.

## Changes

- `agent-builder/kibana-api.md`: new "Route a request to a specific
model" example in **Chat and conversations**, covering `connector_id` /
`inference_id`, mutual exclusivity, and default behavior.
- `agent-builder/models.md`: new "Select a model for a single request"
section pointing to the API.

The `ai.agent` workflow step is documented separately — see **Related**.

## Details

- **Source:** elastic/kibana#262014 (by @ashatova, merged 2026-04-10)
- **Availability:** `stack: ga 9.4+`, `serverless: ga`
- Sending both `connector_id` and `inference_id` returns `400 Bad
Request`; omitting both uses the agent's default model.

## Related

- Companion PR #7289
corrects the `ai.agent` workflow step docs (`agents-and-workflows.md`),
including its `connector-id` / `inference-id` model routing. No file
overlap between the two.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com>

Author: 3 people

explore-analyze/ai-features/agent-builder/kibana-api.md

@@ -1072,6 +1072,48 @@ curl -X POST "${KIBANA_URL}/api/agent_builder/converse/async" \
 
 ::::
 
+**Example:** Route a request to a specific model {applies_to}`stack: ga 9.4+`
+
+By default, an agent uses its configured model. To override the model for a single request, pass either `connector_id` or `inference_id` in the request body:
+
+* `inference_id` takes an [{{infer}} endpoint](models.md#add-an-inference-endpoint) ID.
+* `connector_id` takes a [connector](models.md#configure-a-connector) ID.
+
+Both parameters route the request to the same underlying model and are mutually exclusive. If you send both, the request fails with a `400` error. If you omit both, the agent uses its default model.
+
+::::{tab-set}
+:group: api-examples
+
+:::{tab-item} Console
+:sync: console
+```console
+POST kbn://api/agent_builder/converse
+{
+  "input": "What is Elasticsearch?",
+  "agent_id": "elastic-ai-agent",
+  "inference_id": "my-inference-endpoint-id"
+}
+```
+:::
+
+:::{tab-item} curl
+:sync: curl
+```bash
+curl -X POST "${KIBANA_URL}/api/agent_builder/converse" \
+     -H "Authorization: ApiKey ${API_KEY}" \
+     -H "kbn-xsrf: true" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "input": "What is Elasticsearch?",
+       "agent_id": "elastic-ai-agent",
+       "inference_id": "my-inference-endpoint-id"}'
+```
+:::{include} _snippets/spaces-api-note.md
+:::
+:::
+
+::::
+
 **Example:** List conversations
 
 This example uses the [list conversations API]({{kib-apis}}operation/operation-get-agent-builder-conversations).

explore-analyze/ai-features/agent-builder/models.md

@@ -57,6 +57,22 @@ To learn more, refer to [select a different model](/explore-analyze/ai-features/
 :screenshot:
 :::
 
+## Select a model for a single request
+
+```{applies_to}
+stack: ga 9.4+
+serverless: ga
+```
+
+When you call an agent through the [Converse API](kibana-api.md#chat-and-conversations), you can override the agent's configured model for that request. Pass one of the following in the request body:
+
+* `inference_id`: the ID of an [{{infer}} endpoint](#add-an-inference-endpoint).
+* `connector_id`: the ID of a [connector](#configure-a-connector).
+
+Both parameters route the request to the same underlying model and are mutually exclusive. If you send both, the request fails with a `400` error. If you omit both, the agent uses its default model.
+
+For an example request, refer to [Route a request to a specific model](kibana-api.md#chat-and-conversations).
+
 ## Change the default model
 
 ::::{applies-switch}