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
CodeEnv with the actual tool type:
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 asremote_sandbox.py and run python remote_sandbox.py from the configured terminal:
remote_sandbox.py
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 specificdescription so the coordinator can recognize suitable work
coordinator.py
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 theinbound_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 containingerror_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