Implantar um agente

A implantação de um agente no Agent Runtime o deixa disponível remotamente para processar solicitações. Este documento explica as maneiras de implantar um agente com base no seu fluxo de trabalho de desenvolvimento: de um objeto de execução, arquivos de origem local, um Dockerfile, uma imagem de contêiner hospedada no Artifact Registry ou diretamente por um repositório Git conectado.

Para implantar um agente no Agent Runtime, escolha um dos seguintes métodos:

Developer Connect

Recomendado para projetos gerenciados em um repositório Git vinculados pelo Developer Connect. Esse método simplifica a implantação de agentes diretamente do código-fonte e oferece suporte nativo ao controle de versões, à colaboração em equipe e aos pipelines de CI/CD. Antes de usar esse método, configure o link do repositório Git seguindo as instruções em Configurar o link do repositório Git do Developer Connect.

Você só pode usar esse método de implantação com Python.

Arquivos de origem

Ideal para fluxos de trabalho automatizados, como pipelines de CI/CD e ferramentas de infraestrutura como código, como o Terraform, permitindo implantações totalmente declarativas e automatizadas. Ele implanta seu agente diretamente do código-fonte local e não exige um bucket do Cloud Storage.

Você só pode usar esse método de implantação com Python.

Dockerfile

Semelhante à implantação de arquivos de origem. Você implanta o agente diretamente do código-fonte local sem precisar de um bucket do Cloud Storage. Esse método é adequado se você precisar definir e controlar o servidor da API implantado. O contêiner implantado precisa obedecer ao contrato de tempo de execução.

É possível usar esse método de implantação com qualquer linguagem. Os exemplos nesta página usam Python.

Imagem do contêiner

Semelhante à implantação do Dockerfile. Você implanta uma imagem de contêiner hospedada no Artifact Registry. Use esse método se precisar controlar o processo de build da imagem do contêiner e reduzir a latência de implantação. A imagem do contêiner precisa seguir o contrato de tempo de execução.

É possível usar esse método de implantação com qualquer linguagem. Os exemplos nesta página usam Python.

SDK da plataforma de agentes

Ideal para desenvolvimento interativo em ambientes como o Colab, permitindo a implantação de objetos local_agent na memória. Esse método funciona melhor para agentes com estruturas que não contêm componentes complexos e não serializáveis.

Para começar, siga estas etapas:

  1. Concluir pré-requisitos
  2. Opcional: configure seu agente para implantação
  3. Criar uma instância da Agent Platform
  4. Opcional: receber o ID do recurso do agente
  5. Opcional: listar as operações compatíveis
  6. Opcional: conceda permissões ao agente implantado

Pré-requisitos

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

  1. Configurar o ambiente
  2. Criar um agente

Opcional: configurar o agente para implantação

Você pode fazer configurações opcionais para seu agente. Os exemplos nesta seção usam Python.

Criar uma instância da Agent Platform

Esta seção descreve como criar uma instância da Agent Platform para implantar um agente. Você pode escolher entre os seguintes métodos:

Developer Connect

Para fazer a implantação do Developer Connect na Agent Platform, use client.agent_engines.create fornecendo developer_connect_source, entrypoint_module e entrypoint_object no dicionário de configuração, além de outras configurações opcionais. Esse método permite implantar código diretamente de um repositório Git conectado.

Você só pode usar esse método de implantação com Python. 

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Os parâmetros para a implantação do Developer Connect são:

  • developer_connect_source (dict): a configuração para buscar o código-fonte. Consulte configurar o link do repositório Git do Developer Connect para mais detalhes.
    • git_repository_link (str): o nome do recurso de link do repositório Git do Developer Connect.
    • revision (str): a revisão a ser buscada (ramificação, tag ou commit SHA).
    • dir (str): o diretório raiz do código do agente no repositório.
  • entrypoint_module (str): o nome do módulo Python que contém o ponto de entrada do agente, relativo ao diretório especificado em developer_connect_source.dir.
  • entrypoint_object (str): o nome do objeto chamável no entrypoint_module que representa o aplicativo do agente (por exemplo, root_agent).
  • requirements_file (str): opcional. O caminho para um arquivo de requisitos do pip em relação à raiz da origem. O padrão é requirements.txt.

A implantação leva alguns minutos, durante os quais as seguintes etapas acontecem em segundo plano:

  1. O serviço Agent Runtime busca o código-fonte da revisão especificada do repositório Git.
  2. O serviço instala dependências de requirements_file (se fornecido).
  3. O serviço inicia o aplicativo do agente usando o entrypoint_module e o entrypoint_object especificados.

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 Agent Platform e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém o seguinte:

