> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote sandbox agent

`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](/productions/veadk/preview/en/components/tools/code-sandbox), 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](/productions/veadk/preview/en/get-started/quickstart); when calling the remote agent directly, the remote service supplies model execution

<Warning>
  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
</Warning>

For Volcengine, configure the following and replace `CodeEnv` with the actual tool type:

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="<access-key>"
export VOLCENGINE_SECRET_KEY="<secret-key>"
export AGENTKIT_TOOL_REGION="cn-beijing"
export AGENTKIT_TOOL_ID="<tool-id>"
export AGENTKIT_TOOL_TYPE="CodeEnv"
```

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:

```python remote_sandbox.py lines theme={null}
import asyncio
import os
from veadk import AgentkitRemoteSandboxAgent, Runner
from veadk.memory.short_term_memory import ShortTermMemory

sandbox = AgentkitRemoteSandboxAgent(
    name="remote_sandbox",
    description="Run code and skills in the remote sandbox.",
    tool_id=os.environ["AGENTKIT_TOOL_ID"],
    tool_type=os.getenv("AGENTKIT_TOOL_TYPE") or None,
)

async def main():
    runner = Runner(agent=sandbox, short_term_memory=ShortTermMemory())
    print(await runner.run(
        messages="Calculate the sum of integers from 1 to 100 using Python.",
        session_id="remote-demo",
    ))

if __name__ == "__main__":
    asyncio.run(main())
```

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

```python coordinator.py lines theme={null}
import asyncio
import os
from veadk import Agent, AgentkitRemoteSandboxAgent, Runner

sandbox = AgentkitRemoteSandboxAgent(
    name="sandbox",
    description="Execute tasks that require remote code, files, or skills.",
    tool_id=os.environ["AGENTKIT_TOOL_ID"],
    tool_type=os.getenv("AGENTKIT_TOOL_TYPE") or None,
)
coordinator = Agent(
    name="coordinator",
    instruction=(
        "Answer general questions directly. Transfer tasks that need code "
        "execution to sandbox using transfer_to_agent."
    ),
    sub_agents=[sandbox],
)

async def main():
    print(await Runner(agent=coordinator).run(
        messages="Use Python to calculate the sum of integers from 1 to 100.",
        session_id="coordinator-demo",
    ))

if __name__ == "__main__":
    asyncio.run(main())
```

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

| `tool_type` | Description |
| :- | :- |
| `Skill` | Runs skill workflows through A2A |
| `CodeEnv` | Runs code, commands, and file tasks through Codex Worker |

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

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `name` | `str` | Required | Agent name, unique within the application |
| `description` | `str` | `""` | Capability description used by the coordinator for transfers |
| `tool_id` | `str \| None` | `None` | Falls back to `AGENTKIT_TOOL_ID` |
| `tool_type` | `Literal["Skill", "CodeEnv"] \| None` | `None` | Automatically discovered when omitted |
| `request_timeout` | `float` | `900` | Task timeout in seconds, greater than 0 and less than 86000 |
| `expiry_buffer` | `float` | `90` | Session lease margin in seconds, at least 0 and less than 86400 |
| `ready_timeout` | `float` | `120` | Session readiness timeout in seconds, greater than 0 |
| `ttl` | `int` | `1800` | Session lifetime in seconds, from 60 to 86400 |
| `prefer_internal_endpoint` | `bool` | `False` | Prefers an internal endpoint reachable from the caller |
| `endpoint` | `str \| None` | `None` | Pre-provisioned session endpoint for testing or self-managed sessions; requires `tool_type` and bypasses control-plane session management |
| `api_key` | `SecretStr \| None` | `None` | Data-plane access key sent as `X-API-Key` |

`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

| Variable | Default | Description |
| :- | :- | :- |
| `AGENTKIT_TOOL_ID` | Unset | Default Tool ID |
| `AGENTKIT_TOOL_REGION` | Volcengine: `cn-beijing`; BytePlus: `ap-southeast-1` | Control-plane region; Volcengine can also inherit `REGION` |
| `AGENTKIT_TOOL_HOST` | SDK endpoint for the environment | Explicit control-plane host override; use an address supplied by the service |
| `AGENTKIT_TOOL_SERVICE_CODE` | `agentkit` | Control-plane service identifier; overriding it also affects the derived endpoint |
| `AGENTKIT_TOOL_SCHEME` | `https` | Control-plane protocol, `http` or `https` |
| `VOLCENGINE_ACCESS_KEY` | Unset | AccessKey variable read by this entry |
| `VOLCENGINE_SECRET_KEY` | Unset | SecretKey variable read by this entry |
| `CLOUD_PROVIDER` | Volcengine | `byteplus` selects the BytePlus default region |

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](/productions/veadk/preview/en/components/security/inbound)

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