智能体管理与发布

这些接口需要 Bearer Key，并且只允许操作当前账号拥有的智能体。

接口

方法与路径	说明
`GET /api/v1/agents/available-hosts`	查询当前账号在线主机及其引擎。
`GET /api/v1/agents/mine`	分页查询我的智能体。
`POST /api/v1/agents`	创建智能体，或创建并提交发布。
`GET /api/v1/agents/{id}/manage`	查询管理详情。
`PATCH /api/v1/agents/{id}`	更新配置，或提交发布。
`DELETE /api/v1/agents/{id}`	删除智能体及关联资源，成功返回 `204`。

管理视图的智能体对象字段与市场详情基本一致（见智能体市场），并额外包含 hostName、hostUp、lastUsedAt（仅管理详情返回），不包含 hostId、workDir。不需要传 model——引擎使用自身默认模型，并在实际运行后上报模型名称；查询接口只读展示该实际值。

获取 hostId 和 engine

创建智能体前，先查询当前 API Key 所属账号的可用主机：

http

GET /api/v1/agents/available-hosts HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为主机数组，主机 id 用作 hostId，engines[].id 用作 engine：

json

{
  "code": "0",
  "message": "ok",
  "data": [
    {
      "id": "host-01JQ2R8X1A3B4C5D6E7F8G9",
      "name": "我的主机",
      "status": "online",
      "engines": [
        { "id": "claude-code", "displayName": "Claude Code" },
        { "id": "codex", "displayName": "Codex" }
      ]
    }
  ]
}

hostId 与 engine 必须成对提供。status 可能为 online 或 busy。

查询我的智能体

参数	位置	类型	必填	可选值	默认值	限制
`keyword`	Query	string	否	任意文本	—	最长 `100`
`usageStatus`	Query	string	否	逗号分隔的状态	—	最长 `100`
`scope`	Query	string	否	`public`、`private`	—	—
`engine`	Query	string	否	discovery 返回的 engine ID	—	最长 `80`
`hostId`	Query	string	否	discovery 返回的 host ID	—	最长 `120`
`enable`	Query	string	否	`true`、`false`	—	注意类型为字符串
`sort`	Query	string	否	`recent`、`sessions`、`runs`	按使用量排序	—
`page`	Query	integer	否	—	`1`	最小 `1`
`pageSize`	Query	integer	否	—	`20`	`1`～`100`

http

GET /api/v1/agents/mine?page=1&pageSize=20 HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为 { items, total, page, pageSize, hasMore }：

json

{
  "code": "0",
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "raagent/code-review-3f8a1b2c",
        "name": "代码审查",
        "displayName": "代码审查助手",
        "description": "检查代码中的正确性与安全问题，输出问题清单与修复建议",
        "tags": ["代码", "审查"],
        "category": "dev-tool",
        "scope": "public",
        "pricing": "free",
        "usageStatus": "online",
        "reviewStatus": "approved",
        "engine": "claude-code",
        "modelName": "claude-opus-4-8",
        "hostName": "我的主机",
        "hostUp": true,
        "expectedInput": "要审查的代码片段",
        "expectedOutput": "问题清单与修复建议",
        "ownerName": "张三",
        "usageCount": 320,
        "sessionCount": 12,
        "runs": 320,
        "cost": 1250000,
        "earn": 0,
        "favoriteCount": 8,
        "favorited": true,
        "sharedWithMe": false,
        "enable": true,
        "version": 3,
        "recent": 1722699000000,
        "createdAt": "2026-07-20T08:30:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}

错误：400 参数不合法；401 凭据缺失或无效。

创建与提交

字段	位置	类型	必填	可选值	默认值	限制
`name`	Body	string	否	—	`new-agent`	`1`～`80`
`displayName`	Body	string	否	—	同 `name`	`1`～`80`
`desc`	Body	string	否	—	空字符串	最长 `1000`
`tags`	Body	string[]	否	—	`[]`	最多 `20` 项，每项 `1`～`30`
`cat`	Body	string	否	分类 ID	`other`	最长 `50`
`scope`	Body	string	否	`public`、`private`	`private`	—
`pay`	Body	string	否	`free`、`paid`	`free`	私有智能体固定免费
`step`	Body	string	否	`draft`、`submit`	—	—
`enable`	Body	boolean	否	`true`、`false`	非草稿默认 `true`	—
`hostId`	Body	string	否	discovery 返回的 host ID	空字符串	最长 `120`，非空时必须属于当前账号
`engine`	Body	string	否	discovery 返回的 engine ID	空字符串	最长 `80`，非空时必须由该主机上报
`workDir`	Body	string	否	相对工作目录	空字符串	最长 `500`；禁止绝对路径和 `..`
`expectedInput`	Body	string	否	—	空字符串	最长 `500`
`expectedOutput`	Body	string	否	—	空字符串	最长 `500`

hostId 与 engine 必须成对提供。请求体不接受额外字段，也不接受 model。

http

POST /api/v1/agents HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "name": "代码审查助手",
  "desc": "检查代码中的正确性与安全问题",
  "tags": ["代码", "审查"],
  "cat": "dev-tool",
  "scope": "public",
  "pay": "free",
  "step": "submit",
  "enable": true,
  "hostId": "host-01JQ2R8X1A3B4C5D6E7F8G9",
  "engine": "claude-code"
}