Arquivos de origem

Para fazer a implantação de arquivos de origem na Agent Platform, use client.agent_engines.create fornecendo source_packages, entrypoint_module, entrypoint_object e class_methods no dicionário de configuração, além de outras configurações opcionais. Com esse método, não é necessário transmitir um objeto de agente ou um bucket do Cloud Storage.

Você só pode usar esse método de implantação com Python. 

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

Os parâmetros para implantação de origem inline são:

  • source_packages (list[str]): uma lista de caminhos de arquivos ou diretórios locais a serem incluídos na implantação. O tamanho total dos arquivos e diretórios em source_packages não pode exceder 8 MB.
  • entrypoint_module (str): o nome totalmente qualificado do módulo Python que contém o ponto de entrada do agente (por exemplo, agent_dir.agent).
  • entrypoint_object (str): o nome do objeto chamável no entrypoint_module que representa o aplicativo do agente (por exemplo, root_agent).
  • class_methods (list[dict]): uma lista de dicionários que definem os métodos expostos do agente. Cada dicionário inclui um campo name, api_mode e parameters (opcional). Consulte Listar operações compatíveis para mais informações sobre os métodos de um agente personalizado.

    Exemplo:

    class_methods = [
    {
        "name": "method_name",
        "api_mode": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "Description of param1"},
                "param2": {"type": "integer"}
            },
            "required": ["param1"]
        }
    }
]
  • requirements_file (str): opcional. O caminho para um arquivo de requisitos do pip nos caminhos especificados em source_packages. O padrão é requirements.txt no diretório raiz da origem empacotada.

A implantação leva alguns minutos, durante os quais as seguintes etapas acontecem em segundo plano:

  1. O SDK da Agent Platform cria um arquivo tar.gz dos caminhos especificados em source_packages.
  2. Esse arquivo é codificado e enviado diretamente para a API Agent Platform.
  3. O serviço Agent Runtime recebe o arquivo, extrai, instala dependências de requirements_file (se fornecido) e inicia o aplicativo do agente usando entrypoint_module e entrypoint_object especificados.

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 Agent Platform e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém o seguinte:

Dockerfile

A implantação do Dockerfile na Agent Platform segue uma abordagem semelhante à implantação de arquivos de origem, exceto que você usa image_spec na configuração em vez de entrypoint_module, entrypoint_object e requirements_file. O contêiner criado com o Dockerfile precisa obedecer ao contrato de tempo de execução.

É possível usar esse método de implantação com qualquer linguagem. O exemplo nesta seção usa Python.

Confira um exemplo de como implantar um agente usando um Dockerfile:

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

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 Agent Platform e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém o seguinte:

Imagem do contêiner

Para fazer a implantação de uma imagem de contêiner, primeiro siga as instruções de configuração para Traga seu próprio contêiner, instalando uma versão do google-cloud-aiplatform que atenda a >=1.144. A imagem do contêiner precisa seguir o contrato de tempo de execução.

É possível usar esse método de implantação com qualquer linguagem. O exemplo nesta seção usa Python.

Confira um exemplo de implantação de um agente usando uma imagem de contêiner:

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

Em que CONTAINER_IMAGE_URI corresponde ao URI da imagem do contêiner no Artifact Registry, como us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag.

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 Agent Platform e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém o seguinte:

SDK da plataforma de agentes

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

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # 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 ao 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 Agent Runtime 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 Agent Platform e pode ser consultada ou excluída.

O objeto remote_agent corresponde a uma classe AgentEngine que contém o seguinte:

Opcional: extrair o ID do recurso do agente

Cada agente implantado tem um identificador exclusivo. Execute o comando a seguir para receber o nome do recurso do agente implantado:

remote_agent.api_resource.name

A resposta será semelhante à seguinte string:

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

em que

Opcional: listar as operações compatíveis

Cada agente implantado tem uma lista de operações compatíveis. Use o AgentEngine.operation_schemas para receber a lista de operações compatíveis com o agente implantado:

remote_agent.operation_schemas()

O esquema de cada operação é um dicionário que documenta as informações de um método para o agente que você pode chamar. O conjunto de operações compatíveis depende do framework usado para desenvolver o agente:

Opcional: 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.

Opcional: implante agentes com infraestrutura empresarial

Para implantar seu agente com um ambiente completo que inclua camadas de segurança e governança, copie e personalize os seguintes modelos do App Design Center:

A seguir

Guia

Aprenda a gerenciar agentes implantados no ambiente de execução gerenciado da Agent Platform.

Guia

Usar um agente com o ambiente de execução da Agent Platform.