Esta página foi traduzida pela API Cloud Translation.

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:

Criar uma instância do 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 Agent Development Kit (ADK), consulte Ferramenta de execução de código com o Agent Engine.

Antes de começar

Configurr o projeto e o ambiente.

Criar o projeto

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

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

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 Agent Engine

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

Criar uma 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 instância do Agent Engine. Consulte Regiões com suporte para o Vertex AI Agent Engine.
AGENT_ENGINE_ID: o ID da sua instância do Agent Engine.

Durante a prévia, somente LANGUAGE_PYTHON e LANGUAGE_JAVASCRIPT são compatíveis. 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("output.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":"",
        "output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
      }',
      mime_type='application/json',
    ),
  ]
)

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

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

Shell local

Colab

Criar uma instância do Agent Engine

Criar uma 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