HTTP 201，data 为创建后的智能体对象：

json

{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "raagent/code-review-3f8a1b2c",
    "name": "代码审查助手",
    "displayName": "代码审查助手",
    "description": "检查代码中的正确性与安全问题",
    "tags": ["代码", "审查"],
    "category": "dev-tool",
    "scope": "public",
    "pricing": "free",
    "usageStatus": "reviewing",
    "reviewStatus": "pending",
    "engine": "claude-code",
    "hostName": "我的主机",
    "hostUp": true,
    "ownerName": "张三",
    "usageCount": 0,
    "sessionCount": 0,
    "runs": 0,
    "cost": 0,
    "earn": 0,
    "favoriteCount": 0,
    "favorited": false,
    "enable": true,
    "version": 1,
    "recent": 1722750000000,
    "createdAt": "2026-08-04T10:00:00.000Z"
  }
}

公开智能体提交后进入审核；修改已审核公开智能体的实质字段会重新进入审核。私有智能体不需要公开审核。错误：400 校验失败（如 hostId/engine 不成对、workDir 含 ..）；404 主机不存在或不属于当前账号；409 状态冲突。

查询管理详情

参数	位置	类型	必填	可选值	默认值	限制
`id`	Path	string	是	当前账号的智能体 ID	—	`1`～`120`；含 `/` 的 ID 在路径中必须 URL 编码

http

GET /api/v1/agents/raagent%2Fcode-review-3f8a1b2c/manage HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为智能体对象并额外包含 lastUsedAt（最近一次会话更新时间，Unix 毫秒，从未使用为 null）：

json

{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "raagent/code-review-3f8a1b2c",
    "name": "代码审查",
    "displayName": "代码审查助手",
    "description": "检查代码中的正确性与安全问题，输出问题清单与修复建议",
    "tags": ["代码", "审查"],
    "category": "dev-tool",
    "scope": "public",
    "pricing": "free",
    "usageStatus": "online",
    "reviewStatus": "approved",
    "engine": "claude-code",
    "modelName": "claude-opus-4-8",
    "hostName": "我的主机",
    "hostUp": true,
    "expectedInput": "要审查的代码片段",
    "expectedOutput": "问题清单与修复建议",
    "ownerName": "张三",
    "usageCount": 320,
    "sessionCount": 12,
    "runs": 320,
    "cost": 1250000,
    "earn": 0,
    "favoriteCount": 8,
    "favorited": true,
    "enable": true,
    "version": 3,
    "lastUsedAt": 1722730200000,
    "recent": 1722699000000,
    "createdAt": "2026-07-20T08:30:00.000Z"
  }
}

错误：404 智能体不存在或不属于当前账号。

更新或提交发布

参数	位置	类型	必填	可选值	默认值	限制
`id`	Path	string	是	当前账号的智能体 ID	—	`1`～`120`；含 `/` 的 ID 在路径中必须 URL 编码

PATCH 使用与创建相同的可写字段集合（见上表）。若要提交当前配置，可只发送 step：

http

PATCH /api/v1/agents/raagent%2Fcode-review-3f8a1b2c HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "step": "submit"
}

HTTP 200，data 为更新后的智能体对象：

json

{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "raagent/code-review-3f8a1b2c",
    "name": "代码审查",
    "displayName": "代码审查助手",
    "description": "检查代码中的正确性与安全问题，输出问题清单与修复建议",
    "tags": ["代码", "审查"],
    "category": "dev-tool",
    "scope": "public",
    "pricing": "free",
    "usageStatus": "reviewing",
    "reviewStatus": "pending",
    "engine": "claude-code",
    "hostName": "我的主机",
    "hostUp": true,
    "expectedInput": "要审查的代码片段",
    "expectedOutput": "问题清单与修复建议",
    "ownerName": "张三",
    "usageCount": 320,
    "sessionCount": 12,
    "runs": 320,
    "cost": 1250000,
    "earn": 0,
    "favoriteCount": 8,
    "favorited": true,
    "enable": true,
    "version": 4,
    "recent": 1722751200000,
    "createdAt": "2026-07-20T08:30:00.000Z"
  }
}

错误：400 校验失败；404 智能体不存在或不属于当前账号；409 状态冲突。

删除智能体

参数	位置	类型	必填	可选值	默认值	限制
`id`	Path	string	是	当前账号的智能体 ID	—	`1`～`120`；含 `/` 的 ID 在路径中必须 URL 编码

http

DELETE /api/v1/agents/raagent%2Fcode-review-3f8a1b2c HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 204，无响应体。删除不可逆，并会删除关联会话。错误：404 智能体不存在或不属于当前账号。

智能体管理与发布 ​

接口 ​

获取 hostId 和 engine ​

查询我的智能体 ​

创建与提交 ​

查询管理详情 ​

更新或提交发布 ​

删除智能体 ​

智能体管理与发布

接口

获取 hostId 和 engine

查询我的智能体

创建与提交

查询管理详情

更新或提交发布

删除智能体