Consultar um agente implantado no Databricks

Aprenda como enviar solicitações para agentes implantados em Databricks Apps ou para endpoints que servem como modelo. O Databricks oferece diversos 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 benefícios
Cliente OpenAI da Databricks (Recomendado)	Integração nativa, suporte completo a recursos, capacidades de transmissão
API REST	Compatível com OpenAI, independente de linguagem, funciona com ferramentas existentes
AI Functions: ai_query	Compatível com OpenAI , consulte apenas agentes legados hospedados no endpoint do modelo de serviço.

A Databricks recomenda o Databricks OpenAI Client para novos aplicativos. Escolha a APIREST ao integrar com plataformas que esperam um endpoint compatível com OpenAI.

Cliente OpenAI da Databricks (Recomendado)

A Databricks recomenda que você use o DatabricksOpenAI Client para consultar um agente implantado. Dependendo da API do seu agente implantado, você usará o cliente de respostas ou o cliente de conclusões de chat:

Agents deployed to Apps

Use o exemplo a seguir para agentes hospedados no Databricks Apps seguindo a interface ResponsesAgent , que é a abordagem recomendada para criar agentes. Você precisa usar tokens OAuth Databricks para consultar agentes hospedados no Databricks Apps.

Python

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 você quiser passar custom_inputs, pode adicioná-los com o parâmetro extra_body :

Python

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)

Agents on Model Serving

Use o exemplo a seguir para agentes legados hospedados no modelo de serviço seguindo a interface ResponsesAgent . Você pode usar tokens OAuth do Databricks ou um token de acesso pessoal (PAT) para consultar agentes hospedados no Serving Modelo.

Python

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 parâmetro extra_body :

Python

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 exemplo a seguir para agentes legados no modelo de serviço, seguindo as interfaces ChatAgent ou ChatModel.

Python

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 parâmetro extra_body :

Python

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 Databricks fornece endpoint para modelos compatíveis com OpenAI. Isso permite que você use agentes do Databricks para atender aplicativos que exigem interfaces OpenAI.

Essa abordagem é ideal para:

• Aplicativos independentes de linguagem 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 de código

Autentique-se com a API REST usando tokens OAuth Databricks . Consulte a documentação de autenticaçãoDatabricks para obter mais opções e informações.

Agents deployed to Apps

Use o exemplo a seguir para agentes hospedados no Databricks Apps seguindo a interface ResponsesAgent , que é a abordagem recomendada para criar agentes. Você precisa usar tokens OAuth Databricks para consultar agentes hospedados no Databricks Apps.

Bash

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 você quiser passar custom_inputs, pode adicioná-los ao corpo da requisição:

Bash

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 }
  }'

Agents on Model Serving

Use o exemplo a seguir para agentes legados hospedados no modelo de serviço seguindo a interface ResponsesAgent . Você pode usar tokens OAuth do Databricks ou um token de acesso pessoal (PAT) para consultar agentes hospedados no Serving Modelo. A chamada da API REST é equivalente a:

• Usando o cliente Databricks OpenAI com responses.create.
• Enviar uma solicitação POST para o URL do endpoint específico (ex: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Para obter mais informações, consulte a página do modelo de navegação do seu endpoint e a documentação do modelo de navegação.

Bash

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 você quiser passar custom_inputs ou databricks_options, pode adicioná-los ao corpo da requisição:

Bash

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 ChatAgent ou ChatModel legadas. Isso é equivalente a:

• Usando o cliente Databricks OpenAI com chat.completions.create.
• Enviar uma solicitação POST para o URL do endpoint específico (ex: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Para obter mais informações, consulte a página do modelo de navegação do seu endpoint e a documentação do modelo de navegação.

Bash

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 você quiser passar custom_inputs ou databricks_options, pode adicioná-los ao corpo da requisição:

Bash

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 }
  }'

AI Functions: ai_query

Você pode usar ai_query para consultar um agente implantado hospedado no modelo de serviço usando SQL. Consulte a funçãoai_query para obter a sintaxe SQL e as definições de parâmetros.

SQL

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

Próximas etapas

Monitorar GenAI em produção