Implantar um agente

Para implantar um agente no Vertex AI Agent Engine, escolha entre dois métodos principais:

  • Implantação de um objeto de agente: ideal para desenvolvimento interativo em ambientes como o Colab, permitindo a implantação de objetos local_agent na memória. Esse método funciona melhor para agentes com estruturas que não contêm componentes complexos e não serializáveis.
  • Implantar de arquivos de origem: esse método é adequado para fluxos de trabalho automatizados, como pipelines de CI/CD e ferramentas de infraestrutura como código, como o Terraform, permitindo implantações totalmente declarativas e automatizadas. Ele implanta seu agente diretamente do código-fonte local e não exige um bucket do Cloud Storage.

Para começar, siga estas etapas:

  1. Conclua os pré-requisitos.
  2. (Opcional) Configure o agente para implantação.
  3. Crie uma instância de AgentEngine.
  4. (Opcional) Receba o ID do recurso do agente.
  5. (Opcional) Liste as operações compatíveis.
  6. (Opcional) Conceda permissões ao agente implantado.

Também é possível usar modelos do Pacote inicial para agentes para implantação.

Pré-requisitos

Antes de implantar um agente, verifique se você concluiu as seguintes tarefas:

  1. Configure o ambiente.
  2. Desenvolver um agente.

(Opcional) Configurar o agente para implantação

É possível fazer as seguintes configurações opcionais para seu agente:

Criar uma instância AgentEngine

Esta seção descreve como criar uma instância AgentEngine para implantar um agente.

Para implantar um agente no Vertex AI Agent Engine, escolha entre os seguintes métodos:

  • Implantação de um objeto de agente para desenvolvimento interativo.

  • Implantação de arquivos de origem para fluxos de trabalho automatizados baseados em arquivos.

De um objeto de agente

Para implantar o agente na Vertex AI, use client.agent_engines.create para transmitir o objeto local_agent junto com as configurações opcionais:

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

A implantação leva alguns minutos, durante os quais as seguintes etapas acontecem em segundo plano:

  1. Um pacote dos seguintes artefatos é gerado localmente:

    • *.pkl um arquivo pickle correspondente ao local_agent.
    • requirements.txt, um arquivo de texto que contém os requisitos do pacote.
    • dependencies.tar.gz: um arquivo tar que contém pacotes extras.

  2. O pacote é enviado para o Cloud Storage (na pasta correspondente) para preparar os artefatos.

  3. Os URIs do Cloud Storage para os respectivos artefatos são especificados no PackageSpec.

  4. O serviço Vertex AI Agent Engine recebe a solicitação, cria contêineres e inicia servidores HTTP no back-end.

A latência da implantação depende do tempo total necessário para instalar os pacotes necessários. Depois de implantado, remote_agent corresponde a uma instância de local_agent que está em execução na Vertex AI e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém os seguintes atributos:

De arquivos de origem

Para fazer a implantação de arquivos de origem na Vertex AI, use client.agent_engines.create fornecendo source_packages, entrypoint_module, entrypoint_object e class_methods no dicionário de configuração, além de outras configurações opcionais. Com esse método, não é necessário transmitir um objeto de agente ou um bucket do Cloud Storage.

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

Os parâmetros para implantação de origem inline são:

  • source_packages (obrigatório, list[str]): uma lista de caminhos de arquivos ou diretórios locais a serem incluídos na implantação. O tamanho total dos arquivos e diretórios em source_packages não pode exceder 8 MB.
  • entrypoint_module (obrigatório, str): o nome totalmente qualificado do módulo Python que contém o ponto de entrada do agente (por exemplo, agent_dir.agent).
  • entrypoint_object (obrigatório, str): o nome do objeto invocável no entrypoint_module que representa o aplicativo do agente (por exemplo, root_agent).

  • class_methods (obrigatório, list[dict]): uma lista de dicionários que definem os métodos expostos do agente. Cada dicionário inclui um campo name (obrigatório), um api_mode (obrigatório) e um parameters. Consulte Listar operações compatíveis para mais informações sobre os métodos de um agente personalizado.

    Exemplo:

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (opcional, str): o caminho para um arquivo de requisitos do pip nos caminhos especificados em source_packages. O padrão é requirements.txt no diretório raiz da origem empacotada.

A implantação leva alguns minutos, durante os quais as seguintes etapas acontecem em segundo plano:

  1. O SDK da Vertex AI cria um arquivo tar.gz dos caminhos especificados em source_packages.
  2. Esse arquivo é codificado e enviado diretamente para a API Vertex AI.
  3. O serviço Vertex AI Agent Engine recebe o arquivo, extrai, instala dependências de requirements_file (se fornecido) e inicia o aplicativo do agente usando os entrypoint_module e entrypoint_object especificados.

A latência da implantação depende do tempo total necessário para instalar os pacotes necessários. Depois de implantado, remote_agent corresponde a uma instância do aplicativo de agente que está em execução na Vertex AI e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém os seguintes atributos:

Confira abaixo um exemplo de implantação de um agente usando arquivos de origem:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

(Opcional) Receber o ID do recurso do agente

Cada agente implantado tem um identificador exclusivo. Execute o comando a seguir para receber o nome do recurso do agente implantado:

remote_agent.api_resource.name

A resposta será semelhante à seguinte string:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

em que

(Opcional) Listar as operações compatíveis

Cada agente implantado tem uma lista de operações compatíveis. Execute o seguinte comando para receber a lista de operações compatíveis com o agente implantado:

remote_agent.operation_schemas()

O esquema de cada operação é um dicionário que documenta as informações de um método para o agente que você pode chamar. O conjunto de operações compatíveis depende do framework usado para desenvolver o agente:

(Opcional) Conceder permissões ao agente implantado

Se o agente implantado precisar de outras permissões, siga as instruções em Configurar a identidade e as permissões do agente.

A seguir