Implantar um agente

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

1. Configure o agente para implantação. É possível fazer as seguintes configurações opcionais:
   • Requisitos do pacote
   • Pacotes adicionais
   • Diretório do Cloud Storage
   • Metadados do recurso
2. Crie uma instância de AgentEngine.
3. Conceda as permissões ao agente implantado.
4. Conseguir o ID do recurso do agente.

Também é possível usar os modelos do pacote inicial do agente 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.

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

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

requirements = None

Se o agente usar um modelo específico do framework, especifique a versão do SDK que será 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
]

Restrições de versão (opcional)

Para definir o limite máximo ou fixar a versão de um determinado pacote (como google-cloud-aiplatform), especifique o seguinte:

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

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

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

(Opcional) Definir uma ramificação de desenvolvimento

É possível apontar para a versão de um pacote que está em uma ramificação ou solicitação de pull do GitHub. Exemplo:

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

(Opcional) Definir um formato de arquivo de requisitos

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

(Opcional) Definir pacotes adicionais

É possível incluir arquivos ou diretórios locais que contêm arquivos de origem Python obrigatórios. 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 pacotes extras, defina-o como None:

extra_packages = None

(Opcional) Definir arquivos e diretórios

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

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) Definir binários de roda

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

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

(Opcional) Definir um diretório do Cloud Storage

Os artefatos de preparação sã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. Você pode definir gcs_dir_name como None se 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 em:

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

(Opcional) Configurar metadados de recursos

É possível definir metadados no recurso ReasoningEngine criado na Vertex AI:

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 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, 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 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 Vertex AI Agent Engine 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.

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

Conseguir o ID do recurso 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

A resposta será semelhante a esta 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.

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 gerenciar recursos de forma simplificada.
• 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

Práticas recomendadas para implantação

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

2. Minimize o número de dependências no agente. Isso reduz o número de alterações interruptivas ao atualizar as dependências e facilita a atualização do agente ao longo do tempo para recursos mais recentes.

A seguir

• Usar o agente.
• Gerencie os agentes implantados.
• Resolver problemas na implantação de um agente.
• Receba suporte.