Agent Server

An agent server is the biblioteca that turns your agent code into a serviço. It wraps the agent loop in an HTTP server, defines the API that clients call to run the agent, gerencia client connections, and determines what happens when a execução is interrupted. The agent server runs on the agent runtime. To learn how the layers fit together, see Deploy agents on Databricks.

Para novos agentes, o Databricks recomenda o servidor de agente que o AgentKit fornece, que esta página descreve. Para compará-lo com os servidores de agente legados, consulte Comparar servidores de agente no Databricks.

Requisitos

• Python 3.10 and acima.
• O pacote databricks-agentbricks, que inclui o AgentKit. Projetos que você cria com agentbricks init declaram isso como uma dependência.

AgentKit

O AgentKit é a biblioteca do Agent Bricks para criar agentes executados no Agent Runtime. Ele fornece o servidor de agente que atende seu agente, além de clientes e auxiliares para memória de agente, sessões de agente, rastreamento e autenticação. Projetos que você cria com a CLI do Agent Bricks usam o AgentKit por default.

Servidor de agente

O AgentKit fornece seu servidor de agente por meio da classe DurableAgentServer. O servidor do agente envolve o loop do seu agente em um servidor HTTP que serve a API de invocação, rastreia cada execução e recupera execuções interrompidas por falha ou reinicialização. Ele fornece:

• One API for every request mode : Synchronous, transmissão, and background invocations, plus transmissão reconnection, all served by the same handler.
• Invocações idempotentes : um ID de invocação gerado pelo cliente garante que uma solicitação retentada não comece uma execução duplicada.
• Sessões ordenadas : as invocações na mesma sessão entram em execução uma de cada vez, em ordem.
• Persistent run state : quando implantado, o status da execução, os eventos e os resultados sobrevivem às reinicializações do worker.
• Recuperação de falhas : o servidor detecta execuções interrompidas e começa uma tentativa de substituição.
• Autorização do usuário solicitante : as ferramentas podem agir com as permissões do usuário que enviou a solicitação.
• Endpoint personalizados : O servidor de agente é um aplicativo FastAPI, portanto, você pode adicionar suas próprias rotas.

O que o AgentKit inclui

AgentKit é a biblioteca Python databricks_agentkit. Ele exporta o seguinte:

Exportar	Descrição
DurableAgentServer, InvocationContext	O servidor do agente e o contexto que ele passa para os seus manipuladores de invocação e recuperação.
AgentKitClient	Um cliente para armazenamento de memória e sessão de agente. Ele cria e obtém armazenamentos, e expõe as memórias e sessões dos armazenamentos como objetos Memory, MemoryStore, MemorySearchResult, Session, SessionStore e SessionItem.
configure_tracing, start_trace	Configure o rastreamento do MLflow para o agente e comece um rastreamento em torno de uma unidade de trabalho.
workspace_client, workspace_headers	Crie um SDK WorkspaceClient autenticado do Databricks ou obtenha cabeçalhos de autenticação para chamadas HTTP diretas a partir do ambiente do agente.
list_ai_gateway_model_services	Liste os serviços de modelo que o agente pode chamar por meio do Unity Gateway.

Exportar	Descrição
DurableAgentServer, InvocationContext	O servidor do agente e o contexto que ele passa para os seus manipuladores de invocação e recuperação.
AgentKitClient	Um cliente para armazenamento de memória e sessão de agente. Ele cria e obtém armazenamentos, e expõe as memórias e sessões dos armazenamentos como objetos Memory, MemoryStore, MemorySearchResult, Session, SessionStore e SessionItem.
configure_tracing, start_trace	Configure o rastreamento do MLflow para o agente e comece um rastreamento em torno de uma unidade de trabalho.
workspace_client, workspace_headers	Crie um SDK WorkspaceClient autenticado do Databricks ou obtenha cabeçalhos de autenticação para chamadas HTTP diretas a partir do ambiente do agente.
list_ai_gateway_model_services	Liste os serviços de modelo que o agente pode chamar por meio do Unity Gateway.

A biblioteca também inclui helpers de framework em databricks_agentkit.langgraph e databricks_agentkit.openai, que os padrões gerados usam para conectar cada framework ao armazenamento de sessão. Para APIs de memória e sessão, consulte Memória do agente e Sessões do agente.

Registre seu agente

