Implantar um agente

Para implantar um agente no Vertex AI Agent Engine, siga estas etapas:

  1. Configure seu agente para implantação.
  2. Crie uma instância AgentEngine.
  3. Conceda as permissões do agente implantado.
  4. Receba o ID do recurso do agente.

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

Antes de começar

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

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

Configurar o agente para implantação

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

Definir os requisitos do pacote

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

  1. Fixe as versões do pacote para builds reproduzíveis. Pacotes comuns para acompanhar a inclusão: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai e pydantic.

  2. Minimize o número de dependências no seu agente. Isso reduz o número de mudanças interruptivas ao atualizar as dependências e o agente.

Se o agente não tiver dependências, defina requirements como None:

requirements = None

Se o agente usar um modelo específico da estrutura, especifique a versão do SDK importada (como 1.77.0) ao desenvolver o agente.

ADK 

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # 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

As instruções a seguir são para o pipeline de consulta do LlamaIndex:

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

Você também pode fazer o seguinte com o pacote requirements:

  • Defina um limite superior ou fixe a versão de um pacote específico (como google-cloud-aiplatform):

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

  • Adicione outros pacotes e restrições:

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

  • Aponte para a versão de um pacote em uma ramificação ou solicitação de envio do GitHub:

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

  • Mantenha a lista de requisitos em um arquivo (como path/to/requirements.txt):

    requirements = "path/to/requirements.txt"

    em que path/to/requirements.txt é um arquivo de texto que segue o formato de arquivo de requisitos. Exemplo:

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

Definir pacotes adicionais

Você pode incluir arquivos ou diretórios locais que contenham arquivos de origem Python locais obrigatórios. Em comparação com os requisitos de pacote, isso permite usar utilitários particulares desenvolvidos que não estão disponíveis no PyPI ou no GitHub.

Se o agente não exigir outros pacotes, defina extra_packages como None:

extra_packages = None

Você também pode fazer o seguinte com extra_packages:

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

    extra_packages = ["agents/agent.py"]

  • Inclua o conjunto de arquivos em um diretório inteiro (por exemplo, agents/):

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

  • Especifique binários de roda do 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

Definir as variáveis de ambiente

Se houver variáveis de ambiente de que seu agente depende, especifique-as no argumento env_vars=. Se o agente não depender de nenhuma variável de ambiente, defina-o como None:

env_vars = None

Para especificar as variáveis de ambiente, há algumas opções 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 referenciar um secret no Secret Manager e disponibilizá-lo como uma variável de ambiente (por exemplo, CLOUD_SQL_CREDENTIALS_SECRET), primeiro siga as instruções para criar um secret para CLOUD_SQL_CREDENTIALS_SECRET no seu projeto, antes de especificar as variáveis de ambiente como:

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

em que

  • SECRET_VERSION_ID é o ID da versão do secret.
  • SECRET_ID é o ID do secret.

No código do agente, você pode fazer referência ao secret assim:

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 

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"],
#   }

Definir controles de recursos personalizados

É possível especificar controles de recursos de execução para o agente, como o número mínimo e máximo de instâncias de aplicativos, limites de recursos para cada contêiner e simultaneidade para cada contêiner.

  • min_instances: o número mínimo de instâncias de aplicativo que precisam ficar em execução o tempo todo, com um intervalo de [0, 10]. O valor padrão é 1.

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

  • resource_limits: limites de recursos para cada contêiner. Apenas as chaves cpu e memory são aceitas. O valor padrão é {"cpu": "4", "memory": "4Gi"}.

    • Os únicos valores aceitos para cpu são "1", "2", "4", "6" e "8". Para mais informações, consulte Configurar a alocação de CPU.

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

    • Para saber a CPU necessária em diferentes valores de memória, consulte Configurar limites de memória.

  • container_concurrency: simultaneidade para cada contêiner e servidor de agente. O valor recomendado é 2 * cpu + 1. O valor padrão é 9.

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

Definir opções de build

É possível especificar opções de build para o agente, como scripts de instalação a serem executados ao criar a imagem do contêiner do agente. Isso é útil para instalar dependências do sistema (por exemplo, gcloud cli, npx) ou outras configurações personalizadas. Os scripts são executados com permissões de root.

