Implantar um agente

A implantação de um agente no Agent Runtime o disponibiliza remotamente para processar solicitações. Este documento explica as maneiras de implantar um agente com base no seu fluxo de trabalho de desenvolvimento: de um objeto de execução, arquivos de origem local, um Dockerfile, uma imagem de contêiner hospedada no Artifact Registry ou diretamente por um repositório Git conectado.

Para implantar um agente no Agent Runtime, escolha um dos 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 de API implantado.
  • Implantar da imagem do contêiner: esse método é semelhante ao método 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.
  • Implantar do Developer Connect: recomendado para projetos gerenciados em um repositório Git vinculado pelo Developer Connect. Esse método simplifica a implantação do agente 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 seu agente para implantação.
  3. Crie uma instância da plataforma de agentes.
  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 a CLI de 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 da plataforma de agentes

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

Para implantar um agente na plataforma de agentes, escolha um dos 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 Agent Platform, use client.agent_engines.create para transmitir o objeto local_agent junto com quaisquer 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 Agent Runtime 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 Agent Platform, 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 de tempo de execução do agente 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 plataforma do agente, 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 Plataforma de Agentes cria um arquivo tar.gz dos caminhos especificados em source_packages.
  2. Esse arquivo é codificado e enviado diretamente para a API Agent Platform.
  3. O serviço de ambiente de execução do agente recebe o arquivo, extrai, instala dependências de requirements_file (se fornecido) e inicia o aplicativo do agente usando o entrypoint_module e o 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 implantar do Dockerfile na plataforma do agente, 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 Agent Runtime 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 plataforma de agentes e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém o seguinte:

Opcional: extrair 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 o 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

Guia

Saiba como gerenciar agentes implantados no ambiente de execução gerenciado da plataforma de agentes.

Guia

Use um agente com o ambiente de execução da plataforma de agentes.