Nesta página, mostramos como fazer chamadas diretas de API para a execução de código do 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 ou se quiser integrar a execução de código a outras estruturas de agentes.
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
- Listar e receber sandboxes (opcional)
- 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
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
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theserviceusage.services.enablepermission. Learn how to grant roles. -
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
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theserviceusage.services.enablepermission. Learn how to grant roles. PROJECT_ID: o ID do projeto do Google Cloud .LOCATION: a Google Cloud região do Agent Engine.SANDBOX_DISPLAY_NAME: o nome legível do ambiente sandbox de execução de código.execute_coderedefine o time to live (TTL) da sandbox.- Os arquivos precisam ser inseridos na solicitação e codificados em base64.
- Cada solicitação ou resposta pode conter até 100 MB de arquivos.
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.0Autenticar 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:
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:
Também é possível configurar as opçõ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=agent_engine_name,
config=types.CreateAgentEngineSandboxConfig(display_name=sandbox_display_name),
)
sandbox_name = operation.response.name
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.
Listar e receber sandboxes (opcional)
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 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:
python_code = """
lines = []
with open("input.txt", "r") as input:
for line in input:
lines.append(line)
"""
input_data = {
"code": python_code,
"files": [{
"name": "input.txt",
"content": "aGVsbG8="
}]
}
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":[]}',
mime_type='application/json'),
]
)
Observe o seguinte:
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()