Para usar scripts de instalação, crie um diretório chamado installation_scripts e coloque seus scripts de shell dentro dele:

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

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

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

Você 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

Definir uma pasta do Cloud Storage

Os artefatos de staging são substituídos se corresponderem a uma pasta em um bucket do Cloud Storage. Se necessário, especifique a pasta do Cloud Storage para os artefatos de preparo. Você pode definir gcs_dir_name como None se não se importar de substituir os arquivos na pasta padrão:

gcs_dir_name = None

Para evitar a substituição dos arquivos (como para diferentes ambientes, como desenvolvimento, preparo e produção), configure a pasta correspondente e especifique a pasta para preparar o artefato:

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

Se você quiser ou precisar evitar colisões, gere um uuid aleatório:

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

Configurar metadados de recursos

É possível definir metadados no recurso ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

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

Para um conjunto completo de parâmetros, consulte a referência da API.

Configurar uma conta de serviço personalizada

É possível configurar uma conta de serviço personalizada como a identidade do seu agente implantado, em vez da identidade padrão.

Para fazer isso, especifique o e-mail da sua conta de serviço personalizada como o service_account ao criar ou atualizar a instância do Agent Engine, por exemplo:

# Create a new instance
agent_engines.create(
  local_agent=<my-agent>,
  service_account="my-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
agent_engines.update(
  resource_name,
  service_account="my-new-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

Configurar a interface do Private Service Connect

O Vertex AI Agent Engine é compatível com a interface do Private Service Connect e o peering de DNS para tráfego de saída particular e seguro.

Por que usar uma interface do Private Service Connect?

O agente é implantado em uma rede segura gerenciada pelo Google sem acesso à sua rede de nuvem privada virtual (VPC). Uma interface do PSC cria uma ponte privada e segura para sua rede, sendo a solução recomendada para interagir com serviços hospedados de forma privada em ambientes de VPC, locais e multicloud.

Além de fornecer acesso particular, essa conexão também é necessária para ativar o acesso à Internet ao usar o VPC Service Controls. Consulte Como acessar a Internet pública.

Como funciona

Quando você configura uma interface do PSC, o Agent Engine provisiona uma interface em um projeto de locatário do Google em que o agente é executado. Essa interface se conecta diretamente a um anexo de rede no seu projeto. Todo o tráfego entre o agente e a VPC viaja com segurança na rede do Google, sem passar pela Internet pública.

Como acessar a Internet pública

A capacidade do agente de acessar a Internet pública depende da configuração de segurança do seu projeto, especificamente se você está usando o VPC Service Controls.

Comportamento padrão (sem o VPC Service Controls)
  • Quando você configura o agente apenas com uma interface do PSC, ele mantém o acesso padrão à Internet. Esse tráfego de saída sai diretamente do ambiente seguro gerenciado pelo Google em que o agente é executado.
Com o VPC Service Controls
  • Quando seu projeto faz parte de um perímetro do VPC Service Controls, o acesso padrão à Internet do agente é bloqueado pelo perímetro para evitar a exfiltração de dados. Para permitir que o agente acesse a Internet pública nesse cenário, é preciso configurar explicitamente um caminho de saída seguro que roteie o tráfego pela sua VPC. A maneira recomendada de fazer isso é configurar um servidor proxy dentro do perímetro da VPC e criar um gateway do Cloud NAT para permitir que a VM proxy acesse a Internet.

Antes de começar

Para ativar a conectividade privada do agente implantado usando a interface do Private Service Connect, configure uma rede VPC, uma sub-rede e um anexo de rede no projeto do usuário.

Requisitos de intervalo de IP da sub-rede

O Agent Engine recomenda uma sub-rede /28.

A sub-rede do anexo de rede é compatível com endereços RFC 1918 e não RFC 1918, exceto as sub-redes 100.64.0.0/10 e 240.0.0.0/4. O Agent Engine só pode se conectar a intervalos de endereços IP RFC 1918 que podem ser roteados da rede especificada. O Agent Engine não consegue acessar um endereço IP público usado de modo privado ou estes intervalos não RFC 1918:

  • 100.64.0.0/10
  • 192.0.0.0/24
  • 192.0.2.0/24
  • 198.18.0.0/15
  • 198.51.100.0/24
  • 203.0.113.0/24
  • 240.0.0.0/4

Consulte Configurar uma interface do Private Service Connect para mais detalhes sobre a configuração.

Como usar com a VPC compartilhada

É possível usar a interface do Private Service Connect com uma arquitetura de VPC compartilhada, que permite criar o Agent Engine em um projeto de serviço usando uma rede de um projeto host central.

Ao configurar o PSC-I em um ambiente de VPC compartilhada, crie a sub-rede no projeto host e, em seguida, crie o anexo de rede no projeto de serviço.

Para que o projeto de serviço use a rede do projeto host, conceda a permissão apropriada do IAM. O agente de serviço da Vertex AI do seu projeto de serviço precisa do papel de usuário da rede do Compute (roles/compute.networkUser) no projeto host.

Implantar agentes com a interface do Private Service Connect

Depois que o anexo de rede for configurado, você poderá especificá-lo ao criar a instância AgentEngine.

remote_agent = agent_engines.create(
    agent_engine=local_agent,
    psc_interface_config={
      "network_attachment": "NETWORK_ATTACHMENT",
    },
)

em que

  • NETWORK_ATTACHMENT é o nome ou o caminho completo do anexo de rede que você criou.

Como usar anexos de rede com vários agentes

Você tem a flexibilidade de decidir como seus agentes compartilham recursos de rede. É possível configurar vários agentes para usar um único anexo de rede compartilhada ou anexos de rede exclusivos e dedicados.

Para usar um anexo de rede compartilhada, forneça o mesmo anexo de rede no psc_interface_config para cada agente criado.

Peering de DNS

Enquanto a interface do Private Service Connect fornece o caminho de rede seguro, o peering de DNS oferece o mecanismo de descoberta de serviços. Com o PSC-I, você ainda precisaria saber o endereço IP específico do serviço na rede VPC. Embora seja possível se conectar a serviços usando os endereços IP internos deles, isso não é recomendado para sistemas de produção em que os IPs podem mudar. Com o peering de DNS, o agente implantado pode se conectar a serviços na rede VPC usando nomes DNS estáveis e legíveis por humanos em vez de endereços IP. Com o peering de DNS, os agentes implantados podem resolver nomes de DNS usando os registros de uma zona privada do Cloud DNS na sua VPC. Consulte Configurar um peering de DNS particular.

Depois que o peering de DNS particular é configurado, é possível especificá-lo ao criar a instância AgentEngine.

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

em que

  • NETWORK_ATTACHMENT é o nome ou o caminho completo do anexo de rede que você criou.
  • DOMAIN_SUFFIX é o nome DNS da zona privada do Cloud DNS que você criou ao configurar o peering de DNS particular.
  • TARGET_PROJECT é o projeto que hospeda a rede VPC.
  • TARGET_NETWORK é o nome da rede VPC.

Configurar chaves de criptografia gerenciadas pelo cliente

Você pode usar uma chave personalizada para criptografar os dados do seu agente em repouso. Consulte Chaves de criptografia gerenciadas pelo cliente (CMEK) do Agent Engine para mais detalhes.

Para configurar a chave personalizada (CMEK) do seu agente, forneça o nome do recurso da chave ao parâmetro encryption_spec ao 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 = agent_engines.create(
    local_agent,
    # ... other parameters
    encryption_spec={"kms_key_name": kms_key_name},
)

Criar uma instância AgentEngine

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

remote_agent = agent_engines.create(
    local_agent,                     # Optional.
    requirements=requirements,       # Optional.
    extra_packages=extra_packages,   # Optional.
    gcs_dir_name=gcs_dir_name,       # Optional.
    display_name=display_name,       # Optional.
    description=description,         # 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 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 a 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. Ela é separada das instâncias locais do agente.

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.

Se você definiu secrets como variáveis de ambiente, é necessário conceder a seguinte permissão:

  • Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor)

Extrair o ID do recurso do agente

Cada agente implantado tem um identificador exclusivo. Execute o seguinte comando para receber o identificador resource_name do seu agente implantado:

remote_agent.resource_name

A resposta será semelhante à seguinte string:

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

em que

A seguir