{ "swagger": "2.0", "info": { "title": "Databricks Genie Agent Mode - SSE startup PoC", "description": "Experimental managed-transport PoC. Uses only Context.SendAsync; creates no HTTP client. Starts a new STANDARD Agent mode conversation and extracts response.created if the platform exposes SSE incrementally. This early-streaming behavior is not guaranteed by the documented SendAsync contract and must be validated in the target environment. Requires Script.cs; not a certified connector.", "version": "1.1" }, "host": "adb-REPLACE.azuredatabricks.net", "basePath": "/", "schemes": ["https"], "consumes": ["application/json"], "produces": ["application/json"], "securityDefinitions": { "DatabricksBearer": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "For this PoC, store the complete Databricks bearer credential in the connection. The managed transport applies authentication; the script does not read the credential header. Never enter credentials in flow inputs or source files. Production OAuth requires separate validation." } }, "security": [{"DatabricksBearer": []}], "paths": { "/api/2.0/genie/agents/{agent_id}/responses": { "post": { "operationId": "StartAgentMode", "summary": "Start a STANDARD Agent mode analysis", "description": "The custom code converts question to the Databricks input envelope, reads only response.created, closes SSE and returns IDs. Creates a new conversation on every call. Never retry automatically: timeout can leave the result of the start unknown.", "x-ms-summary": "Start Agent mode", "x-ms-visibility": "important", "parameters": [ {"$ref": "#/parameters/AgentId"}, { "name": "body", "in": "body", "required": true, "schema": {"$ref": "#/definitions/StartRequest"} } ], "responses": { "200": { "description": "Databricks acknowledged the start. The analysis is still running.", "schema": {"$ref": "#/definitions/StartResult"} }, "400": {"description": "Invalid question, route or configuration.", "schema": {"$ref": "#/definitions/ConnectorError"}}, "401": {"description": "Databricks authentication rejected.", "schema": {"$ref": "#/definitions/ConnectorError"}}, "403": {"description": "Databricks denied the start.", "schema": {"$ref": "#/definitions/ConnectorError"}}, "429": {"description": "Databricks rate limit.", "schema": {"$ref": "#/definitions/ConnectorError"}}, "502": {"description": "Unexpected SSE response, network error or redirect. Do not retry automatically.", "schema": {"$ref": "#/definitions/ConnectorError"}}, "504": {"description": "Startup timed out. The analysis may still be running. Do not retry automatically.", "schema": {"$ref": "#/definitions/ConnectorError"}}, "default": {"description": "Start failed. Inspect the error code and correlation ID.", "schema": {"$ref": "#/definitions/ConnectorError"}} } } }, "/api/2.0/genie/agents/{agent_id}/conversations/{conversation_id}/items": { "get": { "operationId": "GetAgentModeItems", "summary": "Get Agent mode state and one page of conversation items", "description": "Returns the documented Databricks JSON page. Follow last_id while has_more is true. Do not expose reasoning items as the final report. Use a separate new conversation for each analysis created by StartAgentMode.", "x-ms-summary": "Get Agent mode items", "x-ms-visibility": "important", "parameters": [ {"$ref": "#/parameters/AgentId"}, {"$ref": "#/parameters/ConversationId"}, {"name": "limit", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Page size; lower it if connector response-size limits are reached."}, {"name": "after", "in": "query", "type": "string", "description": "Use the preceding page's last_id."}, {"name": "order", "in": "query", "type": "string", "enum": ["asc", "desc"], "default": "asc"} ], "responses": { "200": {"description": "Latest response state and a page of items.", "schema": {"$ref": "#/definitions/ConversationPage"}}, "default": {"description": "Databricks or connector error; do not treat as an empty result.", "schema": {"type": "object", "additionalProperties": true}} } } }, "/api/2.0/genie/agents/{agent_id}/conversations/{conversation_id}/responses/{response_id}/cancel": { "post": { "operationId": "CancelAgentModeResponse", "summary": "Request cancellation of an Agent mode response", "description": "Cancellation is not necessarily immediate. Check the subsequent conversation status; do not report cancelled merely because this action was called.", "x-ms-summary": "Cancel Agent mode response", "parameters": [ {"$ref": "#/parameters/AgentId"}, {"$ref": "#/parameters/ConversationId"}, {"name": "response_id", "in": "path", "required": true, "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "The response_id returned by StartAgentMode."} ], "responses": { "200": {"description": "Databricks cancellation response.", "schema": {"type": "object", "additionalProperties": true}}, "default": {"description": "Databricks or connector error.", "schema": {"type": "object", "additionalProperties": true}} } } } }, "parameters": { "AgentId": { "name": "agent_id", "in": "path", "required": true, "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "x-ms-summary": "Genie Agent ID", "description": "Configure a trusted Genie Agent ID in the flow; do not let the model choose an arbitrary agent." }, "ConversationId": { "name": "conversation_id", "in": "path", "required": true, "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "The conversation_id returned by StartAgentMode." } }, "definitions": { "StartRequest": { "type": "object", "additionalProperties": false, "required": ["question"], "properties": { "question": {"type": "string", "minLength": 1, "maxLength": 32768, "x-ms-summary": "Question"}, "enable_viz": {"type": "boolean", "default": false, "x-ms-summary": "Request visualizations", "description": "Requests Databricks visualizations; this connector does not itself render them."} } }, "StartResult": { "type": "object", "required": ["conversation_id", "response_id", "status"], "properties": { "conversation_id": {"type": "string"}, "response_id": {"type": "string"}, "status": {"type": "string", "enum": ["in_progress"], "description": "The start was acknowledged, not completed."} } }, "ConversationPage": { "type": "object", "required": ["data", "has_more", "status"], "properties": { "object": {"type": "string"}, "status": {"type": "string", "description": "Latest response state. Do not infer completion from an empty page."}, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": {"type": "string"}, "type": {"type": "string"}, "role": {"type": "string"}, "status": {"type": "string"}, "content": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": {"type": "string"}, "text": {"type": "string"} } } } } } }, "first_id": {"type": "string"}, "last_id": {"type": "string"}, "has_more": {"type": "boolean"} } }, "ConnectorError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "correlation_id"], "properties": { "code": {"type": "string"}, "message": {"type": "string"}, "correlation_id": {"type": "string"} } } } } } }