Consultar um agente implementado no Azure Databricks

Aprenda a enviar pedidos para agentes implementados nas Databricks Apps ou nos endpoints de Model Serving. O Databricks fornece vários métodos de consulta para atender a diferentes casos de uso e necessidades de integração.

Selecione a abordagem de consulta que melhor se adapta ao seu caso de uso:

Método	Principais vantagens
Databricks Cliente OpenAI (Recomendado)	Integração nativa, suporte completo a recursos, recursos de streaming
API REST	Compatível com OpenAI, agnóstico à linguagem, funciona com ferramentas existentes
Funções AI: `ai_query`	Compatibilidade com OpenAI, consultar apenas agentes legados alojados em endpoints Model Serving

A Databricks recomenda o Databricks OpenAI Client para novas aplicações. Escolha a API REST ao integrar com plataformas que esperam endpoints compatíveis com OpenAI.

Databricks Cliente OpenAI (Recomendado)

A Databricks recomenda que utilize o Cliente DatabricksOpenAI para consultar um agente implementado. Dependendo da API do seu agente implantado, você usará as respostas ou o cliente de conclusão de chat:

Agentes implementados nas Aplicações

Use o seguinte exemplo para agentes alojados nas aplicações Databricks seguindo a ResponsesAgent interface, que é a abordagem recomendada para construir agentes. Deve usar um token Databricks OAuth para consultar agentes alojados nas aplicações Databricks.

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
app_name = "<agent-app-name>"  # TODO: update this with your app name

# The WorkspaceClient must be configured with OAuth authentication
# See: https://docs.databricks.com/aws/en/dev-tools/auth/oauth-u2m.html
w = WorkspaceClient()

client = DatabricksOpenAI(workspace_client=w)

# Run for non-streaming responses. Calls the "invoke" method
# Include the "apps/" prefix in the model name
response = client.responses.create(model=f"apps/{app_name}", input=input_msgs)
print(response)

# Include stream=True for streaming responses. Calls the "stream" method
# Include the "apps/" prefix in the model name
streaming_response = client.responses.create(
    model=f"apps/{app_name}", input=input_msgs, stream=True
)
for chunk in streaming_response:
    print(chunk)

Se quiseres passar em custom_inputs, podes adicioná-los com o extra_body parâmetro:

streaming_response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
    },
)
for chunk in streaming_response:
    print(chunk)

Agentes em Serviço Modelo

Use o seguinte exemplo para agentes legados alojados no Model Serving seguindo a ResponsesAgent interface. Pode usar um token Databricks OAuth ou um Personal Access Token (PAT) para consultar agentes alojados no Model Serving.

from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

client = DatabricksOpenAI()

# Run for non-streaming responses. Invokes `predict`
response = client.responses.create(model=endpoint, input=input_msgs)
print(response)

# Include stream=True for streaming responses. Invokes `predict_stream`
streaming_response = client.responses.create(model=endpoint, input=input_msgs, stream=True)
for chunk in streaming_response:
  print(chunk)

Se você quiser passar custom_inputs ou databricks_options, você pode adicioná-los com o extra_body param:

streaming_response = client.responses.create(
    model=endpoint,
    input=input_msgs,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
        "databricks_options": {"return_trace": True},
    },
)
for chunk in streaming_response:
    print(chunk)

Use o seguinte exemplo para agentes legados no modelo que serve seguindo as interfaces ChatAgent ou ChatModel.

from databricks.sdk import WorkspaceClient

messages = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

ws_client = WorkspaceClient()
client = ws_client.serving_endpoints.get_open_ai_client()

# Run for non-streaming responses. Invokes `predict`
response = client.chat.completions.create(model=endpoint, messages=messages)
print(response)

# Include stream=True for streaming responses. Invokes `predict_stream`
streaming_response = client.chat.completions.create(model=endpoint, messages=messages, stream=True)
for chunk in streaming_response:
  print(chunk)

Se você quiser passar custom_inputs ou databricks_options, você pode adicioná-los com o extra_body param:

streaming_response = client.chat.completions.create(
    model=endpoint,
    messages=messages,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
        "databricks_options": {"return_trace": True},
    },
)
for chunk in streaming_response:
    print(chunk)

API REST

A API REST do Databricks fornece interfaces para modelos compatíveis com OpenAI. Isso permite que você use agentes Databricks para atender aplicativos que exigem interfaces OpenAI.

Esta abordagem é ideal para:

Aplicativos independentes de idioma que usam solicitações HTTP
Integração com plataformas de terceiros que esperam APIs compatíveis com OpenAI
Migrando do OpenAI para o Databricks com alterações mínimas no código

Autenticar com a API REST usando um token Databricks OAuth. Consulte a Documentação de Autenticação Databricks para mais opções e informações.

Agentes implementados em aplicações

curl --request POST \
  --url <app-url>.databricksapps.com/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

Se quiser passar em custom_inputs, pode adicioná-los ao corpo do pedido:

curl --request POST \
  --url <app-url>.databricksapps.com/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 }
  }'

Agentes em Serviço Modelo

Usando o Cliente Databricks OpenAI com responses.create.
Enviar uma solicitação POST para o URL do ponto de extremidade específico (por exemplo: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Para mais informações, consulte a página de Serviço de Modelo do seu endpoint e a Documentação de Serviço de Modelo.

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

Se quiser incluir custom_inputs ou databricks_options, pode adicioná-los ao corpo do pedido:

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 },
    "databricks_options": { "return_trace": true }
  }'

Use o seguinte para agentes criados com interfaces legadas ChatAgent ou ChatModel. Isto é equivalente a:

Usando o Cliente Databricks OpenAI com chat.completions.create.
Enviar uma solicitação POST para o URL do ponto de extremidade específico (por exemplo: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Para mais informações, consulte a página de Serviço de Modelo do seu endpoint e a Documentação de Serviço de Modelo.

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/chat/completions \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "messages": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

Se quiser passar em custom_inputs ou databricks_options, pode adicioná-los ao corpo da solicitação.

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/chat/completions \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "messages": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 },
    "databricks_options": { "return_trace": true }
  }'

Funções de IA: `ai_query`

Podes usar ai_query para consultar um agente implementado alojado em servidor de modelos usando SQL. Consulte ai_query função para sintaxe SQL e definições de parâmetro.

SELECT ai_query(
  "<model name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);

Próximos passos

Monitor GenAI em produção

Comentários

Esta página foi útil?

Last updated on 2026-02-14

Partilhar via

Consultar um agente implementado no Azure Databricks

Databricks Cliente OpenAI (Recomendado)

Agentes implementados nas Aplicações

Agentes em Serviço Modelo

API REST

Agentes implementados em aplicações

Agentes em Serviço Modelo

Funções de IA: ai_query

Próximos passos

Comentários

Recursos adicionais

Funções de IA: `ai_query`