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

Esta página demonstra como fazer chamadas diretas de API para a execução de código e executar código não confiável em um ambiente de sandbox isolado. As chamadas diretas de API são úteis quando você não quer que a estrutura do agente organize as 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ê vai realizar as seguintes tarefas:

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

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

Antes de começar

Configurr o projeto e o ambiente.

Criar o projeto

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

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

  3. Verify that billing is enabled for your Google Cloud project.

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

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

  6. Verify that billing is enabled for your Google Cloud project.

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

    8.

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 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 implantação, a criação de uma instância da Agent Platform 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: a Google Cloud região da sua instância da plataforma de agentes. Consulte Regiões compatíveis.

Criar sandbox

Crie uma 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 da 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: a Google Cloud região da sua instância da plataforma de agentes. Consulte Regiões compatíveis.

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

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 receber sandboxes

Liste todas as sandbox associadas à 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 acessar um sandbox:

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) da 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 a sandbox mantém o estado, execute mais código na mesma 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. 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 um exemplo de saída:

b'HelloWorld\n'

Limpar

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

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

A seguir