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