Skip to main content

Databricks Responses agents

The registry has three 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.
Databricks Managed Conversation AgentDatabricksConversational agents that use a managed memory store and a conversation.id.

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​

The single-turn and client-history integrations use these 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.

The managed-conversation integration uses these secrets:

SecretValue
DATABRICKS_HOSTYour Databricks workspace origin, such as https://<workspace>.cloud.databricks.com. Do not include a path.
DATABRICKS_MODELThe fully qualified Unity AI Gateway model service name, such as system.ai.qwen35-122b-a10b.
DATABRICKS_MEMORY_STOREThe three-part Unity Catalog memory store name, such as workspace.default.spec27_agent_memory.
DATABRICKS_TOKENA Databricks access token with access to Unity AI Gateway and the selected Unity Catalog memory store.

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. For a managed conversation, select the AI Gateway and Unity Catalog API scopes.
  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.

Prepare managed conversations​

Complete this section only for the Databricks Managed Conversation Agent.

Your workspace must have Unity Catalog enabled. A workspace administrator may need to enable managed agent memory from Previews.

For an initial validation, use a text generation model service from the system.ai schema. In Catalog Explorer, open system, then ai, and copy the model service's three-part name. You do not need to deploy a custom agent before testing the managed conversation flow.

Your Databricks principal also needs USE CATALOG, USE SCHEMA, and EXECUTE for the selected model service. It needs WRITE MEMORY STORE on the memory store.

Create the memory store​

Create one memory store for the integration. The token used for this request needs CREATE MEMORY STORE on the parent schema:

curl --request POST \
  "${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
  --header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "spec27_agent_memory",
    "catalog_name": "workspace",
    "schema_name": "default",
    "description": "Managed conversations for Spec27 evaluations"
  }'

Set DATABRICKS_MEMORY_STORE to workspace.default.spec27_agent_memory for this example. Replace workspace and default if you created the store in another catalog or schema.

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.

Managed conversation​

The first call creates a Databricks conversation backed by the configured memory store. Later calls reuse the returned conversation.id and send only the new user message. Databricks stores the conversation items.

The integration resolves the Databricks user represented by the token and binds the conversation to that user's memory scope. Each Spec27 sandbox session creates a separate conversation.id, so turns stay within their evaluation case.

All three 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.