配置 Harness

SuperAgent API

创建会话、消费 SSE 流、继续追问，并查询会话元数据。

POST/v2/conversations

认证

Bearer API key

Content type

application/json and text/event-stream

限流说明

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API 用于创建带实时 SSE 输出的 AI 对话，并自动关联 LiveDoc。典型流程是创建 conversation、消费 stream、继续追问、查询 conversation detail，并用 LiveDoc 管理上下文资源。

认证

Authorization: Bearer YOUR_API_KEY

1. 创建会话

POST https://openapi.felo.ai/v2/conversations

请求 Body

参数	类型	必填	说明
`query`	string	是	用户问题，1-2000 字符
`live_doc_short_id`	string	否	复用现有 LiveDoc；不传时会创建新的 LiveDoc
`selected_resource_ids`	array of strings	否	用于上下文的资源 ID
`skill_id`	string	否	本次会话使用的 Skill ID
`accept_language`	string	否	语言偏好，例如 `en`
`device_id`	string	否	设备标识
`extra`	object	否	传递给 SuperAgent 的额外参数
`ext`	object	否	扩展参数，例如 `style_id` or `theme`

curl -X POST 'https://openapi.felo.ai/v2/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"What is the latest news about AI?","accept_language":"en"}'

响应字段

字段	类型	说明
`stream_key`	string	Key used to consume the SSE stream
`thread_short_id`	string	Conversation ID for follow-up and detail query
`live_doc_short_id`	string	Associated LiveDoc ID

2. 消费 SSE 流

创建 conversation 后立即连接 stream endpoint，使用 stream_key 接收实时输出。

GET https://openapi.felo.ai/v2/conversations/stream/{stream_key}

参数	类型	必填	说明
`offset`	integer	否	Resume streaming from this position after disconnect

curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

The response uses standard SSE format with events such as message, done, and error. Connect soon after creating the conversation because stream_key has a limited validity window.

3. 继续追问会话

追问现有 conversation。接口会返回新的 stream_key，用于继续消费 SSE stream。

POST https://openapi.felo.ai/v2/conversations/{thread_short_id}/follow_up

参数	类型	必填	说明
`query`	string	是	Follow-up question, 1-2000 characters

4. 查询会话详情

查询 conversation metadata，包括标题、创建时间、更新时间和关联的 LiveDoc ID。

GET https://openapi.felo.ai/v2/conversations/{thread_short_id}

响应字段

字段	类型	说明
`thread_short_id`	string	Conversation ID
`title`	string	Conversation title derived from the query
`created_at`	string	Creation timestamp, ISO 8601
`updated_at`	string	Last update timestamp, ISO 8601
`live_doc_short_id`	string	Associated LiveDoc ID

Typical Integration Flow

1. POST /v2/conversations                              -> get stream_key + thread_short_id + live_doc_short_id
2. GET  /v2/conversations/stream/{stream_key}          -> consume SSE until done
3. POST /v2/conversations/{thread_short_id}/follow_up  -> ask follow-up, get new stream_key
4. GET  /v2/conversations/stream/{new_stream_key}      -> consume follow-up SSE until done
5. GET  /v2/conversations/{thread_short_id}            -> fetch conversation metadata

For LiveDoc CRUD, resource upload, URL import, and retrieval, see the LiveDoc API.

错误码

Code	HTTP Status	说明
`INVALID_API_KEY`	401	API Key is invalid or revoked
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	创建 conversation 失败
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	追问失败
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	查询 conversation detail 失败