When you create a project with agentbricks init, a CLI faz isso para você. O runtime/main.py gerado cria o servidor e faz o registro dos manipuladores de invocação e recuperação do padrão, para que você edite apenas o código do agente em agent/. Siga os passos nesta seção para trazer um agente existente ou para escrever seu próprio manipulador.

Crie um DurableAgentServer e registro um manipulador de invocação assíncrona com @app.invoke. O manipulador recebe o input da solicitação e um contexto de invocação, e retorna um resultado serializável em JSON. Publique o progresso como eventos com context.emit.

Python

from databricks_agentkit import DurableAgentServer, InvocationContext

app = DurableAgentServer()


@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    await context.emit({"type": "status", "message": "Looking that up"})
    answer = await run_my_agent(input, session_id=context.session_id)
    return {"answer": answer}

Você pode fazer um registro de um manipulador de invocação e o servidor não começa sem um. O manipulador atende a todos os modos de solicitação: o cliente escolhe se deseja aguardar o resultado, fazer a transmissão de eventos, ou realizar a execução em segundo plano.

Para a execução do servidor localmente, comece-o com agentbricks dev. Projetos criados com agentbricks init incluem um ponto de entrada que executa o servidor com o Uvicorn e um arquivo app.yaml que começa o mesmo ponto de entrada após a implantação.

Contexto de execução

O segundo argumento do manipulador é um InvocationContext:

Atributo	Descrição
invocation_id	O ID que o cliente enviou para esta invocação.
session_id	The session that the invocation belongs to, or None if the client didn't send one.
attempt	The attempt number. The first attempt is 1.
is_recovery	True quando o manipulador de recuperação estiver executando uma tentativa de substituição.
emit(event)	Armazena um evento JSON, o entrega a clientes de transmissão e retorna a posição do evento na transmissão.
request_auth	O resolvedor de credenciais do usuário solicitante, quando o agente requer autorização do usuário solicitante. Caso contrário, None.

Atributo	Descrição
invocation_id	O ID que o cliente enviou para esta invocação.
session_id	The session that the invocation belongs to, or None if the client didn't send one.
attempt	The attempt number. The first attempt is 1.
is_recovery	True quando o manipulador de recuperação estiver executando uma tentativa de substituição.
emit(event)	Armazena um evento JSON, o entrega a clientes de transmissão e retorna a posição do evento na transmissão.
request_auth	O resolvedor de credenciais do usuário solicitante, quando o agente requer autorização do usuário solicitante. Caso contrário, None.

API de invocações

DurableAgentServer fornece a API de invocação em /api/invocations:

• POST /api/invocations começar uma invocação. Por default, a solicitação aguarda o resultado. Defina stream para receber eventos como Server-Sent Events, ou background para retornar imediatamente com uma URL de status.
• 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> transmissões armazenados, para que um cliente possa se reconectar após uma conexão perdida.

Para campos de solicitação, exemplos e formatos de resposta, consulte Query agentes implantados no Databricks.

Idempotência

Os clientes enviam uma key UUID id a cada invocação. O servidor trata o ID como uma key de idempotência enquanto retiene o registro de invocação: o reenvio da mesma solicitação retorna a invocação existente em vez de executar o agente novamente. A reutilização de um ID para uma solicitação diferente retorna um erro 409.

Sessões

Os clientes podem enviar um session_id para agrupar invocações em uma única conversa. O servidor armazena o ID da sessão separadamente de input, o passa para o seu manipulador como context.session_id e executa invocações que compartilham um ID de sessão uma de cada vez, em ordem. O servidor não infere uma sessão a partir do ID de invocação ou da entrada. Sem um ID de sessão, uma invocação é sem sessão.

Estado de execução

DurableAgentServer stores each invocation's request, status, heartbeats, events, and result in a Runtime Store.

• Local development : o agentbricks dev usa um Runtime Store em processo. A API de invocação se comporta da mesma maneira, mas o estado de execução é perdido quando o processo é interrompido e o servidor não reinicia o trabalho interrompido.
• Agentes implantados : agentbricks deploy provisiona um banco de dados dedicado para o Runtime Store de cada implantação em um projeto Lakebase gerenciado pelo Databricks e o reutiliza quando você reimplanta. Você não pode usar seu próprio projeto Lakebase para o Runtime Store, e não o cria nem o vincula por conta própria. Os resultados e os eventos sobrevivem a reinicializações de worker, e qualquer instância do agente pode atender a solicitações de status e reconexão. agentbricks deployments delete remove o Runtime Store junto com a implantação.

