Guia de início rápido da execução de código

Nesta página, mostramos como fazer chamadas de API diretas para a Execução de Código para executar código não confiável em um ambiente de sandbox isolado. As chamadas de API diretas são úteis quando você não quer que o framework do agente organize as chamadas para você ou se quiser integrar a execução de código a outros frameworks de agente.

Neste guia de início rápido, você vai realizar as seguintes tarefas:

• Criar uma instância da Plataforma de Agentes para acessar a execução de código
• Criar um sandbox de execução de código
• (Opcional) Listar e acessar sandboxes
• Executar código em um sandbox
• Execute mais código usando o mesmo sandbox. Observe que o sandbox mantém o estado automaticamente.
• Limpar

Para mais informações sobre como usar a execução de código com o Kit de Desenvolvimento de Agentes (ADK), consulte Ferramenta de execução de código.

Antes de começar

Configurr o projeto e o ambiente.

Criar o projeto

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Observação : para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você não tiver essa permissão, peça ao administrador para conceder a você o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin).

Ter os papéis necessários

Para receber as permissões necessárias para usar o Vertex AI Agent Engine, peça ao administrador para conceder a você o papel do IAM de Usuário da plataforma de agentes (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Configurar o ambiente

Nesta seção, pressupomos que você configurou um ambiente de desenvolvimento em Python ou está usando um ambiente de execução com um ambiente de desenvolvimento em Python (como o Colab).

Instalar bibliotecas

Instale o SDK da Agent Platform:

  pip install google-cloud-agentplatform>=2.0.1

Autenticar

Para autenticar:

Shell local

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Criar uma instância da Agent Platform

Para usar a execução de código, primeiro crie uma instância da Plataforma de Agentes. Não é necessário implantar um agente para usar a execução de código. Sem a implantação, a criação de uma instância da Agent Platform leva alguns segundos.

import agentplatform
from agentplatform import types

client = agentplatform.Client(project=PROJECT_ID, location=LOCATION)

remote_agent = client.runtimes.create()
remote_agent_name = remote_agent.api_resource.name

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .

• LOCATION: a região do Google Cloud da instância da plataforma de agentes. Consulte as regiões com disponibilidade.

Criar sandbox

Crie um sandbox para execução de código.

operation = client.sandboxes.create(
    spec={"code_execution_environment": {}},
    name=remote_agent_name,
    config=types.CreateRuntimeSandboxConfig(display_name=SANDBOX_DISPLAY_NAME)
)

sandbox_name = operation.response.name

Substitua:

• SANDBOX_DISPLAY_NAME: o nome legível do ambiente de sandbox de execução de código.

Também é possível definir as configurações do sandbox, como linguagem de programação e configuração da máquina:

operation = client.sandboxes.create(
   spec={
       "code_execution_environment": {
            "code_language": "LANGUAGE_JAVASCRIPT",
            "machine_config": "MACHINE_CONFIG_VCPU4_RAM4GIB"
        }
   },
   name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID',
   config=types.CreateRuntimeSandboxConfig(
       display_name=sandbox_display_name, ttl="3600s"),
)

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .

• LOCATION: a região do Google Cloud para sua instância da plataforma de agente. Consulte as regiões com disponibilidade.

• INSTANCE_ID: o ID da instância da plataforma de agentes.

Somente LANGUAGE_PYTHON e LANGUAGE_JAVASCRIPT são aceitos. Se machine_config não for especificado, a configuração padrão será 2 vCPUs e 1,5 GB de RAM. Se você especificar MACHINE_CONFIG_VCPU4_RAM4GIB, o sandbox terá 4 vCPUs e 4 GB de RAM.

(Opcional) Listar e acessar sandboxes

Liste todos os sandboxes associados à instância especificada do Agent Engine:

sandboxes = client.sandboxes.list(name=remote_agent_name)

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Confira o exemplo de saída:

SandboxEnvironment(
  create_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC)),
  display_name='test_sandbox',
  name=SANDBOX_NAME,
  spec=SandboxEnvironmentSpec(
    code_execution_environment=SandboxEnvironmentSpecCodeExecutionEnvironment()
  ),
  state=<State.STATE_RUNNING: 'STATE_RUNNING'>,
  update_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC))
)

Para acessar um sandbox:

sandbox = client.sandboxes.get(name=sandbox_name)

pprint.pprint(sandbox)

Confira o exemplo de saída:

SandboxEnvironment(
  create_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC)),
  display_name='test_sandbox',
  name=SANDBOX_NAME,
  spec=SandboxEnvironmentSpec(
    code_execution_environment=SandboxEnvironmentSpecCodeExecutionEnvironment()
  ),
  state=<State.STATE_RUNNING: 'STATE_RUNNING'>,
  update_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC))
)

Executar código em um sandbox

Para executar o código, chame execute_code:

my_code = """
with open("input.txt", "r") as input:
   with open("output.txt", "w") as output:
       for line in input:
           print(line)
           output.write(line)
"""
input_data = {
   "code": my_code,
   "files": [{
       "name": "input.txt",
       "content": b"Hello, world!"
   }]
}


response = client.sandboxes.execute_code(
   name = sandbox_name,
   input_data = input_data
)

Confira o exemplo de saída:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
      }',
      mime_type='application/json',
    ),
    chunk(
data=b"hello world!",
        mime_type="text/plain"
        attributes={
          "file_name":"output.txt"
        }
    )
  ]
)

Observe o seguinte:

• execute_code redefine o time to live (TTL) do sandbox.
• A saída está em bytes brutos.
• Cada solicitação ou resposta pode conter até 100 MB de arquivos.

Executar mais código em um sandbox

Para demonstrar que o sandbox mantém o estado, execute mais código no mesmo sandbox:

python_code = """
with open("output2.txt", "w") as output:
    for line in lines:
        output.write(line + "World\n")
"""
input_data = {"code": python_code}

response = client.sandboxes.execute_code(
    name = sandbox_name,
    input_data = input_data
)

pprint.pprint(response)

Confira o exemplo de saída:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
      }',
      mime_type='application/json',
    ),
    chunk(
      data=b"hello world!",
        mime_type="text/plain"
        attributes={
          "file_name":"output2.txt"
        }
    )

  ]
)

A resposta inclui um arquivo que precisa ser decodificado. Veja um exemplo de como decodificar a saída:

import base64
import json

if response.outputs[0].mime_type=="application/json":
    json_output = json.loads(response.outputs[0].data.decode("utf-8"))
    output_file_content = json_output.get("output_files")[0].get("content")
    print(output_file_content.b64decode(output_file_content))

Confira o exemplo de saída:

b'HelloWorld\n'

Limpar

Para limpar os recursos criados por este guia de início rápido, exclua o sandbox e a instância da Agent Platform.

client.sandboxes.delete(name=sandbox_name)
remote_agent.delete()

A seguir

• Solução de problemas de execução de código