Agent Runtime
O Agent Runtime executa seu agente no compute serverless hospedado pelo Databricks. Ele executa o servidor do seu agente, como DurableAgentServer, no Databricks Apps, para que você implante o código em vez de fazer o provisionamento de servidores. Para saber como o Agent Runtime se encaixa com o seu framework e o servidor do agente, consulte Deploy agents on Databricks.
O que o Agent Runtime fornece
- A stable, authenticated endpoint : Each deployment is an app named
agent-bricks-<name>with its own URL. Clients authenticate with a Databricks OAuth tokens. See query agents implantado on Databricks. - Agent identity : o agente é executado como o service principal do aplicativo. Consulte Agent identity.
- Execução durável : para agentes que usam
DurableAgentServer, a implantação realiza o provisionamento de um Runtime Store para que o estado da execução sobreviva a reinicializações de workers e as execuções interrompidas possam ser recuperadas. - Rastreamento : A implantação configura o rastreamento do MLflow para o experimento ao qual o projeto se vincula. Consulte a Visão geral do rastreamento.
- Escala : execução de um agente em escala em várias instâncias. Consulte Escalonamento horizontal para apps do Databricks.
Identidade do agente
A identidade de um agente é o service principal do aplicativo no qual ele está implantado. O agente usa essa identidade para chamar as APIs do Databricks e para fazer execução de ferramentas que você adiciona com --auth app.
- Quando você faz o deploy, o
agentbricks deployconcede ao service principal acesso aos armazenamentos de estado de memória, sessão e execução usados pelo agente. - Para dar ao agente acesso a outros dados e recursos, conceda ao service principal do aplicativo as permissões de que ele precisa, como faria para qualquer aplicativo. Consulte Configurar a autorização em um aplicativo do Databricks.
- Ferramentas que usam
auth = "user"são executadas com as permissões do usuário que enviou a solicitação em vez do Service Principal. Consulte Autorização do usuário solicitante.
Pré-requisitos
-
Instale a CLI do Databricks, Python 3.11 ou acima e
uv. -
Instale a CLI do Agent Bricks:
Bashuv tool install databricks-agentbricks -
Faça login no seu workspace.
agentbricks loginsalva o perfil como default, para que comandos posteriores possam omitir--profile:Bashdatabricks auth login --host <workspace-url> --profile <profile>agentbricks login --profile <profile> -
Criar um projeto de agente e mudar para o seu diretório:
Bashagentbricks init my-agentcd my-agent
Implantar um agente
Implantar um projeto de agente com a CLI do Agent Bricks.
Implantar a partir do diretório do projeto
Para implantar o agente, faça a execução do seguinte comando no diretório do projeto:
agentbricks deploy my-agent
Para implantar em um workspace que não seja o default, passe --profile <profile>.
O diretório do projeto mantém agent.toml e app.yaml. Se você fizer a execução de agentbricks deploy a partir de qualquer outro diretório, o upload desse diretório será feito em seu lugar. Para implantar um projeto de outro diretório, passe --source <dir>.
O argumento para agentbricks deploy é o nome da implantação, com até 17 caracteres. O aplicativo se chama agent-bricks-<name>, então este exemplo cria agent-bricks-my-agent. A primeira implantação registra o nome em agent.toml, para que implantações posteriores do projeto possam omiti-lo.
A primeira implantação demora alguns minutos. O comando termina quando o agente responde às solicitações.
agentbricks deploy faz o seguinte:
- Cria ou reutiliza os armazenamentos de memória e sessão declarados em
agent.tomle concede ao Service Principal do aplicativo acesso a eles. - Para agentes que usam
DurableAgentServer, cria ou reutiliza o Runtime Store da implantação. - Configura o rastreamento.
- Implanta o aplicativo.
Para execução o agente em mais de uma instância, passe --instances:
agentbricks deploy my-agent --instances 2
Quando um agente é executado em mais de uma instância, os clientes podem enviar o ID da sessão em um cabeçalho X-Routing-Key para encaminhar todas as solicitações de uma sessão para a mesma instância.
Implantar sem esperar
Se um script ou agente de codificação tiver um timeout de comando curto, implante sem esperar e aguarde a implantação em um comando separado:
agentbricks deploy my-agent --no-wait
agentbricks deployments wait agent-bricks-my-agent
--no-wait realiza a execução das verificações rápidas e, em seguida, finaliza a implantação em um processo em segundo plano. agentbricks deployments wait espera até 100 segundos por default. Para alterar o limite, passe --timeout. O comando sai com um dos seguintes códigos:
0: o agente é implantado e responde às solicitações.1: A implantação falhou.75: O agente ainda está sendo implantado. Faça a execução do comando novamente.
Faça a execução de agentbricks deployments wait a partir do diretório do projeto ou passe --source <dir>.
Gerenciar implantações
Comando | Descrição |
|---|---|
| Liste as implantações do seu agente. |
| Show a deployment's URL, status, and description. |
| Aguarde o término de uma implantação. O default é a implantação registrada em |
| Mostrar os Logs de um deployment. |
| Comece uma implantação. |
| Parar uma implantação. Pede confirmação, a menos que você passe |
| Exclua uma implantação. Solicita confirmação, a menos que você passe |
Como cada implantação é um aplicativo, você também pode view e monitorá-lo no Databricks Apps. Consulte Registro e monitoramento para Databricks Apps.
Limitações
Não é possível alterar o servidor de agentes de uma implantação existente. Para alternar servidores, crie um novo projeto com a opção agentbricks init --server desejada e implante-o com um novo nome.