The Runtime Store holds the server's execution state. It's separate from the session and memory stores that your agent uses for conversation história and long-term memory.

Recuperação de falhas

Para recuperar execuções interrompidas por falhas ou reinicializações de um worker, registro um manipulador de recuperação com @app.recover. Quando um servidor implantado detecta que os batimentos cardíacos de uma execução pararam, ele começa uma tentativa de substituição em um worker disponível e chama o manipulador de recuperação com a entrada original.

Python

@app.recover
async def recover(input, context: InvocationContext) -> dict:
    # Resume from the agent's last checkpoint in the session store,
    # or replay the input if that's safe for your agent.
    return await resume_my_agent(input, session_id=context.session_id)

Se você não fizer o registro de um manipulador de recuperação, a recuperação automática será desativada e o servidor Logs um aviso quando começar.

A recuperação funciona da seguinte maneira:

• Quando a recuperação começa : cada execução ativa envia um heartbeat a cada poucos segundos. Se os heartbeats pararem, por exemplo, porque o worker trava, é reiniciado ou é substituído durante uma nova implantação, o servidor detecta a execução obsoleta em segundos e começa uma tentativa de substituição.
• Quando a recuperação não começa : se o seu manipulador gerar uma exceção, a invocação falhará e o servidor não a repetirá. A recuperação cobre workers interrompidos, mas não erros no código do seu agente.
• Número de tentativas : O servidor não limita o número de tentativas de recuperação. Cada tentativa de substituição aumenta context.attempt em um. Para parar após um número de tentativas, marque context.attempt no seu manipulador de recuperação e gere um erro.
• Recuperação manual : não é possível Trigger a recuperação manualmente. Reenviar uma solicitação com o mesmo ID de invocação retorna a invocação existente em vez de iniciar uma nova tentativa.

A recuperação pode realizar a execução do código do agente mais de uma vez para a mesma invocação. Uma tentativa interrompida pode já ter chamado sistemas externos antes de a tentativa de substituição começar, portanto, torne essas chamadas idempotentes.

Request-user authorization

Por default, as ferramentas do seu agente são executadas com as permissões do Service Principal do aplicativo. To execução a tool with the permissions of the user who sent the request, declare user authorization in agent.toml:

• For a gerenciada tool, set auth = "user" on the tool entry. The agentbricks tools add comandos for MCP servers, sandboxes, and Genie Agents write auth = "user" by default. Pass --auth app to use the app's identity instead.

• Para uma ferramenta que você escreve em código, declare o requisito e quaisquer escopos de API que o Agent Bricks não possa inferir:

  Toml

  [auth.user]
  required = true
  additional_api_scopes = ["sql"]

Quando um agente exige autorização do usuário, o DurableAgentServer lê a credencial do usuário nos cabeçalhos de solicitação confiáveis do Databricks Apps e a mantém na memória apenas para a tentativa ativa. O Runtime Store não armazena a credencial. No seu manipulador, obtenha um cliente do workspace para o usuário de context.request_auth:

Python

@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    user_client = context.request_auth.client_for("user")
    me = user_client.current_user.me()
    return {"answer": f"Hello, {me.user_name}"}

client_for("app") retorna um cliente que usa o service principal do aplicativo. O resolvedor é fechado quando a execução é encerrada, portanto, chame-o dentro do manipulador em vez de armazenar o cliente. Quando você executa o agente localmente com agentbricks dev, client_for("user") usa suas credenciais locais.

Ao implantar, agentbricks deploy solicita os escopos de usuário do Databricks Apps necessários para suas ferramentas. Para adicionar escopos ausentes a um aplicativo existente, passe --allow-user-scope-update. Consulte Configurar autorização em um aplicativo do Databricks.

Request-user invocations use the same synchronous, transmissão, background, and reconnection APIs. Como o servidor não armazena a credencial do usuário, ele não pode recuperar uma invocação de usuário de solicitação interrompida. The replacement attempt fails with the MCP_USER_AUTH_RECOVERY_UNSUPPORTED error before your handlers run.

Add custom Endpoint

DurableAgentServer é um aplicativo FastAPI. Adicione rotas junto à API de invocação da mesma forma que as adiciona a qualquer aplicativo FastAPI:

