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 do Vertex AI Agent Engine para 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:

• Crie uma instância do Vertex AI Agent Engine 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 com o Vertex AI Agent Engine.

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

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

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 Vertex AI 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

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 função de administrador do uso de serviço (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 Vertex AI (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 na Vertex AI

Para autenticar:

Shell local

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Criar uma instância do Vertex AI Agent Engine

Para usar a execução de código, primeiro crie uma instância do Vertex AI Agent Engine. 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 do Vertex AI Agent Engine 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 do Vertex AI Agent Engine. Consulte Regiões com suporte para o Vertex AI Agent Engine.

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/AGENT_ENGINE_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 do Vertex AI Agent Engine. Consulte Regiões com suporte para o Vertex AI Agent Engine.

• AGENT_ENGINE_ID: o ID da sua instância do Vertex AI Agent Engine.

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 todos os ambientes de simulação 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 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 liberar memória dos recursos criados por este guia de início rápido, exclua sua sandbox e a instância do Vertex AI Agent Engine.

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

A seguir

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