Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Implantar um agente

A implantação de um agente no Agent Runtime o disponibiliza remotamente para processar solicitações. Neste documento, explicamos como implantar um agente com base no seu fluxo de trabalho de desenvolvimento: de um objeto de execução, arquivos de origem locais, 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.

Esse método de implantação só pode ser usado com o Python.

Arquivos de origem

Adequado 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 requer um bucket do Cloud Storage.

Esse método de implantação só pode ser usado com o 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 de API implantado. O contêiner implantado precisa seguir o contrato de ambiente 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. Implante uma imagem de contêiner hospedada no Artifact Registry. Use esse método se você precisar de controle sobre o processo de criação da imagem do contêiner e menor latência de implantação. A imagem do contêiner precisa seguir o contrato de ambiente 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:

Concluir pré-requisitos
Opcional: configurar o agente para implantação
Criar uma instância da Agent Platform
Opcional: receber o ID do recurso do agente
Opcional: listar as operações compatíveis
Opcional: conceder as permissões do agente implantado

Pré-requisitos

Antes de implantar um agente, conclua as seguintes tarefas:

Opcional: configurar o agente para implantação

É possível fazer configurações opcionais para o agente. Os exemplos nesta seção usam Python.

Definir os requisitos do pacote

Observação:para implantações de arquivos de origem, não é necessário usar o parâmetro requirements. Em vez disso, inclua um arquivo requirements.txt diretamente no pacote de código-fonte. O caminho para esse arquivo pode ser especificado no parâmetro requirements_file ao criar a instância da plataforma de agentes.

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 do arquivo de requisitos. Siga estas práticas recomendadas:

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.
Minimize o número de dependências no seu agente. Isso reduz o número de alterações 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 do framework, especifique a versão do SDK importada (como 1.112.0) ao desenvolver o agente.

ADK

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

A2A

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

LangChain

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

LangGraph

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

AG2

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

LlamaIndex

As instruções a seguir são para o pipeline de consulta do LlamaIndex:

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

Também é possível fazer o seguinte com o pacote requirements:

Defina o limite superior ou fixe a versão de um determinado pacote (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 do arquivo de requisitos. Exemplo:
```
  google-cloud-aiplatform[agent_engines,adk]
  cloudpickle==3.0
  
```

Definir pacotes adicionais

Observação:o parâmetro extra_packages só é usado ao implantar de um objeto de agente.

É possível incluir arquivos ou diretórios locais que contenham arquivos de origem Python locais necessá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 extra_packages como None:

extra_packages = None

Você também pode fazer o seguinte com o extra_packages:

Inclua 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 variáveis de ambiente

Se houver variáveis de ambiente das quais o 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

Se você estiver usando secrets como variáveis de ambiente com um agente configurado para usar a identidade do agente, conceda a permissão secretmanager.versions.access (incluída no papel roles/secretmanager.secretAccessor) ao agente de serviço da plataforma de agente, que tem o seguinte formato:

service-PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com

A identidade do agente configurada é usada no ambiente de execução, mas o agente de serviço da plataforma de agentes é usado para buscar secrets durante a implantação. A permissão adicionada permite que o agente de serviço recupere os valores de secret do Secret Manager durante o processo de implantação.

Aviso:não defina as seguintes variáveis de ambiente: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION e GOOGLE_APPLICATION_CREDENTIALS. Além disso, evite o prefixo GOOGLE_CLOUD_AGENT_ENGINE para evitar conflitos de nomenclatura com variáveis de ambiente do Agent Runtime.

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

Dicionário

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Agent Platform
# 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"
#

Para referenciar um secret no Secret Manager e disponibilizá-lo como uma variável de ambiente (por exemplo, CLOUD_SQL_CREDENTIALS_SECRET), siga as instruções para criar um secret para CLOUD_SQL_CREDENTIALS_SECRET no seu projeto antes de especificar as variáveis de ambiente como:

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

em que

SECRET_VERSION_ID é o ID da versão do secret.
SECRET_ID é o ID do secret.

No código do agente, é possível fazer referência ao secret da seguinte maneira:

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)

Lista

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 agente para conceder ao agente a permissão de acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor).

Definir controles de recursos personalizados

É possível especificar controles de recursos de ambiente de execução para o agente, como o número mínimo e máximo de instâncias de aplicativo, limites de recursos para cada contêiner e simultaneidade para cada contêiner. Para mais informações sobre os parâmetros de implantação, consulte a referência REST ReasoningEngineSpec.

min_instances: o número mínimo de instâncias do aplicativo que precisam ser mantidas em execução o tempo todo, com um intervalo de [0, 75]. O valor padrão é 1.

