Pular para o conteúdo principal
Última atualização em

query agents implantado on Databricks

A forma como você faz query em um agente depende do servidor de agente que o serve. Encontre seu agente na tabela a seguir e siga a seção correspondente. Para saber mais sobre servidores de agentes, consulte Servidor de agente.

Seu agente

Hospedado no

Como query

Usos DurableAgentServer

Agent Runtime no Databricks Apps

API de invocação em /api/invocations

Usa o MLflow AgentServer ou LongRunningAgentServer (legado)

Databricks Apps

Databricks OpenAI client or the OpenAI Responses API at /responses

Implantado no Model Serving (legado)

Modelo de ponto de extremidade de serviço

Cliente OpenAI, API REST, ai_query ou AI Playground do Databricks

Seu agente

Hospedado no

Como query

Usos DurableAgentServer

Agent Runtime no Databricks Apps

API de invocação em /api/invocations

Usa o MLflow AgentServer ou LongRunningAgentServer (legado)

Databricks Apps

Databricks OpenAI client or the OpenAI Responses API at /responses

Implantado no Model Serving (legado)

Modelo de ponto de extremidade de serviço

Cliente OpenAI, API REST, ai_query ou AI Playground do Databricks

Os agentes hospedados em Databricks Apps exigem um token OAuth do Databricks. Tokens de acesso pessoal não funcionam para o Databricks Apps. Para gerar tokens OAuth a partir de um script, de um service principal, de outro aplicativo ou de um notebook, consulte Connect to an API Databricks app using token authentication.

Query um agente que usa DurableAgentServer​

Agents that use DurableAgentServer serve the invocation API. Agents that you create with the Agent Bricks CLI use DurableAgentServer, and agentbricks deploy deploys them to Agent Runtime as an app named agent-bricks-<name>. Each request to the API começar one execução of your agent, called an invocation.

Endpoint

Descrição

POST /api/invocations

Começar uma invocação. Por default, a solicitação aguarda e retorna o resultado. Defina stream para receber eventos conforme eles acontecem, ou background para retornar imediatamente.

GET /api/invocations/<id>

Retorna o status de uma invocação e, após a conclusão, sua saída.

GET /api/invocations/<id>/events?after=<event-id>

Faz a transmissão dos eventos armazenados que vêm após <event-id>. Use este endpoint para se reconectar a uma transmissão.

Endpoint

Descrição

POST /api/invocations

Começar uma invocação. Por default, a solicitação aguarda e retorna o resultado. Defina stream para receber eventos conforme eles acontecem, ou background para retornar imediatamente.

GET /api/invocations/<id>

Retorna o status de uma invocação e, após a conclusão, sua saída.

GET /api/invocations/<id>/events?after=<event-id>

Faz a transmissão dos eventos armazenados que vêm após <event-id>. Use este endpoint para se reconectar a uma transmissão.

Corpo da solicitação​

O corpo da solicitação para POST /api/invocations aceita os seguintes campos. O servidor rejeita solicitações que contenham outros campos.

campo

Descrição

id

Obrigatório. Um UUID gerado por você para cada invocação. O servidor trata o ID como uma key de idempotência: reenviar a mesma solicitação com o mesmo ID retorna a invocação existente em vez de executar o agente novamente. Reutilizar um ID para uma solicitação diferente retorna um erro 409.

session_id

A conversa à qual a invocação pertence. Invocações que compartilham um ID de sessão são executadas uma de cada vez, em ordem. Agentes gerados a partir dos padrões da CLI exigem este campo.

input

A entrada para o seu agente. Agentes gerados a partir dos padrões da CLI aceitam uma lista de mensagens ou um objeto com uma lista messages.

stream

Definido como true para receber eventos como eventos enviados pelo servidor (SSE).

background

Set to true to return a 202 response immediately with a status URL, and then poll for the result.

campo

Descrição

id

Obrigatório. Um UUID gerado por você para cada invocação. O servidor trata o ID como uma key de idempotência: reenviar a mesma solicitação com o mesmo ID retorna a invocação existente em vez de executar o agente novamente. Reutilizar um ID para uma solicitação diferente retorna um erro 409.

session_id

A conversa à qual a invocação pertence. Invocações que compartilham um ID de sessão são executadas uma de cada vez, em ordem. Agentes gerados a partir dos padrões da CLI exigem este campo.

input

A entrada para o seu agente. Agentes gerados a partir dos padrões da CLI aceitam uma lista de mensagens ou um objeto com uma lista messages.

stream

Definido como true para receber eventos como eventos enviados pelo servidor (SSE).

background

Set to true to return a 202 response immediately with a status URL, and then poll for the result.

O manipulador do seu agente define a estrutura de input. Os agentes gerados a partir dos padrões da CLI leem os seguintes campos quando input é um objeto:

campo

Descrição

messages

Os turnos de conversa a serem enviados ao agente.

actor

The identity whose long-term memory the agent reads and writes. If you don't pass an actor, the agent uses the session ID, so memories don't carry over to a new session. Set actor from your application's signed-in user, not from text that the user types.

model

The model to use for this invocation, instead of the model set in the agent code.

resume

A resposta a um agente que entrou em pausa para entrada humana, como a aprovação de uma chamada de ferramenta. Quando um agente está em pausa, o status da invocação é interrupted. Envie resume em uma nova invocação com o mesmo session_id para continuar.

campo

Descrição

messages

Os turnos de conversa a serem enviados ao agente.

actor

