Implemente um agente

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

  • Implementação a partir de um objeto de agente: ideal para o desenvolvimento interativo em ambientes como o Colab, permitindo a implementação de objetos local_agent na memória. Este método funciona melhor para agentes com estruturas que não contêm componentes complexos e não serializáveis.
  • Implementação a partir de ficheiros de origem: este método é adequado para fluxos de trabalho automatizados, como pipelines de CI/CD e ferramentas de infraestrutura como código, como o Terraform, o que permite implementações totalmente declarativas e automatizadas. Implementa o seu agente diretamente a partir do código fonte local e não requer um contentor do Cloud Storage.

Para começar, siga estes passos:

  1. Conclua os pré-requisitos.
  2. (Opcional) Configure o agente para implementação.
  3. Crie uma instância do AgentEngine.
  4. (Opcional) Obtenha o ID do recurso do agente.
  5. (Opcional) Indique as operações suportadas.
  6. (Opcional) Conceda autorizações ao agente implementado.

Também pode usar modelos do Agent Starter Pack para a implementação.

Pré-requisitos

Antes de implementar um agente, certifique-se de que concluiu as seguintes tarefas:

  1. Configure o seu ambiente.
  2. Desenvolva um agente.

(Opcional) Configure o agente para a implementação

Pode fazer as seguintes configurações opcionais para o seu agente:

Crie uma instância do AgentEngine

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

Para implementar um agente no Vertex AI Agent Engine, pode escolher entre os seguintes métodos:

  • Implementação a partir de um objeto de agente para desenvolvimento interativo.

  • Implementação a partir de ficheiros de origem para fluxos de trabalho automatizados baseados em ficheiros.

A partir de um objeto de agente

Para implementar o agente no Vertex AI, use client.agent_engines.create para transmitir o objeto local_agent juntamente 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 implementação demora alguns minutos, durante os quais os seguintes passos ocorrem em segundo plano:

  1. É gerado localmente um pacote dos seguintes artefactos:

    • *.pkl um ficheiro pickle correspondente a local_agent.
    • requirements.txt um ficheiro de texto que contém os requisitos do pacote.
    • dependencies.tar.gz um ficheiro TAR que contenha pacotes adicionais.

  2. O pacote é carregado para o Cloud Storage (na pasta correspondente) para a preparação dos artefactos.

  3. Os URIs do Cloud Storage para os artefactos respetivos são especificados no elemento PackageSpec.

  4. O serviço Vertex AI Agent Engine recebe o pedido, cria contentores e inicia servidores HTTP no back-end.

A latência da implementação depende do tempo total necessário para instalar os pacotes necessários. Após a implementação, remote_agent corresponde a uma instância de local_agent que está a ser executada no Vertex AI e pode ser consultada ou eliminada.

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

A partir de ficheiros de origem

Para implementar a partir de ficheiros 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, juntamente com outras configurações opcionais. Com este método, não precisa de transmitir um objeto de agente nem um contentor 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 a implementação de origens inline são:

  • source_packages (Obrigatório, list[str]): uma lista de caminhos de ficheiros ou diretórios locais a incluir na implementação. O tamanho total dos ficheiros e diretórios em source_packages não deve exceder 8 MB.
  • entrypoint_module (Obrigatório, str): o nome do módulo Python totalmente qualificado que contém o ponto de entrada do agente (por exemplo, agent_dir.agent).
  • entrypoint_object (Obrigatório, str): o nome do objeto chamável no entrypoint_module que representa a aplicação 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 campo api_mode (obrigatório) e um campo parameters. Consulte o artigo Liste as operações suportadas para mais informações sobre os métodos de um agente personalizado.

    Por 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 ficheiro de requisitos do pip nos caminhos especificados em source_packages. A predefinição é requirements.txt no diretório raiz da origem incluída no pacote.

A implementação demora alguns minutos, durante os quais os seguintes passos ocorrem em segundo plano:

  1. O SDK Vertex AI cria um arquivo tar.gz dos caminhos especificados em source_packages.
  2. Este arquivo é codificado e enviado diretamente para a API Vertex AI.
  3. O serviço Vertex AI Agent Engine recebe o arquivo, extrai-o, instala as dependências de requirements_file (se fornecidas) e inicia a aplicação do agente com os parâmetros entrypoint_module e entrypoint_object especificados.

A latência da implementação depende do tempo total necessário para instalar os pacotes necessários. Após a implementação, remote_agent corresponde a uma instância da aplicação do agente que está a ser executada no Vertex AI e pode ser consultada ou eliminada.

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

Segue-se um exemplo de implementação de um agente a partir de ficheiros 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) Obtenha o ID do recurso do agente

Cada agente implementado tem um identificador exclusivo. Pode executar o seguinte comando para obter o nome do recurso do agente implementado:

remote_agent.api_resource.name

A resposta deve ter o seguinte formato:

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

onde

  • PROJECT_ID é o Google Cloud ID do projeto onde o agente implementado é executado.

  • LOCATION é a região onde o agente implementado é executado.

  • RESOURCE_ID é o ID do agente implementado como um recurso reasoningEngine.

(Opcional) Indique as operações suportadas

Cada agente implementado tem uma lista de operações suportadas. Pode executar o seguinte comando para obter a lista de operações suportadas pelo agente implementado:

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 pode chamar. O conjunto de operações suportadas depende da framework que usou para desenvolver o seu agente:

(Opcional) Conceda autorizações ao agente implementado

Se for necessário conceder autorizações adicionais ao agente implementado, siga as instruções em Configure a identidade e as autorizações do seu agente.

O que se segue?