Implantar um agente

Para implantar um agente no Agente Engine:

  1. (Opcional) Definir os requisitos do pacote
  2. (Opcional) Definir os arquivos de origem
  3. (Opcional) Organizar o diretório do Cloud Storage
  4. (Opcional) Definir os metadados do recurso
  5. Criar uma instância AgentEngine

Antes de começar

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

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

Etapa 1: definir os requisitos do pacote

Forneça o conjunto de pacotes necessários para a implantação do agente. Ela 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.

Se o agente não tiver dependências, defina como "Nenhuma":

requirements = None

Se o agente usar um modelo específico do framework, especifique a versão do SDK que será importada (por exemplo, 1.77.0) ao desenvolver o agente.

LangChain 

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

LangGraph 

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

[Opcional] Restrições de versão

Se você quiser ou precisar definir um limite máximo ou fixar a versão de um determinado pacote (por exemplo, google-cloud-aiplatform):

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

É possível adicionar outros pacotes e restrições à lista:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]==1.75.0",
    "cloudpickle==3.0", # new
]

[Opcional] Branch de desenvolvimento

Você pode apontar para a versão de um pacote que está em uma ramificação ou solicitação de envio do GitHub, por exemplo:

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

[Opcional] Formato do arquivo de requisitos

Você pode manter a lista de requisitos em um arquivo (por exemplo, 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, por exemplo:

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

Etapa 2: pacotes extras

É possível incluir arquivos ou diretórios locais que contêm arquivos de origem Python locais necessários. Em comparação com os requisitos de pacote, isso permite que você use 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 pacotes extras, defina-o como None:

extra_packages = None

[Opcional] Arquivos e diretórios

Para incluir um único arquivo (por exemplo, agents/agent.py), adicione-o à lista:

extra_packages = ["agents/agent.py"]

Para incluir o conjunto de arquivos em um diretório inteiro (por exemplo, agents/), especifique o diretório:

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

[Opcional] Binários de roda

É possível incluir binários de roda Python (por exemplo, path/to/python_package.whl) e especificá-los nos requisitos do pacote:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]",
    "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

Etapa 3: diretório do Cloud Storage

Os artefatos de preparação serão substituídos se corresponderem a um subbucket existente (uma pasta em um bucket do Cloud Storage). Se necessário, você pode especificar o subbucket para os artefatos de preparação. Essa etapa é opcional e pode ser definida como None se você não se importar em substituir os arquivos no subbucket padrão:

gcs_dir_name = None

Para evitar a substituição dos arquivos (por exemplo, em diferentes ambientes, como desenvolvimento, preparação e produção), configure os subbuckets correspondentes e especifique o subbucket para preparar o artefato, como:

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

Se você quiser ou precisar evitar colisões, poderá gerar um UUID aleatório, por exemplo:

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

Etapa 4: metadados do recurso

É possível definir metadados no recurso ReasoningEngine que é criado na Vertex AI, por exemplo:

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 conferir um conjunto completo de parâmetros, acesse a referência da API.

Etapa 5: criar uma instância AgentEngine

Para implantar o aplicativo na Vertex AI, use agent_engines.create e transmita o objeto como um parâmetro:

remote_agent = agent_engines.create(
    local_agent,                    # Required.
    requirements=requirements,      # Optional.
    extra_packages=extra_packages,  # Optional.
    gcs_dir_name=gcs_dir_name,      # Optional.
    display_name=display_name,      # Optional.
    description=description,        # Optional.
)

A implantação leva alguns minutos para ser executada. Ao implantar o agente,

  1. Um pacote de artefatos é gerado localmente, incluindo:
    • *.pkl um arquivo pickle correspondente a local_agent.
    • requirements.txt: um arquivo de texto com os requisitos do pacote.
    • dependencies.tar.gz um arquivo tar contendo pacotes extras.
  2. O pacote é enviado para o Cloud Storage (no subbucket correspondente) para a preparação dos artefatos.
  3. Os URIs do Cloud Storage para os artefatos respectivos são especificados no PackageSpec.
  4. O serviço do mecanismo do agente recebe a solicitação, cria contêineres e ativa 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. Ele é separado das instâncias locais do agente.

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

remote_agent.resource_name

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 aplicativo. Isso reduz o número de alterações interruptivas ao atualizar as dependências e facilita a atualização do aplicativo ao longo do tempo para recursos mais recentes.

Implantar na produção com o pacote inicial do agente

O Agent Starter Pack é uma coleção de modelos de agentes de IA generativa prontos para produção criados para o Vertex AI Agent Engine. Ele acelera a implantação fornecendo:

  • Modelos de agentes pré-criados:ReAct, RAG, multiagente e muito mais.
  • Ambiente interativo: teste e interaja com seu agente.
  • Infraestrutura automatizada: usa o Terraform para simplificar o gerenciamento de recursos.
  • Pipelines de CI/CD: fluxos de trabalho de implantação automatizada que usam o Cloud Build.
  • Observabilidade: inclui suporte integrado para o Cloud Trace e o Cloud Logging.

Começar:guia de início rápido

A seguir