Observação:enquanto esse recurso estiver em pré-lançamento, mesmo que você configure um número maior de instâncias mínimas, não haverá cobrança pelo tempo em que um agente estiver ocioso. Esse comportamento de faturamento está sujeito a mudanças no futuro.
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á de [1, 100] por recurso da plataforma de agentes.
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 compatíveis com cpu são 1, 2, 4, 6 e 8. Para mais informações, consulte Configurar a alocação de CPU.
- Os únicos valores compatíveis com memory são 1Gi, 2Gi, ... 32Gi.
- Para saber qual é 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.runtimes.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

Para conferir as práticas recomendadas sobre como otimizar recursos de ambiente de execução, consulte Otimizar e escalonar o Agent Runtime.

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 de 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 raiz.

Para usar scripts de instalação, crie um diretório chamado installation_scripts e coloque os scripts de shell dentro dele:

.
├── ...
└── installation_scripts/
    └── install.sh

Em seguida, especifique o diretório installation_scripts em extra_packages e os caminhos do script em build_options:

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

Use um dos seguintes scripts de instalação comuns:

install_npx.sh

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

install_uvx.sh

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

install_gcloud_cli.sh

#!/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 o framework do agente

É possível especificar o framework que seu agente usa:

agent_framework = "google-adk"

Confira a seguir os valores compatíveis:

Se agent_framework não for especificado, o valor será detectado automaticamente se você estiver implantando de um objeto de agente. Se você estiver implantando de arquivos de origem, agent_framework será definido como "custom" por padrão.

Definir uma pasta do Cloud Storage

Observação:o parâmetro gcs_dir_name só é usado ao implantar de um objeto de agente.

Os artefatos de preparo serã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 teste. É possível definir gcs_dir_name como None se você não se importar em substituir os arquivos na pasta padrão:

gcs_dir_name = None

Para evitar a substituição dos arquivos (como em ambientes diferentes, 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())

Defina o nome de exibição

É possível definir o nome de exibição do recurso ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

Definir a descrição

É possível definir a descrição do recurso ReasoningEngine:

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

Definir os rótulos

É possível definir os rótulos do recurso ReasoningEngine como um dicionário de pares de strings de chave-valor. Confira o seguinte exemplo:

labels = {"author": "username", "version": "latest"}

Configurar uma identidade de agente padrão

É possível provisionar agentes implantados na Agent Platform com uma identidade exclusiva ao criar o agente. A identidade está vinculada ao ID do recurso do agente da Agent Platform e é independente do framework usado para desenvolver o agente:

identity_type=AGENT_IDENTITY

Para mais informações, consulte Criar um agente com identidade de agente.

Configurar uma conta de serviço personalizada

É possível configurar uma conta de serviço personalizada como a identidade do agente implantado, em vez da identidade do agente ou da identidade padrão.

Para fazer isso, especifique o e-mail da sua conta de serviço personalizada como service_account ao criar ou atualizar a instância da Agent Platform, por exemplo:

# Create a new instance
client.runtimes.create(
    agent=local_agent,
    config={
        "service_account": "my-custom-service-account@my-project.s3ns.iam.gserviceaccount.com",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.runtimes.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "my-new-custom-service-account@my-project.s3ns.iam.gserviceaccount.com",
        # ...
    },
)

Observação:especifique apenas o e-mail da conta de serviço, não o URI completo do recurso, como projects/{project_id}/serviceAccounts/{service_account_email}.

Configurar a interface do Private Service Connect

Se você tiver configurado a interface do Private Service Connect e a zona de DNS particular, especifique o anexo de rede e crie um peering de DNS particular ao implantar o agente:

remote_agent = client.runtimes.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 o caminho completo do anexo de rede. Se o anexo de rede for criado em um projeto (como o projeto host da VPC compartilhada) diferente daquele em que você usa a plataforma de agente, será necessário transmitir o caminho completo do anexo de rede.
DOMAIN_SUFFIX é o nome DNS da zona de DNS particular do Cloud DNS.
TARGET_PROJECT é o projeto que hospeda a rede VPC. Ele pode ser diferente do projeto de anexo de rede.
TARGET_NETWORK é o nome da rede VPC no `TARGET_PROJECT` em que o peering de DNS é estabelecido.

É possível configurar vários agentes para usar um único anexo de rede compartilhado ou anexos de rede dedicados exclusivos. Para usar um anexo de rede compartilhado, forneça o mesmo anexo de rede no psc_interface_config para cada agente que você criar.

Configurar chaves de criptografia gerenciadas pelo cliente

É possível usar uma chave personalizada para criptografar os dados em repouso do agente. Consulte as chaves de criptografia gerenciadas pelo cliente (CMEK) do Agent Engine para mais detalhes.