The identity whose long-term memory the agent reads and writes. If you don't pass an actor, the agent uses the session ID, so memories don't carry over to a new session. Set actor from your application's signed-in user, not from text that the user types.

model

The model to use for this invocation, instead of the model set in the agent code.

resume

A resposta a um agente que entrou em pausa para entrada humana, como a aprovação de uma chamada de ferramenta. Quando um agente está em pausa, o status da invocação é interrupted. Envie resume em uma nova invocação com o mesmo session_id para continuar.

Para permitir que o agente se lembre do que aprendeu sobre um usuário entre as sessões, passe o ID do usuário como actor:

JSON
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "support-case-123",
  "input": {
    "messages": [{ "role": "user", "content": "What does Databricks do?" }],
    "actor": "user-42"
  }
}

Para testar um agente implantado a partir do seu terminal, use agentbricks endpoint invoke. O comando procura o aplicativo e se autentica com o seu perfil da CLI.

Bash
agentbricks --profile <profile> endpoint invoke agent-bricks-<name> \
  --path /api/invocations \
  --json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"

To fazer a transmissão da response, add "stream":true to the JSON body and pass --sse. To test the agent while it execução locally with agentbricks dev, replace the app name with --url http://localhost:8000.

Transmissão, execução em segundo plano e reconexão​

  • Transmissão : Defina "stream": true. A resposta é uma transmissão SSE que inclui os eventos run.started e run.completed (ou run.failed), além dos eventos emitidos pelo seu agente, como os eventos delta com texto transmitido. Cada evento tem um ID.
  • Execução em segundo plano : defina "background": true. O servidor retorna uma resposta 202 com um status_url. Faça polling de GET /api/invocations/<id> até que o status seja completed. Se você também definir "stream": true, a resposta incluirá um events_url do qual você poderá ler eventos.
  • Reconectar : se uma transmissão for desconectada, chame GET /api/invocations/<id>/events?after=<event-id> com o ID do último evento recebido.

O exemplo em Python a seguir faz transmissão de uma resposta:

Python
with requests.post(
    f"{app_url}/api/invocations",
    headers=w.config.authenticate(),
    json={
        "id": str(uuid.uuid4()),
        "session_id": session_id,
        "input": [{"role": "user", "content": "Summarize our last conversation."}],
        "stream": True,
    },
    stream=True,
) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if line.startswith("data: "):
            print(line[len("data: "):])

Se você implantar o agente com mais de uma instância, envie o ID da sessão em um cabeçalho X-Routing-Key para direcionar todas as solicitações de uma sessão para a mesma instância.

Query um agente que usa o MLflow legado AgentServer​

Use esta seção para agentes que você implanta no Databricks Apps com o servidor de agentes herdado: o MLflow AgentServer ou LongRunningAgentServer, com a interface ResponsesAgent. Esses agentes atendem à OpenAI Responses API em /responses.

LongRunningAgentServer serve a mesma API, portanto, os exemplos a seguir também se aplicam a ela. Ela também oferece suporte a execuções em segundo plano: defina background como true na solicitação e, em seguida, recupere a resposta com GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, que faz a transmissão dos eventos após esse número de sequência.

O Databricks recomenda o cliente Databricks OpenAI para esses agentes. Inclua o prefixo apps/ no nome do modelo.

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>"

# The WorkspaceClient must use OAuth authentication.
w = WorkspaceClient()
client = DatabricksOpenAI(workspace_client=w)

# Non-streaming request
response = client.responses.create(model=f"apps/{app_name}", input=input_msgs)
print(response)

# Streaming request
streaming_response = client.responses.create(
    model=f"apps/{app_name}", input=input_msgs, stream=True
)
for chunk in streaming_response:
    print(chunk)

Para passar custom_inputs, use o parâmetro extra_body:

Python
response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_body={"custom_inputs": {"id": 5}},
)

Para obter o ID de rastreio de uma solicitação, inclua o cabeçalho x-mlflow-return-trace-id. Em seguida, use oget_tracedo MLflow para recuperar o rastreamento completo.

Python
response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_headers={"x-mlflow-return-trace-id": "true"},
)
trace_id = response.metadata["trace_id"]
trace = client.get_trace(trace_id)

query um agente legado no Model Serving​

Use esta seção para agentes legados implantados em Endpoint do Model Serving. Você pode se autenticar com um token OAuth do Databricks ou um access token pessoal. Para mover esses agentes para o Databricks Apps, consulte Migrar um agente do Model Serving para o Databricks Apps.

Para agentes que usam a interface ResponsesAgent, chame responses.create com o nome do endpoint como o modelo:

Python
from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>"

client = DatabricksOpenAI()

# Non-streaming request. Calls predict.
response = client.responses.create(model=endpoint, input=input_msgs)
print(response)

# Streaming request. Calls predict_stream.
streaming_response = client.responses.create(model=endpoint, input=input_msgs, stream=True)
for chunk in streaming_response:
    print(chunk)

Para agentes que usam as interfaces legadas ChatAgent ou ChatModel, use o cliente de conclusões de chat:

Python
from databricks.sdk import WorkspaceClient

messages = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>"

client = WorkspaceClient().serving_endpoints.get_open_ai_client()
response = client.chat.completions.create(model=endpoint, messages=messages)
print(response)

Com qualquer um dos clientes, passe custom_inputs ou databricks_options por meio do parâmetro extra_body. Por exemplo, extra_body={"databricks_options": {"return_trace": True}} retorna o rastreamento com a resposta.

Outros recursos​

Nesta página