# Metadata Management
<subtitle>Attach custom tags to sandboxes for multi-dimensional filtering and session association.</subtitle>

## Environment Setup

Before using the SDK, please ensure that the `AGENTBOX_API_KEY` environment variable is configured.

>
> You can obtain your API key from the [Console API Keys page](https://console.ucloud.cn/modelverse/experience/api-keys).

```bash
export AGENTBOX_API_KEY=your_api_key
```

Metadata allows you to associate custom key-value pairs with sandboxes. This is very valuable when managing large-scale concurrent sandboxes.

## Typical Use Cases

*   **Session Association**: Bind sandbox to a specific end-user Session ID.
*   **Permission Passthrough**: Store custom user identifiers (such as `userId`) for sandboxes to facilitate retrospective queries.
*   **Business Classification**: Label the project or task type that the sandbox belongs to.

## Set and Access Metadata

You need to specify the `metadata` parameter when creating a sandbox. After that, you can access it through the `metadata` field of sandbox information.

```python
from ucloud_sandbox import Sandbox

# 1. Create sandbox with metadata
sandbox = Sandbox.create(
    metadata={
        'userId': 'user_1a2b3c',
        'taskType': 'data-analysis'
    },
)

# 2. Access current sandbox metadata
print(sandbox.get_info())


# 3. Access metadata through list interface
running_sandboxes = Sandbox.list().next_items()
for sbx in running_sandboxes:
    if sbx.metadata.get('taskType') == 'data-analysis':
        print(f"Found analysis sandbox: {sbx.sandbox_id}")
```

## Filter by Metadata

Together with the `Sandbox.list()` method, you can efficiently retrieve the required sandbox instances by tags. For details, please refer to [List Query](/docs/agent-sandbox/sdk/sandbox/08-list).