Files

andy 92489af18e 实现M002 V3 P0.1 Parent Group路由修订

2026-07-12 11:42:01 +08:00

9.3 KiB

Raw Blame History

Agent Profile Open API Curl 请求示例

本文档用于外部系统调用已发布的 Agent Profile。示例环境域名：

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：

{
  "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：

Authorization: Bearer df_open_xxx

也可以使用请求头：

X-DeerFlow-Open-API-Key: df_open_xxx

1. 创建会话

一个外部用户、一个微信会话、一个 CRM 会话，建议对应一个 Open Agent Session。这样 Agent 可以保留同一会话里的上下文。

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"
    }
  }'

示例响应：

{
  "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 返回运行过程和最终输出。

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：

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 中：

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，或者流式连接中断后需要重新订阅过程事件，可以使用：

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 接收后续事件。

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"
    }
  }'

示例响应：

{
  "session_id": "open_sess_xxx",
  "run_id": "run_xxx",
  "status": "running"
}

4. 查询运行状态

curl "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/runs/{run_id}" \
  -H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY"

示例响应：

{
  "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. 取消运行

curl -X POST "$DEERFLOW_BASE_URL/api/open/agent-sessions/{session_id}/runs/{run_id}/cancel" \
  -H "Authorization: Bearer $DEERFLOW_OPEN_API_KEY"

示例响应：

{
  "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. 最小完整流程

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"
    }
  }'

9.3 KiB Raw Blame History Unescape Escape

Agent Profile Open API Curl 请求示例

Profile 调用规则

执行过程 Trace 策略

认证方式

1. 创建会话

2. 流式发送消息

2.1 流式发送消息并返回公开 Trace

2.2 订阅已有 Run 的公开 Trace

3. 非流式发送消息

4. 查询运行状态

5. 取消运行

6. 常见错误

401 Unauthorized

403 Forbidden

404 Default profile has no published version

409 Active run

7. 最小完整流程

9.3 KiB

Raw Blame History