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

Esta página demonstra como fazer chamadas diretas à API de execução de código para executar códigos não confiáveis em um ambiente de sandbox isolado. As chamadas diretas à API são úteis quando você não quer que a estrutura do agente orquestre chamadas para você ou se quiser integrar a execução de código a outras estruturas de agente.

Neste guia de início rápido, você realiza 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 receber sandboxes
Executar código em um sandbox
Executar mais código usando o mesmo sandbox. O sandbox mantém automaticamente o estado.
Limpar

Para mais informações sobre como usar a execução de código com o Kit de desenvolvimento de agentes (ADK), consulte a 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 Google Cloud conta do. Se você começou a usar o Google Cloud, 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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Ter os papéis necessários

Para receber as permissões necessárias para usar o Vertex AI Agent Engine, peça ao administrador que conceda 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 personalizados papéis ou outros predefinidos papéis.

Configurar o ambiente

Esta seção pressupõe que você configurou um ambiente de desenvolvimento Python, ou está usando um ambiente de execução com um ambiente de desenvolvimento Python (como o Colab).

Instalar bibliotecas

Instale o SDK da Vertex AI:

  pip install google-cloud-aiplatform>=1.112.0

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 plataforma de agentes

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 plataforma de agentes leva alguns segundos.

import vertexai

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

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud .
LOCATION: aregião da instância da plataforma de agentes. Google Cloud Consulte Regiões com suporte.

Criar sandbox

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

operation = client.agent_engines.sandboxes.create(
    spec={"code_execution_environment": {}},
    name=agent_engine_name,
    config=types.CreateAgentEngineSandboxConfig(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 configurar as definições do sandbox, como linguagem de programação e configuração da máquina:

operation = client.agent_engines.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.CreateAgentEngineSandboxConfig(
       display_name=sandbox_display_name, ttl="3600s"),
)

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud .
LOCATION: aregião da instância da plataforma de agentes . Google Cloud Consulte Regiões com suporte.
INSTANCE_ID: o ID da instância da plataforma de agentes.

Somente LANGUAGE_PYTHON e LANGUAGE_JAVASCRIPT são compatíveis. Se machine_config não for especificado, a configuração padrão será de 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 receber sandboxes

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

sandboxes = client.agent_engines.sandboxes.list(name=agent_engine_name)

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Confira um 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 receber um sandbox atual:

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

pprint.pprint(sandbox)

Confira um 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.agent_engines.sandboxes.execute_code(
   name = sandbox_name,
   input_data = input_data
)

Confira um 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.agent_engines.sandboxes.execute_code(
    name = sandbox_name,
    input_data = input_data
)

pprint.pprint(response)

Confira um 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. Confira 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 um 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 plataforma de agentes.

client.agent_engines.sandboxes.delete(name=sandbox_name)
agent_engine.delete()

A seguir

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

Guia de início rápido da execução de código Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Criar o projeto

Ter os papéis necessários

Configurar o ambiente

Instalar bibliotecas

Autenticar

Shell local

Colab

Criar uma instância da plataforma de agentes

Criar sandbox

(Opcional) Listar e receber sandboxes

Executar código em um sandbox

Executar mais código em um sandbox

Limpar

A seguir

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