Implemente um agente

Para implementar um agente no Vertex AI Agent Engine, 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.

Nota: a implementação do Vertex AI Agent Engine só suporta Python.

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:

Defina os requisitos do pacote

Forneça o conjunto de pacotes exigidos pelo agente para a implementação. O conjunto de pacotes pode ser uma lista de itens a serem instalados pelo pip ou o caminho para um ficheiro que segue o formato de ficheiro de requisitos. Use as seguintes práticas recomendadas:

1. Fixe as versões dos pacotes para compilações reproduzíveis. Os pacotes comuns para acompanhar incluem o seguinte: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai e pydantic.
2. Minimize o número de dependências no seu agente. Isto reduz o número de alterações destrutivas quando atualiza as dependências e o agente.

Se o agente não tiver dependências, pode definir requirements para None:

requirements = None

Se o agente usar um modelo específico da framework, deve especificar a versão do SDK que é importada (como 1.112.0) ao desenvolver o agente.

ADK

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # any other dependencies
]

A2A

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "a2a-sdk>=0.3.4"
    # any other dependencies
]

LangChain

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

LangGraph

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

AG2

requirements = [
    "google-cloud-aiplatform[agent_engines,ag2]",
    # any other dependencies
]

LlamaIndex

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

As instruções seguintes destinam-se ao pipeline de consultas do LlamaIndex:

requirements = [
    "google-cloud-aiplatform[agent_engines,llama_index]",
    # any other dependencies
]

Também pode fazer o seguinte com o pacote requirements:

• Limite superior ou fixe a versão de um determinado pacote (como google-cloud-aiplatform):

    requirements = [
        # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
    ]
    

• Adicione mais pacotes e restrições:

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
        "cloudpickle==3.0", # new
    ]
    

• Indicar a versão de um pacote num ramo ou num pedido de envio do GitHub:

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
    ]
    

• Mantenha a lista de requisitos num ficheiro (como path/to/requirements.txt):

    requirements = "path/to/requirements.txt"
    

  onde path/to/requirements.txt é um ficheiro de texto que segue o formato de ficheiro de requisitos. Por exemplo:

    google-cloud-aiplatform[agent_engines,adk]
    cloudpickle==3.0
    

Defina pacotes adicionais

Pode incluir ficheiros ou diretórios locais que contenham ficheiros de origem Python necessários localmente. Em comparação com os requisitos de pacotes, isto permite-lhe usar utilitários privados que desenvolveu e que, de outra forma, não estão disponíveis no PyPI nem no GitHub.

Se o agente não precisar de pacotes adicionais, pode definir extra_packages como None:

extra_packages = None

Também pode fazer o seguinte com o extra_packages:

• Incluir um único ficheiro (como agents/agent.py):

    extra_packages = ["agents/agent.py"]
    

• Inclua o conjunto de ficheiros num diretório completo (por exemplo, agents/):

    extra_packages = ["agents"] # directory that includes agents/agent.py
    

• Especifique binários de roda Python (por exemplo, path/to/python_package.whl):

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]",
        "cloudpickle==3.0",
        "python_package.whl",  # install from the whl file that was uploaded
    ]
    extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading
    

Defina variáveis de ambiente

Se existirem variáveis de ambiente das quais o seu agente depende, pode especificá-las no argumento env_vars=. Se o agente não depender de nenhuma variável de ambiente, pode defini-lo como None:

env_vars = None

Aviso: não deve definir as seguintes variáveis de ambiente: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION e GOOGLE_APPLICATION_CREDENTIALS. Além disso, deve evitar o prefixo GOOGLE_CLOUD_AGENT_ENGINE para evitar conflitos de nomenclatura com as variáveis de ambiente do Vertex AI Agent Engine.

Para especificar as variáveis de ambiente, existem algumas opções diferentes disponíveis:

Dicionário

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Vertex AI Agent Engine
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

Para fazer referência a um segredo no Secret Manager e disponibilizá-lo como uma variável de ambiente (por exemplo, CLOUD_SQL_CREDENTIALS_SECRET), siga primeiro as instruções para criar um segredo para CLOUD_SQL_CREDENTIALS_SECRET no seu projeto, antes de especificar as variáveis de ambiente da seguinte forma:

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_ID},
}

onde

• SECRET_VERSION_ID é o ID da versão do Secret.
• SECRET_ID é o ID do segredo.

Nota: só pode fazer referência a segredos (e respetivas versões) geridos no mesmo projeto que o agente implementado.

No seu código do agente, pode fazer referência ao segredo da seguinte forma:

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON
  # payloads.
  return json.loads(secret)

Lista

Nota: esta opção não suporta a integração do Secret Manager. Se precisar de especificar segredos geridos, tem de especificar as variáveis de ambiente como um dicionário.

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

Também tem de seguir as instruções em Configurar a identidade e as autorizações do seu agente para conceder ao seu agente a autorização Secret Accessor do Secret Manager (roles/secretmanager.secretAccessor).

Defina controlos de recursos personalizados

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Pode especificar controlos de recursos de tempo de execução para o agente, como o número mínimo e máximo de instâncias da aplicação, limites de recursos para cada contentor e simultaneidade para cada contentor.

• min_instances: o número mínimo de instâncias da aplicação a manter em execução em todos os momentos, com um intervalo de [0, 10]. O valor predefinido é 1.

  Nota: enquanto esta funcionalidade estiver em pré-visualização, mesmo que configure um número mais elevado de instâncias mínimas, não lhe será cobrado tempo quando um agente estiver inativo. Este comportamento de faturação está sujeito a alterações no futuro.

• max_instances: o número máximo de instâncias da aplicação que podem ser iniciadas para processar o aumento do tráfego, com um intervalo de [1, 1000]. O valor predefinido é 100. Se o VPC-SC ou o PSC-I estiver ativado, o intervalo aceitável é [1, 100].

