Skip to main content

Databricks Responses agents

The registry has two Databricks integrations. Each integration sends text to a Responses API endpoint and combines streamed text into one Spec27 agent response. Choose the integration based on who owns conversation history.

Choose an integration​

Registry integrationHistory ownerUse it for
Databricks Single-Turn Responses AgentNoneClassification, extraction, routing, and other independent requests.
Databricks Client-History Responses AgentSpec27 fixtureConversational agents whose endpoint expects the complete Responses item history on every turn. This includes agents that run tools within Databricks.

The client-history endpoint is stateless, but its JavaScript fixture is stateful within one Spec27 sandbox session. The fixture stores the complete input and output item history, then sends it again on the next turn.

Required secrets​

SecretValue
DATABRICKS_RESPONSES_URLThe full endpoint URL. Use a Databricks App URL ending in /responses or a Model Serving URL ending in /serving-endpoints/<endpoint-name>/invocations.
DATABRICKS_TOKENA Databricks access token authorized to query that App or Model Serving endpoint.

Create a Databricks agent​

You can create a supervisor agent from the Databricks interface:

  1. Open Agents.
  2. Select Create Agent.
  3. Select Supervisor agent and configure its instructions and tools.
  4. Start a chat. Databricks deploys the agent to an endpoint.
  5. Open Endpoints and copy the endpoint name.

For a Model Serving endpoint, set DATABRICKS_RESPONSES_URL to:

https://<workspace-host>/serving-endpoints/<endpoint-name>/invocations

The endpoint must use the agent/v1/responses task. If you deploy a custom ResponsesAgent as a Databricks App, use its public App URL followed by /responses.

You can use the same deployed agent with either of the first two fixtures. The fixture determines whether Spec27 discards or resends the response history.

Create a token​

Create an access token in Databricks:

  1. Open your user menu and select Settings.
  2. Open Developer.
  3. Next to Access tokens, select Manage.
  4. Select Generate new token.
  5. Select the Model Serving API scope for a /invocations endpoint.
  6. Generate the token and store it as the DATABRICKS_TOKEN project secret in Spec27.

Your principal must have permission to query the selected agent or model. For a Databricks App /responses URL, use an OAuth token authorized for that App.

How history works​

Single turn​

The single-turn fixture sends one user item and returns the combined streamed text. It does not retain the response or include it in a later request.

Client history​

The client-history fixture keeps every successful input item and every response.output_item.done item in module state. The next request includes the complete item list. Keeping structured output items preserves intermediate function calls and function-call outputs produced by tool-using agents.

The fixture commits history only after Databricks finishes the streamed turn. An endpoint or parsing error leaves the previous history unchanged.

Both fixtures collect every response.output_text.delta, preserve output order, and join separate text outputs with a blank line before returning one string to Spec27.

Set it up​

  1. Copy the selected Databricks integration from the registry. See Registry integrations.
  2. Create its requested project secrets. See Project secrets.
  3. Preview the agent. For either multi-turn fixture, ask it to remember a unique detail in the first turn and repeat that detail in the second turn.