> ## 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/agents — 用 API 创建、修改和发布专家

除了调用专家，你也可以用 API 创建和维护自己的专家。

<Note>
  新建和修改都停在**草稿**状态。草稿只有作者本人能调用，不需要过审——你可以先建、先调、先改，确认满意再发布到市场。
</Note>

## 创建或更新草稿

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

<ParamField body="name" type="string" required>
  专家名称。同一作者下不能重名。
</ParamField>

<ParamField body="identifier" type="string">
  专家标识符。不传则由名称生成。传已有标识符即为更新（必须是你自己的专家）。
</ParamField>

<ParamField body="version" type="string" default="0.1.0">
  版本号。
</ParamField>

<ParamField body="persona" type="string">
  人格设定（Markdown）。
</ParamField>

<ParamField body="soul" type="string">
  灵魂内容。
</ParamField>

<ParamField body="agent" type="string">
  Agent 指令内容。
</ParamField>

<ParamField body="skill" type="string">
  技能内容。
</ParamField>

<ParamField body="opening_message" type="string">
  开场白。
</ParamField>

<ParamField body="sandbox" type="object">
  沙盒模板，字段同[运行环境](/zh/developers/api/environments)的 `template`。
</ParamField>

<ParamField body="tools" type="object[]">
  工具配置。
</ParamField>

其余可选字段：`description`、`category`、`tags`、`changelog`、`overview`。

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/agents \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "报关助手",
    "identifier": "customs-helper",
    "persona": "你是一名资深报关员…",
    "sandbox": { "runtime": "python", "dependencies": ["pandas"] }
  }'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "identifier": "customs-helper",
    "version": "0.1.0",
    "status": "pending_review",
    "is_update": false,
    "invocable": true
  }
}
```

草稿创建后即可直接调用：

```bash curl theme={null}
curl -N -X POST https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{"expert_identifier": "customs-helper", "message": "试一下"}'
```

## 修改草稿

```
PATCH https://api.profy.cn/v1/agents/{identifier}
```

只传要改的字段即可，`name` 和 `version` 会自动沿用当前值。

## 发布到市场

```
POST https://api.profy.cn/v1/agents/{identifier}/publish
```

<ParamField body="version" type="string">
  发布版本号，不传用当前版本。
</ParamField>

<ParamField body="changelog" type="string">
  更新说明。
</ParamField>

发布走平台审核流程，API 不能绕过审核。

## 其它操作

| 方法    | 路径                            | 说明         |
| ----- | ----------------------------- | ---------- |
| `GET` | `/v1/agents?page=&page_size=` | 列出你创建的专家   |
| `GET` | `/v1/agents/{identifier}`     | 专家详情（作者视角） |

## 错误码

| HTTP 状态码 | 说明                 |
| -------- | ------------------ |
| `400`    | 缺少 `name`          |
| `401`    | 认证失败               |
| `403`    | 不是这个专家的作者，或作者资质未通过 |
| `404`    | 专家不存在              |
| `409`    | 专家名称重复             |

## 下一步

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

  <Card title="运行环境" icon="box" href="/zh/developers/api/environments">
    定义沙盒运行时与依赖
  </Card>
</CardGroup>