• resource_limits: limites de recursos para cada contentor. Apenas são suportadas as chaves cpu e memory. O valor predefinido é {"cpu": "4", "memory": "4Gi"}.

  • Os únicos valores suportados para cpu são 1, 2, 4, 6 e 8. Para mais informações, consulte o artigo Configure a atribuição de CPU.

  • Os únicos valores suportados para memory são 1Gi, 2Gi, ... 32Gi.

  • Para ver a CPU necessária em diferentes valores de memória, consulte o artigo Configure limites de memória.

• container_concurrency: concorrência para cada contentor e servidor de agente. O valor recomendado é 2 * cpu + 1. O valor predefinido é 9.

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

Defina as opções de compilação

Pode especificar opções de compilação para o agente, como scripts de instalação a executar quando compila a imagem do contentor do agente. Isto é útil para instalar dependências do sistema (por exemplo, gcloud cli, npx) ou outras configurações personalizadas. Os scripts são executados com autorizações de raiz.

Para usar scripts de instalação, crie um diretório com o nome installation_scripts e coloque os seus scripts de shell no diretório installation_scripts:

.
├── ...
└── installation_scripts/
    └── install.sh

Em seguida, especifique o diretório installation_scripts em extra_packages e os caminhos dos scripts em build_options:

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

Pode usar um dos seguintes scripts de instalação comuns:

install_npx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

install_uvx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

install_gcloud_cli.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

Defina uma pasta do Cloud Storage

Os artefactos de preparação são substituídos se corresponderem a uma pasta existente num contentor do Cloud Storage. Se necessário, pode especificar a pasta do Cloud Storage para os artefactos de preparação. Pode definir gcs_dir_name como None se não se importar de substituir potencialmente os ficheiros na pasta predefinida:

gcs_dir_name = None

Para evitar substituir os ficheiros (por exemplo, para diferentes ambientes, como desenvolvimento, preparação e produção), pode configurar a pasta correspondente e especificar a pasta para preparar o artefacto em:

gcs_dir_name = "dev" # or "staging" or "prod"

Se quiser ou precisar de evitar colisões, pode gerar um uuid aleatório:

import uuid
gcs_dir_name = str(uuid.uuid4())

Defina o nome a apresentar

Pode definir o nome a apresentar para o recurso ReasoningEngine

display_name = "Currency Exchange Rate Agent (Staging)"

Defina a descrição

Pode definir a descrição do recurso ReasoningEngine da seguinte forma:

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

Defina as etiquetas

Pode definir as etiquetas do recurso ReasoningEngine como um dicionário de pares de strings de chave-valor. Segue-se um exemplo:

labels = {"author": "username", "version": "latest"}

Configure uma conta de serviço personalizada

Pode configurar uma conta de serviço personalizada como a identidade do seu agente implementado, em vez da identidade predefinida.

Para tal, especifique o email da sua conta de serviço personalizada como o service_account quando criar ou atualizar a instância do Agent Engine, por exemplo:

# Create a new instance
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

Nota: especifique apenas o email da conta de serviço e não o URI do recurso completo, como projects/{project_id}/serviceAccounts/{service_account_email}.

Configure a interface do Private Service Connect

Se tiver a interface do Private Service Connect e o peering de DNS configurados, pode especificar a associação de rede e o peering de DNS privado durante a implementação do agente:

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "psc_interface_config": {
            "network_attachment": "NETWORK_ATTACHMENT",
            "dns_peering_configs": [
                {
                    "domain": "DOMAIN_SUFFIX",
                    "target_project": "TARGET_PROJECT",
                    "target_network": "TARGET_NETWORK",
                },
            ],
        },
    },
)

onde

• NETWORK_ATTACHMENT é o nome ou o caminho completo do anexo de rede. Se a associação de rede for criada num projeto (como o projeto anfitrião de VPC partilhada) diferente daquele onde usa o Agent Engine, tem de transmitir o caminho completo da associação de rede.
• DOMAIN_SUFFIX é o nome DNS da zona do Cloud DNS privado que criou quando configurou o peering de DNS privado.
• TARGET_PROJECT é o projeto que aloja a rede VPC. Pode ser diferente do projeto de associação à rede.
• TARGET_NETWORK é o nome da rede VPC.

Pode configurar vários agentes para usar um único anexo de rede partilhado ou anexos de rede únicos e dedicados. Para usar um anexo de rede partilhado, forneça o mesmo anexo de rede no elemento psc_interface_config para cada agente que criar.

Configure chaves de encriptação geridas pelo cliente

Pode usar uma chave personalizada para encriptar os dados em repouso do seu agente. Consulte o artigo Chaves de encriptação geridas pelo cliente (CMEK) do Agent Engine para ver mais detalhes.

Para configurar a chave personalizada (CMEK) do seu agente, tem de fornecer o nome do recurso da chave ao parâmetro encryption_spec quando criar a instância do Agent Engine.

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Crie uma instância do AgentEngine

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

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. Está separada das instâncias locais do agente.

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

• Um remote_agent.api_resource com informações sobre o agente implementado. Também pode chamar agent.operation_schemas() para devolver a lista de operações que o agente suporta. Consulte o artigo Liste as operações suportadas para ver detalhes.
• Um remote_agent.api_client que permite interações de serviço síncronas.
• Um remote_agent.async_api_client que permite interações de serviço assíncronas.

(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 aspeto:

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

• Agent Development Kit
• Agent2Agent
• LangChain
• LangGraph
• AG2
• LlamaIndex
• Personalizado

(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?

• Use o agente.
• Faça a gestão dos agentes implementados.
• Resolva problemas de implementação de um agente.
• Receba apoio técnico.