Implantar um agente

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.112.0) ao desenvolver o agente.

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

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

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

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

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

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.112.0",
    ]
    

• Adicione outros pacotes e restrições:

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

• 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 necessários localmente. Em comparação com os requisitos de pacote, isso permite usar utilitários particulares que você desenvolveu e 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 como None:

env_vars = None

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

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

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

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)

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

Você também precisa seguir as instruções em Configurar a identidade e as permissões do seu agente para conceder ao agente a permissão de Acessador de secret do Secret Manager (roles/secretmanager.secretAccessor).

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. Somente 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 alocação de CPU.

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

  • 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 = 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
    }
)

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:

#!/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

#!/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

#!/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 preparação. É possível definir gcs_dir_name como None se você 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
client.agent_engines.create(
    agent=local_agent,
    config={
        "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}"
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "my-new-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

Configurar a interface do Private Service Connect

Se você tiver a interface do Private Service Connect e o peering de DNS configurados, poderá especificar o anexo de rede e o peering de DNS particular ao implantar o 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",
                },
            ],
        },
    },
)

em que

• NETWORK_ATTACHMENT é o nome ou caminho completo do anexo de rede. Se o anexo de rede for criado em um projeto (como o projeto host da VPC compartilhada) diferente de onde você usa o Agent Engine, transmita o caminho completo do anexo de rede.
• 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.

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

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 = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)