您的第一个任务
让我们向 Shannon 提交一个简单的任务并看看它的运行情况。本指南假设您已完成安装。
使用 REST API
与 Shannon 交互的最简单方式是通过其 REST API：
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"query": "分析以下句子的情感：Shannon 让 AI 智能体变得简单可靠！"
}'
{
"task_id": "task-dev-1730000000",
"status": "TASK_STATUS_RUNNING",
"message": "Task submitted",
"created_at": "2024-10-22T10:30:00Z"
}
检查任务状态
使用 task_id 检查状态：
curl http://localhost:8080/api/v1/tasks/task-dev-1730000000
{
"task_id": "task-dev-1730000000",
"status": "TASK_STATUS_COMPLETED",
"response": { "result": "The sentiment is overwhelmingly positive..." },
"error": "",
"query": "分析以下句子的情感：Shannon 让 AI 智能体变得简单可靠！",
"session_id": "...",
"mode": "EXECUTION_MODE_STANDARD",
"created_at": "2024-10-22T10:30:00Z",
"updated_at": "2024-10-22T10:30:25Z"
}
实时流式传输事件
Shannon 支持服务器发送事件 (SSE) 进行实时更新：
curl -N http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-1730000000
event: LLM_PROMPT
data: {"message":"Analyzing sentiment..."}
event: WORKFLOW_COMPLETED
data: {"result":"The sentiment is positive..."}
使用 Python SDK
为了获得更好的开发体验，请使用 Python SDK：
提交和监控任务
from shannon import ShannonClient
# HTTP 客户端（默认：http://localhost:8080）
client = ShannonClient()
handle = client.submit_task(
query="分析以下句子的情感：Shannon 让 AI 智能体变得简单！"
)
print("Task submitted:", handle.task_id)
# 等待完成
final = client.wait(handle.task_id, timeout=60)
print("Result:", final.result)
流式传输事件
# 实时流式传输事件
for event in client.stream(handle.workflow_id):
print(f"{event.type}: {event.message}")
执行模式
Shannon 根据任务复杂度自动选择执行模式。您可以通过在任务提交中传递 mode 参数（simple、standard、complex、supervisor）来覆盖此行为。
成本控制
预算控制由 Shannon 管理。目前还不能通过 REST 设置每个请求的明确预算。
多轮对话
Shannon 支持基于会话的对话：
session_id = "my-conversation-123"
# 第一条消息
handle1 = client.submit_task(
query="法国的首都是哪里？",
session_id=session_id
)
# 后续消息（Shannon 记住上下文）
handle2 = client.submit_task(
query="人口是多少？",
session_id=session_id
)
# Shannon 知道您在询问巴黎的人口
使用桌面应用
如果需要图形界面来查看任务和会话，请使用 Shannon 桌面应用程序（基于 Tauri 的客户端）。参见桌面应用程序了解安装和使用细节。
示例用例
Shannon 根据查询复杂度自动选择适当的执行模式和认知策略。您无需指定这些参数。
情感分析
client.submit_task(
query="分析情感：这个产品超出了我的预期！"
)
研究与摘要
client.submit_task(
query="研究 2024 年量子计算的突破性进展并创建摘要"
)
代码生成
client.submit_task(
query="编写一个使用记忆化计算斐波那契数列的 Python 函数"
)
带上下文的复杂分析
client.submit_task(
query="比较微服务架构与单体架构的优缺点",
context={
"domain": "software_architecture",
"depth": "comprehensive",
"include_examples": True
}
)
下一步是什么？
Python SDK 指南
深入了解 SDK 功能和异步使用
故障排除
检查日志中的错误：docker compose logs orchestrator
docker compose logs agent-core
- 无效的 LLM API 密钥
- LLM 提供商速率限制
- 网络连接问题
Shannon 默认禁用认证（GATEWAY_SKIP_AUTH=1）。如果您启用了认证，请包含 API 密钥：curl -H "X-API-Key: sk_test_123456" \
http://localhost:8080/api/v1/tasks
预算限制通过环境变量在平台级别配置：# 在 .env 文件中
MAX_TOKENS_PER_REQUEST=10000
MAX_COST_PER_REQUEST=0.50
# 重启服务以使更改生效
docker compose restart