Para configurar a chave personalizada (CMEK) do agente, forneça o nome do recurso da chave ao parâmetro encryption_spec ao criar a instância da plataforma de agente.

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Configurar o link do repositório Git do Developer Connect

Para implantar de um repositório Git usando o Developer Connect, siga a documentação do Developer Connect para criar uma conexão e um link para o repositório específico. O nome do recurso do link é usado como git_repository_link durante a implantação e segue o formato: projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID.

Criar uma instância da Agent Platform

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

Developer Connect

Para implantar do Developer Connect na Agent Platform, use client.runtimes.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.

Esse método de implantação só pode ser usado com o Python.

remote_agent = client.runtimes.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 do link do repositório Git do Developer Connect.
- revision (str): a revisão a ser buscada (ramificação, tag ou SHA de commit).
- 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 dentro do 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 de origem. O padrão é requirements.txt.

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

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

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 plataforma de agentes e pode ser consultada ou excluída.

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

remote_agent.api_resource com informações sobre o agente implantado. Também é possível chamar remote_agent.operation_schemas() para retornar a lista de operações compatíveis com o remote_agent. Consulte Operações compatíveis para mais detalhes.
remote_agent.api_client que permite interações de serviço síncronas
remote_agent.async_api_client que permite interações de serviço assíncronas

Arquivos de origem

Para implantar de arquivos de origem na Agent Platform, use client.runtimes.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.

Esse método de implantação só pode ser usado com o 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.runtimes.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 para incluir 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 dentro do 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 um campo opcional parameters. 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:

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

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

remote_agent.api_resource com informações sobre o agente implantado. Também é possível chamar remote_agent.operation_schemas() para retornar a lista de operações compatíveis com o remote_agent. Consulte Operações compatíveis para mais detalhes.
remote_agent.api_client que permite interações de serviço síncronas
remote_agent.async_api_client que permite interações de serviço assíncronas

Dockerfile

A implantação do Dockerfile na plataforma de agentes 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 base no Dockerfile precisa seguir o contrato de ambiente de execução.

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

Veja a seguir um exemplo de implantação de um agente usando um Dockerfile:

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

remote_agent = client.runtimes.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",
    }
)

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

remote_agent.api_resource com informações sobre o agente implantado. Também é possível chamar remote_agent.operation_schemas() para retornar a lista de operações compatíveis com o remote_agent. Consulte Operações compatíveis para mais detalhes.
remote_agent.api_client que permite interações de serviço síncronas
remote_agent.async_api_client que permite interações de serviço assíncronas

Imagem do contêiner

Para implantar usando uma imagem do contêiner, siga as instruções de configuração em Traga seu próprio contêiner e instale uma versão de google-cloud-aiplatform que atenda a >=1.144. A imagem do contêiner precisa seguir o contrato de ambiente de execução.

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

Veja a seguir um exemplo de implantação de um agente usando uma imagem de contêiner:

remote_agent = client.runtimes.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).

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

remote_agent.api_resource com informações sobre o agente implantado. Também é possível chamar remote_agent.operation_schemas() para retornar a lista de operações compatíveis com o remote_agent. Consulte Operações compatíveis para mais detalhes.
remote_agent.api_client que permite interações de serviço síncronas
remote_agent.async_api_client que permite interações de serviço assíncronas

SDK da plataforma de agentes

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

remote_agent = client.runtimes.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:

Um pacote com os 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.
O pacote é enviado para o Cloud Storage (na pasta correspondente) para preparar os artefatos.
Os URIs do Cloud Storage para os respectivos artefatos são especificados no PackageSpec.
O serviço Agent Runtime recebe a solicitação, cria contêineres e inicia servidores HTTP no back-end.

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

remote_agent.api_resource com informações sobre o agente implantado. Também é possível chamar remote_agent.operation_schemas() para retornar a lista de operações compatíveis com o remote_agent. Consulte Operações compatíveis para mais detalhes.
remote_agent.api_client que permite interações de serviço síncronas
remote_agent.async_api_client que permite interações de serviço assíncronas

Opcional: receber o ID do recurso do agente

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

remote_agent.api_resource.name

A resposta será parecida com esta string:

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

em que

PROJECT_ID é o Cloud de Confiance by S3NS 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.

Opcional: listar as operações compatíveis

Cada agente implantado tem uma lista de operações compatíveis. Use o AgentRuntime.operation_schemas para ver 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: implantar agentes com infraestrutura empresarial

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

A seguir

Guia

Gerenciar agentes implantados

Saiba como gerenciar agentes que foram implantados no ambiente de execução gerenciado da Agent Platform.

Guia

Usar um agente

Usar um agente com o ambiente de execução da plataforma de agentes.