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

# 运行环境

> /v1/environments — 定义可复用的沙盒运行时、模板与依赖

运行环境（Environment）是一份具名的沙盒模板。多个专家和会话可以引用同一个环境，改一次，引用它的会话下一次运行就生效。

<Note>
  创建环境不会开沙盒。沙盒在引用它的会话第一次运行时才创建。
</Note>

## 创建环境

```
POST https://api.profy.cn/v1/environments
```

<ParamField body="name" type="string" required>
  环境名称。
</ParamField>

<ParamField body="template" type="object">
  沙盒模板。
</ParamField>

<Expandable title="template 字段">
  <ParamField body="runtime" type="string" default="python">
    `python` / `node` / `browser` / `custom`。
  </ParamField>

  <ParamField body="templateId" type="string">
    沙盒基础镜像别名。不传用平台默认镜像。
  </ParamField>

  <ParamField body="dependencies" type="string[]">
    开箱后安装的依赖包，最多 50 个。`python` 走 `pip`，`node` 走 `npm`。
  </ParamField>

  <ParamField body="capabilities" type="string[]">
    能力声明。
  </ParamField>

  <ParamField body="resource_limits" type="object">
    `cpu` / `memory` / `timeout_seconds`。
  </ParamField>
</Expandable>

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/environments \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "报关处理环境",
    "template": {
      "runtime": "python",
      "dependencies": ["pandas", "openpyxl"],
      "resource_limits": { "timeout_seconds": 600 }
    }
  }'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "id": "env_abc",
    "name": "报关处理环境",
    "template": { "runtime": "python", "dependencies": ["pandas", "openpyxl"] },
    "created_at": "...",
    "updated_at": "..."
  }
}
```

## 绑定到会话

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/sessions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "my-expert", "environment_id": "env_abc"}'
```

环境在每次运行前解析，会话上的环境优先于专家自带的沙盒配置。这意味着你调依赖不用重建会话。

## 其它操作

| 方法       | 路径                        | 说明              |
| -------- | ------------------------- | --------------- |
| `GET`    | `/v1/environments?limit=` | 列出你的环境，最多 100 条 |
| `GET`    | `/v1/environments/{id}`   | 环境详情            |
| `PATCH`  | `/v1/environments/{id}`   | 改名或改模板          |
| `DELETE` | `/v1/environments/{id}`   | 软删除，正在运行的沙盒不受影响 |

## 错误码

| HTTP 状态码 | 说明                                            |
| -------- | --------------------------------------------- |
| `400`    | 缺少 `name`，或 `template` 字段非法（runtime 取值、依赖数量等） |
| `401`    | 认证失败                                          |
| `404`    | 环境不存在或不属于你                                    |

## 下一步

<CardGroup cols={2}>
  <Card title="会话" icon="comments" href="/zh/developers/api/sessions">
    创建长期会话并追加事件
  </Card>

  <Card title="管理专家" icon="robot" href="/zh/developers/api/agents">
    用 API 创建和发布专家
  </Card>
</CardGroup>