Skip to main content
AgentkitRemoteSandboxAgent sends a text task to an AgentKit Skill or CodeEnv sandbox and returns progress, tool events, and results. Use it directly as a root agent or as a coordinator’s sub-agent Unlike code sandbox tools, this entry delegates an entire task and lets the remote agent choose the steps. run_code and execute_skills are individual tools called by the current agent

Dependencies and prerequisites

  • Install VeADK and prepare an accessible AgentKit Tool ID, region, and account credentials
  • A Skill sandbox must expose a compatible A2A service; a CodeEnv image must support Codex Worker protocol v1 and tool_events
  • The caller must reach both the AgentKit control plane and the returned sandbox session endpoint
  • A local coordinator also needs model configuration; when calling the remote agent directly, the remote service supplies model execution
These examples create or reuse cloud sandbox sessions and may incur resource charges. Sandboxes can execute code, commands, and file operations and access reachable services. Use trusted images, restrict data, network, and permissions, and confirm that task content may be sent to the sandbox
For Volcengine, configure the following and replace CodeEnv with the actual tool type:
For BytePlus, set CLOUD_PROVIDER=byteplus and the appropriate region, and confirm that the account has a compatible Tool service. This entry currently reads credentials from VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY; changing platforms does not switch it to BYTEPLUS_*. Supply target-platform credentials through those variable names. Endpoint overrides are listed below Construction makes no network request; the first run establishes the connection

Usage

As a root agent

Save this script as remote_sandbox.py and run python remote_sandbox.py from the configured terminal:
remote_sandbox.py
A successful run prints the final remote result; the sum in this example should be 5050. The example explicitly supplies short-term memory so Runner can create a session for this root agent

As a sub-agent

A coordinator chooses whether to transfer the task. Give the sandbox a specific description so the coordinator can recognize suitable work
coordinator.py
Run python coordinator.py. The coordinator can delegate through transfer_to_agent, after which the sandbox returns the result directly. Transfer is a model decision; use the root-agent entry when a task must go to the sandbox

Sandbox types

When tool_type is omitted, AgentKit GetTool discovers it. Specify the type for private tools or compatible custom tools that report a different type. AGENTKIT_TOOL_TYPE is read explicitly by these examples, not automatically by the agent

Parameters

request_timeout + expiry_buffer + 2 * ready_timeout must be less than 86400 seconds, or initialization fails. The table lists task-integration parameters; standard ADK BaseAgent callback configuration is also available

Environment variables

Credentials are resolved from session state, environment variables, then the environment’s IAM Role. A bound IAM Role can supply temporary credentials. Do not expose cloud credentials in session state as ordinary user-visible business data

Session management

The same application, user, session, and agent can reuse a valid remote session, retaining sandbox files and runtime state. ttl defaults to 30 minutes and allows up to 24 hours. Files must not be assumed to survive expiration or session replacement; save required outputs to persistent storage An agent instance rejects overlapping calls to the same logical session instead of queuing them. Serialize submissions per session. Readiness and execution are controlled by ready_timeout and request_timeout, respectively

Inbound authentication

When the current context contains inbound credentials, the agent forwards them through the inbound_auth header to preserve the original user identity. Without those credentials, the header is omitted. This does not bypass the sandbox’s own access authentication: X-API-Key, configured by api_key, serves a separate purpose Forward identity credentials only to trusted sandboxes. See inbound authentication

Error handling

Readiness timeouts, execution timeouts, and protocol incompatibility usually return events containing error_message. Concurrent-call conflicts, initialization failures, and cancellation may still propagate to the caller. Handle both event errors and call exceptions Runner.run returns text only. Use Runner.run_async to inspect progress and distinguish errors from normal answers. Timeouts and cancellation trigger a best-effort remote stop; they do not prove that an operation was never executed. Confirm remote state before retrying a task with side effects
Last modified on September 19, 2026