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: 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.
  • Implantar do Dockerfile: esse método é semelhante ao de implantação de arquivos de origem. Você implanta o agente diretamente do código-fonte local. Você não precisa de um bucket do Cloud Storage. Esse método é adequado se você precisar definir e controlar o servidor da API implantado.
  • Implantar da imagem do contêiner: esse método é semelhante ao de implantação do Dockerfile. Você implanta uma imagem de contêiner hospedada no Artifact Registry. Use esse método se precisar controlar o processo de build da imagem do contêiner e reduzir a latência de implantação.
  • Implantação do Developer Connect: recomendada para projetos gerenciados em um repositório Git vinculado pelo Developer Connect. Esse método simplifica a implantação de agentes diretamente do código-fonte e oferece suporte nativo ao controle de versões, à colaboração em equipe e aos pipelines de CI/CD. Antes de usar esse método, configure o link do repositório Git seguindo as instruções em Configurar o link do repositório Git do Developer Connect.

Para começar, siga estas etapas:

  1. Conclua os pré-requisitos.
  2. (Opcional) Configure o agente para implantação.
  3. Crie uma instância do 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 do Developer Connect para fluxos de trabalho baseados em Git.
  • Implantação de arquivos de origem ou Dockerfile para fluxos de trabalho baseados em arquivos.

  • Implantação de imagem de contêiner para fluxos de trabalho baseados em imagens.

Objeto Python

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.

Developer Connect

Para fazer a implantação do Developer Connect na Vertex AI, use client.agent_engines.create fornecendo developer_connect_source, entrypoint_module e entrypoint_object no dicionário de configuração, além de outras configurações opcionais. Esse método permite implantar código diretamente de um repositório Git conectado.

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Os parâmetros para a implantação do Developer Connect são:

  • developer_connect_source (obrigatório, dict): a configuração para buscar o código-fonte. Consulte configurar o link do repositório Git do Developer Connect para mais detalhes.
    • git_repository_link (obrigatório, str): o nome do recurso de link do repositório Git do Developer Connect.
    • revision (obrigatório, str): a revisão a ser buscada (ramificação, tag ou commit SHA).
    • dir (obrigatório, str): o diretório raiz do código do agente no repositório.
  • entrypoint_module (obrigatório, str): o nome do módulo Python que contém o ponto de entrada do agente, relativo ao diretório especificado em developer_connect_source.dir.
  • entrypoint_object (obrigatório, str): o nome do objeto invocável no entrypoint_module que representa o aplicativo do agente (por exemplo, root_agent).
  • requirements_file (opcional, str): o caminho para um arquivo de requisitos do pip em relação à raiz da origem. O padrão é requirements.txt.

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

  1. O serviço Vertex AI Agent Engine busca o código-fonte da revisão especificada do repositório Git.
  2. O serviço instala dependências de requirements_file (se fornecido).
  3. O serviço inicia o aplicativo do agente usando o entrypoint_module e o entrypoint_object especificados.

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.

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": "...",
  }
)

Dockerfile

Para fazer a implantação de um Dockerfile na Vertex AI, siga uma abordagem semelhante à implantação de arquivos de origem. O único lugar que muda ao implantar é a substituição de entrypoint_module, entrypoint_object e (opcionalmente) requirements_file na configuração por um image_spec.

Confira um exemplo de como implantar um agente usando um Dockerfile:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells AgentEngine to use the Dockerfile
        # Other optional configs
    }
)

Imagem do contêiner

Para fazer a implantação de uma imagem de contêiner, siga as instruções de configuração em Traga seu próprio contêiner, instalando uma versão do google-cloud-aiplatform que atenda a >=1.144. Em seguida, execute o seguinte código:

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
    },
)

Em que CONTAINER_IMAGE_URI corresponde ao URI da imagem do contêiner no Artifact Registry (como us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

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 o seguinte:

(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. Use AgentEngine.operation_schemas para acessar 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