Pular para o conteúdo principal

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 deploy concede 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:

    Bash
    uv tool install databricks-agentbricks
  • Faça login no seu workspace. agentbricks login salva o perfil como default, para que comandos posteriores possam omitir --profile:

    Bash
    databricks auth login --host <workspace-url> --profile <profile>
    agentbricks login --profile <profile>
  • Criar um projeto de agente e mudar para o seu diretório:

    Bash
    agentbricks init my-agent
    cd 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:

Bash
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:

  1. Cria ou reutiliza os armazenamentos de memória e sessão declarados em agent.toml e concede ao Service Principal do aplicativo acesso a eles.
  2. Para agentes que usam DurableAgentServer, cria ou reutiliza o Runtime Store da implantação.
  3. Configura o rastreamento.
  4. Implanta o aplicativo.

Para execução o agente em mais de uma instância, passe --instances:

Bash
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:

Bash
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

agentbricks deployments list

Liste as implantações do seu agente.

agentbricks deployments get <app-name>

Show a deployment's URL, status, and description.

agentbricks deployments wait [<app-name>]

Aguarde o término de uma implantação. O default é a implantação registrada em agent.toml.

agentbricks deployments logs <app-name>

Mostrar os Logs de um deployment.

agentbricks deployments start <app-name>

Comece uma implantação.

agentbricks deployments stop <app-name>

Parar uma implantação. Pede confirmação, a menos que você passe --yes.

agentbricks deployments delete <app-name>

Exclua uma implantação. Solicita confirmação, a menos que você passe --yes.

Comando

Descrição

agentbricks deployments list

Liste as implantações do seu agente.

agentbricks deployments get <app-name>

Show a deployment's URL, status, and description.

agentbricks deployments wait [<app-name>]

Aguarde o término de uma implantação. O default é a implantação registrada em agent.toml.

agentbricks deployments logs <app-name>

Mostrar os Logs de um deployment.

agentbricks deployments start <app-name>

Comece uma implantação.

agentbricks deployments stop <app-name>

Parar uma implantação. Pede confirmação, a menos que você passe --yes.

agentbricks deployments delete <app-name>

Exclua uma implantação. Solicita confirmação, a menos que você passe --yes.

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.

Additional recursos​