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

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Esta página demonstra como fazer chamadas diretas à API Agent Engine Code Execution para executar código não fidedigno num ambiente de sandbox isolado. As chamadas API diretas são úteis quando não quer que a framework de agentes organize as chamadas por si ou se quiser integrar a execução de código com outras frameworks de agentes.

Neste guia de início rápido, vai realizar as seguintes tarefas:

• Crie uma instância do motor do agente para aceder à execução de código
• Crie um isolamento de processos de execução de código
• Liste e obtenha caixas de areia (opcional)
• Execute código num sandbox
• Executar mais código com a mesma sandbox. Repare que a sandbox mantém automaticamente o respetivo estado.
• Limpar

Antes de começar

Configure o projeto e o ambiente.

Configure o seu 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 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 (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

Nota: para ativar APIs, precisa da autorização serviceusage.services.enable. Se não tiver esta autorização, peça ao seu administrador para lhe conceder a função de administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin).

Obtenha as funções necessárias

Para receber as autorizações de que precisa para usar o Vertex AI Agent Engine, peça ao seu administrador para lhe conceder a função IAM Utilizador do Vertex AI (roles/aiplatform.user) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Configure o seu ambiente

Esta secção pressupõe que configurou um ambiente de programação Python ou que está a usar um ambiente de execução com um ambiente de programação Python (como o Colab).

Instale bibliotecas

Instale o SDK Vertex AI:

  pip install google-cloud-aiplatform>=1.112.0

Autentique-se no Vertex AI

Para autenticar:

shell local

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Crie uma instância do motor do agente

Para usar a execução de código, comece por criar uma instância do Agent Engine. Não precisa de implementar um agente para usar a execução de código. Sem a implementação, a criação de uma instância do Agent Engine deve demorar 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 o seguinte:

• PROJECT_ID: o ID do seu Google Cloud projeto.
• LOCATION: a Google Cloud região do seu Agent Engine.

Crie uma sandbox

Crie uma sandbox para a 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 o seguinte:

• SANDBOX_DISPLAY_NAME: o nome legível do ambiente de sandbox de execução de código.

Também pode configurar as definições da sandbox, como a linguagem de programação e a 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é-visualização, apenas são suportados os formatos LANGUAGE_PYTHON e LANGUAGE_JAVASCRIPT. Se machine_config não for especificado, a configuração predefinida é de 2 vCPU e 1,5 GB de RAM. Se especificar MACHINE_CONFIG_VCPU4_RAM4GIB, o sandbox tem 4 vCPU e 4 GB de RAM.

Liste e obtenha caixas de areia (opcional)

Liste todas as caixas de areia associadas à instância do motor do agente especificada:

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

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Segue-se o exemplo do resultado:

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 obter um sandbox existente:

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

pprint.pprint(sandbox)

Segue-se o exemplo do resultado:

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

Execute código num sandbox

Para executar 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)

Segue-se o exemplo do resultado:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{"msg_err":"","msg_out":"","output_files":[]}',
      mime_type='application/json'),
  ]
)

Tenha em conta o seguinte:

• execute_code repõe o tempo de vida (TTL) da área de testes.
• Os ficheiros têm de estar incorporados no pedido e codificados em base64.
• Cada pedido ou resposta pode conter até 100 MB de ficheiros.

Execute mais código numa sandbox

Para demonstrar que o isolamento de processos mantém o respetivo estado, execute mais código no mesmo isolamento de processos:

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)

Segue-se o exemplo do resultado:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
        "output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
      }',
      mime_type='application/json',
    ),
  ]
)

A resposta inclui um ficheiro que tem de ser descodificado. Segue-se um exemplo de como descodificar o resultado:

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

Segue-se o exemplo do resultado:

b'HelloWorld\n'

Limpar

Para limpar os recursos criados por este início rápido, elimine a sua sandbox e instância do Agent Engine.

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

O que se segue?

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