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:

• Requisitos do pacote
• Pacotes adicionais
• Variáveis de ambiente
• Opções de build
• Pasta do Cloud Storage
• Metadados de recursos

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.

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

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

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.

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

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, preparação 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.

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

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 as permissões do agente de serviço.

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

• PROJECT_ID é o Google Cloud ID do projeto em que o agente implantado é executado.

• LOCATION é a região em que o agente implantado é executado.

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

A seguir

• Use o agente.
• Gerenciar agentes implantados.
• Resolver problemas na implantação de um agente.
• Receba suporte.