实现M002 V3 P0.1 Parent Group路由修订
This commit is contained in:
andy
306
docs/import/20260712/OPEN_AGENT_API_CURL_EXAMPLES.md
Normal file
306
docs/import/20260712/OPEN_AGENT_API_CURL_EXAMPLES.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# Agent Profile Open API Curl 请求示例
|
||||
|
||||
本文档用于外部系统调用已发布的 Agent Profile。示例环境域名：
|
||||
|
||||
```bash
|
||||
export DEERFLOW_BASE_URL="https://superagent.nianxx.cn"
|
||||
export DEERFLOW_OPEN_API_KEY="df_open_xxx"
|
||||
```
|
||||
|
||||
`DEERFLOW_OPEN_API_KEY` 使用的是 Ops 中 `Agent Profile Open API` 创建外部应用时生成的 `df_open_...` token，不是“新建应用”的普通业务 token。
|
||||
|
||||
## Profile 调用规则
|
||||
|
||||
公开 API 请求里不直接传 `profile_id`。系统通过当前 `df_open_...` token 对应的外部应用策略来决定调用哪个 Profile：
|
||||
|
||||
- 外部应用策略配置了 `profile_id`：固定调用该 Profile 的已发布版本。
|
||||
- 外部应用策略未配置 `profile_id`：调用组织默认 Profile 的已发布版本。
|
||||
- 目标 Profile 必须已发布，并且该 Profile 的 API exposure 已启用。
|
||||
|
||||
## 执行过程 Trace 策略
|
||||
|
||||
如果对接方需要看到 Agent 执行任务的过程数据，需要在 Ops 的 `Agent Profile Open API` 外部应用策略中显式开启 `trace_policy`：
|
||||
|
||||
```json
|
||||
{
|
||||
"profile_id": "profile_xxx",
|
||||
"trace_policy": {
|
||||
"enabled": true,
|
||||
"expose_tool_inputs": "summary",
|
||||
"expose_tool_outputs": "summary",
|
||||
"expose_step_updates": "summary",
|
||||
"expose_task_events": "summary"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `include_trace=true` 只在 `trace_policy.enabled=true` 时可用。
|
||||
- 系统不会开放模型原始 chain-of-thought。对外只返回公开推理摘要，例如“正在分析问题并规划下一步操作”。
|
||||
- 工具入参、工具输出默认建议使用 `summary`，避免把敏感业务数据或内部上下文完整暴露给第三方。
|
||||
- 如果确实需要完整工具入参或输出，可以把对应项设为 `full`；如果完全不希望透出，可以设为 `redacted`。
|
||||
|
||||
## 认证方式
|
||||
|
||||
推荐使用 Bearer token：
|
||||
|
||||
```bash
|
||||
Authorization: Bearer df_open_xxx
|
||||
```
|
||||
|
||||
也可以使用请求头：
|
||||
|
||||
```bash
|
||||
X-DeerFlow-Open-API-Key: df_open_xxx
|
||||
```
|
||||
|
||||
## 1. 创建会话
|
||||
|
||||
一个外部用户、一个微信会话、一个 CRM 会话，建议对应一个 Open Agent Session。这样 Agent 可以保留同一会话里的上下文。
|
||||
|
||||
```bash
|
||||
curl -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"external_subject_id": "wechat-user-001",
|
||||
"idempotency_key": "wechat-session-001",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001",
|
||||
"source": "wechat"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
示例响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "open_sess_xxx",
|
||||
"status": "active",
|
||||
"external_subject_id": "wechat-user-001",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001",
|
||||
"source": "wechat"
|
||||
},
|
||||
"created_at": "2026-06-22T10:00:00Z",
|
||||
"updated_at": "2026-06-22T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 流式发送消息
|
||||
|
||||
推荐优先使用流式接口。它会通过 SSE 返回运行过程和最终输出。
|
||||
|
||||
```bash
|
||||
curl -N -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/messages/stream" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "你好，帮我介绍一下养马岛有什么玩的？",
|
||||
"idempotency_key": "msg-001",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001",
|
||||
"customer_id": "wechat-user-001"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
其中 `{session_id}` 替换为创建会话接口返回的 `session_id`。
|
||||
|
||||
## 2.1 流式发送消息并返回公开 Trace
|
||||
|
||||
对接方需要看到执行过程、工具调用、步骤更新时，使用 `include_trace=true`：
|
||||
|
||||
```bash
|
||||
curl -N -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/messages/stream?include_trace=true" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "帮我查询刘亦菲最近动态，并标注信息来源。",
|
||||
"idempotency_key": "msg-trace-001",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001",
|
||||
"customer_id": "wechat-user-001"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
SSE 返回统一使用 `event: trace`，具体事件类型在 `data.event` 中：
|
||||
|
||||
```text
|
||||
event: trace
|
||||
data: {"event":"run.started","run_id":"run_xxx","thread_id":"thread_xxx","external_app_id":"external-app-xxx","org_id":"org-1","ts":"2026-07-11T10:00:00Z"}
|
||||
|
||||
event: trace
|
||||
data: {"event":"reasoning.summary","run_id":"run_xxx","text":"正在分析问题并规划下一步操作。","external_app_id":"external-app-xxx","org_id":"org-1","ts":"2026-07-11T10:00:01Z"}
|
||||
|
||||
event: trace
|
||||
data: {"event":"tool.call.started","run_id":"run_xxx","message_id":"ai-1","tool_calls":[{"tool_call_id":"tool-1","name":"web_search","input":{"summary":"{\"query\":\"刘亦菲最近动态\"}"}}],"external_app_id":"external-app-xxx","org_id":"org-1","ts":"2026-07-11T10:00:02Z"}
|
||||
|
||||
event: trace
|
||||
data: {"event":"tool.call.completed","run_id":"run_xxx","tool_call_id":"tool-1","name":"web_search","output":{"summary":"..."},"external_app_id":"external-app-xxx","org_id":"org-1","ts":"2026-07-11T10:00:03Z"}
|
||||
|
||||
event: trace
|
||||
data: {"event":"message.delta","run_id":"run_xxx","message_id":"ai-final","text":"根据可检索到的信息...","external_app_id":"external-app-xxx","org_id":"org-1","ts":"2026-07-11T10:00:04Z"}
|
||||
|
||||
event: trace
|
||||
data: {"event":"run.completed","run_id":"run_xxx","status":"success","external_app_id":"external-app-xxx","org_id":"org-1","ts":"2026-07-11T10:00:05Z"}
|
||||
```
|
||||
|
||||
当前公开 Trace 事件包括：
|
||||
|
||||
- `run.started`
|
||||
- `reasoning.summary`
|
||||
- `tool.call.started`
|
||||
- `tool.call.completed`
|
||||
- `message.delta`
|
||||
- `step.updated`
|
||||
- `task.updated`
|
||||
- `progress`
|
||||
- `run.failed`
|
||||
- `run.completed`
|
||||
|
||||
## 2.2 订阅已有 Run 的公开 Trace
|
||||
|
||||
如果对接方使用非流式发送消息拿到了 `run_id`，或者流式连接中断后需要重新订阅过程事件，可以使用：
|
||||
|
||||
```bash
|
||||
curl -N "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/runs/{run_id}/events" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 该接口需要外部应用具备 `agent_sessions:read` scope。
|
||||
- 仍然要求外部应用策略里 `trace_policy.enabled=true`。
|
||||
- 支持通过 `Last-Event-ID` 请求头按底层 stream bridge 的保留窗口重放事件。
|
||||
- 如果底层事件已经被清理，只能订阅后续仍保留或新产生的事件。
|
||||
|
||||
## 3. 非流式发送消息
|
||||
|
||||
非流式接口会立即返回 `run_id`，不直接返回最终答案。外部系统需要继续查询 run 状态，或通过 webhook 接收后续事件。
|
||||
|
||||
```bash
|
||||
curl -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/messages" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "你好，帮我介绍一下养马岛有什么玩的？",
|
||||
"idempotency_key": "msg-002",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
示例响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "open_sess_xxx",
|
||||
"run_id": "run_xxx",
|
||||
"status": "running"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 查询运行状态
|
||||
|
||||
```bash
|
||||
curl "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/runs/{run_id}" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY"
|
||||
```
|
||||
|
||||
示例响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "open_sess_xxx",
|
||||
"run_id": "run_xxx",
|
||||
"status": "running",
|
||||
"metadata": {
|
||||
"source": "open_agent_api",
|
||||
"external_app_id": "external-app-xxx",
|
||||
"resolved_profile_id": "profile_xxx",
|
||||
"resolved_profile_version_id": "version_xxx",
|
||||
"invocation_source": "open_agent_api"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 取消运行
|
||||
|
||||
```bash
|
||||
curl -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/runs/{run_id}/cancel" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY"
|
||||
```
|
||||
|
||||
示例响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "open_sess_xxx",
|
||||
"run_id": "run_xxx",
|
||||
"status": "cancelling",
|
||||
"metadata": {}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 常见错误
|
||||
|
||||
### 401 Unauthorized
|
||||
|
||||
检查 `df_open_...` token 是否正确，或外部应用是否已被停用、移除。
|
||||
|
||||
### 403 Forbidden
|
||||
|
||||
当前外部应用缺少对应 scope。例如：
|
||||
|
||||
- 创建会话需要 `agent_sessions:create`
|
||||
- 发送消息需要 `agent_sessions:message`
|
||||
- 查询 run 需要 `agent_sessions:read`
|
||||
- 取消 run 需要 `agent_sessions:cancel`
|
||||
|
||||
### 404 Default profile has no published version
|
||||
|
||||
外部应用没有绑定 `profile_id`，系统回退到组织默认 Profile，但默认 Profile 没有已发布版本。处理方式：
|
||||
|
||||
- 在 Agent 工作台设置并发布组织默认 Profile。
|
||||
- 或在 Ops 的 `Agent Profile Open API` 外部应用策略里绑定明确的 `profile_id`。
|
||||
|
||||
### 409 Active run
|
||||
|
||||
同一个 session 当前已有运行中的任务。需要等上一个 run 结束，或先取消上一个 run。
|
||||
|
||||
## 7. 最小完整流程
|
||||
|
||||
```bash
|
||||
export DEERFLOW_BASE_URL="https://superagent.nianxx.cn"
|
||||
export DEERFLOW_OPEN_API_KEY="df_open_xxx"
|
||||
|
||||
SESSION_ID=$(
|
||||
curl -s -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"external_subject_id": "wechat-user-001",
|
||||
"idempotency_key": "wechat-session-001",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001",
|
||||
"source": "wechat"
|
||||
}
|
||||
}' | jq -r '.session_id'
|
||||
)
|
||||
|
||||
curl -N -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions/$SESSION_ID/messages/stream" \
|
||||
-H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "你好，帮我介绍一下养马岛有什么玩的？",
|
||||
"idempotency_key": "msg-001",
|
||||
"metadata": {
|
||||
"conversation_id": "wechat-conv-001"
|
||||
}
|
||||
}'
|
||||
```
|
||||
Reference in New Issue
Block a user