Skip to main content

​
概述

Agent Conversation API 提供了一套完整的接口，用于与智能体进行对话交互。通过这些 API，您可以：
  • 创建和管理智能体对话会话
  • 实时接收智能体的响应流
  • 查询历史消息和对话详情
  • 控制智能体的执行流程

​
核心功能

智能体对话

与智能体进行自然语言交互，支持流式（SSE）和非流式两种响应模式
  • 信息检索和分析
  • 工具调用和数据处理
  • 报告生成和内容创作

事件流监控

通过 Server-Sent Events (SSE) 实时监控智能体的执行过程
  • 工作流启动和结束
  • 节点执行状态
  • 智能体思考过程
  • 工具调用详情
  • 流式内容输出

历史记录管理

完整的对话历史记录功能
  • 查询对话详情
  • 获取消息列表（支持分页）
  • 回溯事件流
  • 断点续传

流程控制

灵活控制智能体执行流程
  • 取消正在执行的任务
  • 断点续传支持
  • 实时状态监控

​
API 接口

Create Conversation

创建一个新的智能体对话会话使用场景：开始与智能体的新对话

Chat

与智能体进行对话聊天，支持流式和非流式响应使用场景：发送消息给智能体并接收响应

Fetch Stream Events

获取指定助手消息的所有事件使用场景：断点续传、历史回放、事件查询

Cancel

取消正在执行的智能体任务使用场景：中止长时间运行的任务、用户取消操作

Conversation Detail

获取指定智能体对话的详细信息使用场景：查看对话状态、获取最后一条消息

Messages History

获取指定对话的消息列表，支持分页查询使用场景：查看历史消息、实现聊天记录功能

​
快速开始

1

创建对话

首先创建一个新的智能体对话会话
curl -X POST "https://api.reportify.cn/v1/agent/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 11887655289749510,
    "title": "nvidia 最新业绩分析"
  }'
响应示例：
{
  "id": 683242877840089,
  "agent_id": 11887655289749510,
  "title": "nvidia 最新业绩分析",
  "status": "active"
}
2

发起对话

使用返回的 conversation_id 发送消息给智能体
curl -X POST "https://api.reportify.cn/v1/agent/conversations/683242877840089/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请分析 NVIDIA 最新一季度的财报表现",
    "stream": true
  }' \
  --no-buffer
3

接收事件流

智能体会通过 SSE 流返回执行过程中的各种事件
事件流包含工作流启动、节点执行、智能体思考、工具调用等详细信息，可用于实时展示执行进度
事件示例：
data: {"event_type":"init","event_id":"...","timestamp":1765851195760}

data: {"event_type":"workflow_start","workflow_id":"...","node_id":"start"}

data: {"event_type":"streaming","content":"正在分析 NVIDIA 财报数据..."}

data: {"event_type":"workflow_end","output":{...}}

​
认证

所有 API 请求都需要在 HTTP 请求头中包含 Bearer Token： 
Authorization: Bearer YOUR_API_KEY

​
响应格式

​
流式响应（SSE）

使用 stream=true 时，响应格式为 text/event-stream： 
data: {"event_id":"...","event_type":"...","content":"..."}

​
非流式响应（JSON）

使用 stream=false 时，响应格式为 application/json： 
{
  "assistant_events": [
    {"event_id":"...","event_type":"..."},
    ...
  ]
}

​
错误处理

API 使用标准的 HTTP 状态码：
  • 200 - 请求成功
  • 400 - 请求参数错误
  • 401 - 认证失败
  • 422 - 验证错误
  • 500 - 服务器内部错误
错误响应示例： 
{
  "detail": "Invalid conversation_id"
}

​
最佳实践

使用流式响应对于需要实时反馈的场景，建议使用 stream=true，这样可以：
  • 更快地看到智能体的响应
  • 实时监控执行进度
  • 提供更好的用户体验
保存 assistant_message_id从 Chat 接口的响应头 X-REPORTIFY-ASSISTANT-MESSAGE-ID 中获取并保存 assistant_message_id，用于：
  • 获取消息事件
  • 取消执行
  • 事件回溯
实现断点续传使用 from_offset 参数实现断点续传：
curl -X GET "https://api.reportify.cn/v1/agent/conversations/{conversation_id}/messages/{assistant_message_id}?from_offset=9200"
合理使用分页获取消息列表时，建议：
  • 每次请求不超过 50 条消息
  • 使用 before_message_id 实现向前翻页
  • 缓存已加载的消息

​
下一步

选择一个 API 开始使用：

Create Conversation

创建新的对话会话

Chat

与智能体对话

Fetch Stream Events

获取事件流

Cancel

取消执行