Python

@app.get("/status")
async def status() -> dict:
    return {"ready": True}

Padrões de framework

agentbricks init gera dois diretórios:

• agent/ contém o código do seu framework: o modelo, os prompts e as ferramentas.
• runtime/ contém o adaptador que conecta o framework a DurableAgentServer, e o ponto de entrada que registro os manipuladores de invocação e recuperação do adaptador.

O adaptador traduz cada invocação em uma chamada para o loop de agente do framework e traduz a saída do framework em eventos e um resultado. Ambos os padrões registram um manipulador de recuperação. O padrão do LangGraph é retomado a partir do seu último ponto de verificação no armazenamento de sessões, e o padrão do OpenAI Agents SDK reproduz a solicitação na mesma sessão. Para integrar um agente existente, adicione um adaptador e um ponto de entrada DurableAgentServer, e defina server = "agentbricks" na seção [agent] de agent.toml.

Comparar servidores de agente no Databricks

O Databricks fornece três servidores de agente: o servidor de agente AgentKit e dois servidores de agente legados que os padrões de aplicativo anteriores usam.

Servidor de agentes	Pacote	API do cliente	Execução durável	Usado por
AgentKit (DurableAgentServer, recomendado)	databricks_agentkit, no pacote databricks-agentbricks	API de invocação em /api/invocations: execuções síncronas, de transmissão e em segundo plano, com reconexão de transmissão	Um Armazenamento de Runtime que agentbricks deploy faz o provisionamento, além de recuperação de falhas por meio de um manipulador de recuperação	Projetos que você cria com a CLI do Agent Bricks
LongRunningAgentServer (legado)	databricks_ai_bridge.long_running, no pacote databricks-ai-bridge[agent-server]	OpenAI Responses API em /responses, com execuções em segundo plano e retomada de transmissão	Execução state in a Lakebase database that you configure. After a crash, a new attempt continues the execução from the interrupted attempt's event log.	O agent-openai-advanced e os padrões de aplicativos agent-langgraph-advanced
MLflow AgentServer (legado)	mlflow.genai.agent_server, no pacote mlflow	OpenAI Responses API em /responses: execuções síncronas e de transmissão	Nenhuma	Os padrões de aplicativos base, como agent-openai-agents-sdk

Servidor de agentes	Pacote	API do cliente	Execução durável	Usado por
AgentKit (DurableAgentServer, recomendado)	databricks_agentkit, no pacote databricks-agentbricks	API de invocação em /api/invocations: execuções síncronas, de transmissão e em segundo plano, com reconexão de transmissão	Um Armazenamento de Runtime que agentbricks deploy faz o provisionamento, além de recuperação de falhas por meio de um manipulador de recuperação	Projetos que você cria com a CLI do Agent Bricks
LongRunningAgentServer (legado)	databricks_ai_bridge.long_running, no pacote databricks-ai-bridge[agent-server]	OpenAI Responses API em /responses, com execuções em segundo plano e retomada de transmissão	Execução state in a Lakebase database that you configure. After a crash, a new attempt continues the execução from the interrupted attempt's event log.	O agent-openai-advanced e os padrões de aplicativos agent-langgraph-advanced
MLflow AgentServer (legado)	mlflow.genai.agent_server, no pacote mlflow	OpenAI Responses API em /responses: execuções síncronas e de transmissão	Nenhuma	Os padrões de aplicativos base, como agent-openai-agents-sdk

LongRunningAgentServer estende o MLflow AgentServer, e ambos atendem a agentes que implementam a interface MLflow ResponsesAgent. Para implantar e manter um agente que usa um deles, consulte Executar agentes no Databricks Apps usando o servidor de agente herddo. Para fazer uma query de um agente em qualquer um desses servidores, consulte Fazer query de agentes implantados no Databricks.

Limitações

• Não é possível alterar o servidor de agentes de uma implantação existente. Para alternar entre DurableAgentServer e seu próprio servidor, crie um novo projeto com a opção agentbricks init --server desejada e implante-o com um novo nome.
• Changing the server field in agent.toml doesn't convert existing server code into DurableAgentServer.
• Request-user authorization requires server = "agentbricks".

Recursos adicionais

• Runtime do Agente
• Fazer query de agentes implantados no Databricks
• Agent Bricks CLI