Witty-Insight API完全手册会话查询、中断统计与技能分析接口详解【免费下载链接】witty-insightThe witty-insight is an eBPF-based observability framework for tracing agent execution pipelines.项目地址: https://gitcode.com/openeuler/witty-insight前往项目官网免费下载https://ar.openeuler.org/ar/Witty-Insight是一款基于eBPF的AI Agent运行时观测框架提供了一套完整的HTTP API接口用于查询会话数据、监控中断事件和分析技能使用情况。本手册将详细介绍所有API端点的功能、参数和使用方法帮助您快速掌握Witty-Insight的数据查询能力。 快速开始启动API服务器在开始使用API之前首先需要启动Witty-Insight的HTTP服务器# 构建项目 make build # 启动eBPF追踪需要root权限 sudo ./target/release/agentsight trace # 启动HTTP API服务器 ./target/release/agentsight serve # 或使用统一启动脚本 ./scripts/agentsight-start.sh默认情况下API服务器将在http://localhost:8080启动。您可以通过--host和--port参数自定义监听地址。 基础健康检查与指标GET /health - 健康检查功能检查服务状态和版本信息响应示例{ status: ok, version: 1.0.0, uptime_seconds: 3600 }GET /metrics - Prometheus指标功能提供Prometheus格式的监控指标包括Token消耗统计和中断事件计数指标示例# HELP agentsight_token_total Total token consumption # TYPE agentsight_token_total counter agentsight_token_total{modelgpt-4,directioninput} 1500 agentsight_token_total{modelgpt-4,directionoutput} 2500 # HELP agentsight_interruptions_total Total interruption events by type # TYPE agentsight_interruptions_total counter agentsight_interruptions_total{typeagent_crash} 5 agentsight_interruptions_total{typesse_truncated} 12️ 会话查询APIGET /api/sessions - 会话列表查询功能查询所有会话的聚合统计信息查询参数 | 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| |start_ns| int64 | 否 | 24小时前 | 开始时间纳秒 | |end_ns| int64 | 否 | 当前时间 | 结束时间纳秒 | |session_id| string | 否 | - | 过滤单个会话ID | |session_ids| string[] | 否 | - | 过滤多个会话ID |响应结构[ { session_id: sess_abc123, start_time_ns: 1721123456789, end_time_ns: 1721129876543, agent_name: claude-desktop, total_tokens: 4500, total_requests: 12, interruption_count: 2 } ]GET /api/sessions/{id}/traces - 会话下的Trace功能获取指定会话的所有Trace记录路径参数id会话ID响应结构[ { trace_id: trace_xyz789, session_id: sess_abc123, conversation_id: conv_def456, start_time_ns: 1721123456789, end_time_ns: 1721124567890, model: gpt-4, input_tokens: 500, output_tokens: 750, status: success } ]GET /api/traces/{id} - Trace详情功能获取单个Trace的详细信息路径参数idTrace ID响应结构{ trace_id: trace_xyz789, session_id: sess_abc123, conversation_id: conv_def456, model: gpt-4, input_tokens: 500, output_tokens: 750, total_tokens: 1250, start_time_ns: 1721123456789, end_time_ns: 1721124567890, duration_ms: 1101, status: success, finish_reason: stop, error_message: null }GET /api/conversations/{id} - 对话事件详情功能获取指定对话的所有事件路径参数id对话ID⚡ 中断事件监控APIWitty-Insight能够检测多种类型的中断事件帮助您及时发现和解决AI Agent运行中的问题。中断事件类型类型描述严重级别agent_crashAgent进程在会话中途消失criticalrate_limitHTTP 429或包含rate_limit的错误highauth_errorHTTP 401/403或认证错误highnetwork_timeoutHTTP 408/504或超时错误mediumservice_unavailableHTTP 502/503或服务不可用mediumsafety_filterLLM安全策略导致的过滤mediumsse_truncatedSSE流未正常结束highcontext_overflow上下文长度超限hightoken_limit输出Token达到限制mediumllm_errorHTTP状态码≥400的通用错误mediumretry_storm同一错误重复出现多次highdead_loopAgent陷入逻辑循环criticalGET /api/interruptions - 中断事件列表功能查询中断事件列表查询参数 | 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| |start_ns| int64 | 否 | 24小时前 | 开始时间 | |end_ns| int64 | 否 | 当前时间 | 结束时间 | |type| string | 否 | - | 过滤中断类型 | |severity| string | 否 | - | 过滤严重级别 | |agent_name| string | 否 | - | 过滤Agent名称 | |resolved| boolean | 否 | - | 过滤解决状态 | |limit| int | 否 | 100 | 返回数量限制 |响应示例[ { interruption_id: int_123456, session_id: sess_abc123, conversation_id: conv_def456, agent_name: claude-desktop, interruption_type: sse_truncated, severity: high, detected_at_ns: 1721123456789, resolved_at_ns: null, error_message: SSE stream ended without finish_reason, metadata: { trace_id: trace_xyz789, http_status: 200, model: gpt-4 } } ]GET /api/interruptions/count - 中断计数统计功能按严重级别统计中断事件数量查询参数同/api/interruptions响应结构{ total: 45, by_severity: { critical: 3, high: 12, medium: 20, low: 10 } }GET /api/interruptions/stats - 中断类型统计功能按类型统计中断事件数量响应结构[ { interruption_type: sse_truncated, count: 15, severity: high }, { interruption_type: agent_crash, count: 3, severity: critical } ]GET /api/interruptions/session-counts - 会话中断统计功能按会话分组统计中断事件响应结构[ { session_id: sess_abc123, total: 5, by_severity: { critical: 1, high: 2, medium: 2, low: 0 }, types: [ { interruption_type: agent_crash, severity: critical, count: 1 }, { interruption_type: sse_truncated, severity: high, count: 2 } ] } ]GET /api/interruptions/conversation-counts - 对话中断统计功能按对话分组统计中断事件响应结构同会话中断统计但按conversation_id分组GET /api/interruptions/{id} - 单个中断详情功能获取单个中断事件的详细信息路径参数id中断事件IDPOST /api/interruptions/{id}/resolve - 标记中断为已解决功能标记指定中断事件为已解决状态路径参数id中断事件ID响应204 No Content成功或错误信息GET /api/sessions/{id}/interruptions - 会话中断列表功能获取指定会话的所有中断事件路径参数id会话IDGET /api/conversations/{id}/interruptions - 对话中断列表功能获取指定对话的所有中断事件路径参数id对话ID️ 技能分析APIWitty-Insight提供了强大的技能使用分析功能帮助您了解AI Agent的技能使用情况。GET /api/skill-metrics - 技能统计总览功能获取完整的技能使用统计报告查询参数 | 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| |start_ns| int64 | 否 | 7天前 | 开始时间 | |end_ns| int64 | 否 | 当前时间 | 结束时间 | |agent_name| string | 否 | - | 过滤Agent名称 | |granularity| string | 否 | week | 热度趋势粒度day或week |响应结构{ downloads: { skill_name: { first_seen_session_id: sess_abc123, first_seen_timestamp_ns: 1721123456789, total_sessions: 25 } }, loads: { loads: { skill_name: 150 }, total_loads: 500 }, usage_ratio: { ratio: 0.75, with_skill_count: 300, without_skill_count: 100, total_sessions: 400 }, distribution: { min: 0, max: 8, mean: 2.5, median: 2.0, p90: 5.0, histogram: [50, 100, 120, 80, 30, 20] }, hotness: { skills: [ { skill_name: web_search, total_loads: 150, total_rank: 1, weekly_ranks: [ { iso_week: 2024-W28, load_count: 45, rank: 1 } ], rank_delta: 0 } ] } }GET /api/skill-metrics/downloads - 技能下载统计功能获取技能下载统计数据GET /api/skill-metrics/loads - 技能加载统计功能获取技能加载统计数据GET /api/skill-metrics/usage-ratio - 技能使用率功能获取任务中使用技能的比例GET /api/skill-metrics/distribution - 技能分布统计功能获取每个任务使用技能数量的分布情况GET /api/skill-metrics/hotness - 技能热度统计功能获取技能热度排名和趋势分析 其他实用APIGET /api/agent-names - Agent名称列表功能获取所有已发现的Agent名称列表响应示例[claude-desktop, vscode-copilot, cursor-agent]GET /api/timeseries - 时序Token统计功能获取时间序列的Token消耗统计查询参数 | 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| |start_ns| int64 | 否 | 1小时前 | 开始时间 | |end_ns| int64 | 否 | 当前时间 | 结束时间 | |bucket_seconds| int | 否 | 300 | 时间桶大小秒 | |model| string | 否 | - | 过滤模型名称 |响应结构[ { bucket_start_ns: 1721123400000, bucket_end_ns: 1721123700000, model: gpt-4, input_tokens: 1200, output_tokens: 1800, total_tokens: 3000, request_count: 8 } ]GET /api/agent-health - Agent健康状态功能获取所有Agent的健康状态响应结构[ { pid: 12345, agent_name: claude-desktop, status: healthy, last_seen_ns: 1721123456789, uptime_seconds: 3600, interruption_count: 2 } ]DELETE /api/agent-health/{pid} - 删除健康条目功能删除指定PID的Agent健康记录POST /api/agent-health/{pid}/restart - 重启Agent功能触发Agent重启需要相应的重启机制支持GET /api/token-savings - Token节省统计功能获取Token节省统计数据 数据导出APIGET /api/export/atif/trace/{id} - ATIF Trace导出功能将指定Trace导出为ATIF格式路径参数idTrace IDGET /api/export/atif/session/{id} - ATIF Session导出功能将指定会话导出为ATIF格式路径参数id会话IDGET /api/export/atif/conversation/{id} - ATIF Conversation导出功能将指定对话导出为ATIF格式路径参数id对话ID 最佳实践与使用技巧1. 时间范围查询优化# 查询最近24小时的数据 curl http://localhost:8080/api/sessions?start_ns$(date -d 24 hours ago %s%9N) # 查询指定时间范围 curl http://localhost:8080/api/interruptions?start_ns1721123456789000000end_ns17212134567890000002. 中断事件监控告警# 监控critical级别中断 curl http://localhost:8080/api/interruptions/count?severitycritical # 获取未解决的中断事件 curl http://localhost:8080/api/interruptions?resolvedfalselimit103. 技能使用分析# 分析最热门的技能 curl http://localhost:8080/api/skill-metrics/hotness # 查看技能使用趋势 curl http://localhost:8080/api/skill-metrics?granularitydaystart_ns$(date -d 30 days ago %s%9N)4. 性能监控仪表板# 构建完整的监控仪表板数据 curl http://localhost:8080/api/sessions?limit50 curl http://localhost:8080/api/interruptions/stats curl http://localhost:8080/api/timeseries?bucket_seconds3600 错误处理与状态码Witty-Insight API使用标准的HTTP状态码状态码含义常见场景200 OK请求成功数据查询成功400 Bad Request请求参数错误参数格式不正确404 Not Found资源不存在指定的ID不存在500 Internal Server Error服务器内部错误数据库连接失败503 Service Unavailable服务不可用中断存储未初始化错误响应格式{ error: 错误描述信息 } API使用示例示例1监控AI Agent的健康状态#!/bin/bash # 监控脚本示例 API_URLhttp://localhost:8080 # 检查服务健康 health$(curl -s $API_URL/health) echo 服务状态: $(echo $health | jq -r .status) # 获取中断统计 interruptions$(curl -s $API_URL/api/interruptions/count) critical_count$(echo $interruptions | jq -r .by_severity.critical) if [ $critical_count -gt 0 ]; then echo ⚠️ 发现 $critical_count 个严重中断事件 fi # 获取活跃会话 sessions$(curl -s $API_URL/api/sessions?limit10) echo 活跃会话数: $(echo $sessions | jq length)示例2生成技能使用报告# Python示例 import requests import json from datetime import datetime, timedelta def generate_skill_report(): base_url http://localhost:8080 # 获取技能统计数据 response requests.get(f{base_url}/api/skill-metrics) data response.json() print( 技能使用报告 ) print(f总技能加载次数: {data[loads][total_loads]}) print(f技能使用率: {data[usage_ratio][ratio]*100:.1f}%) # 输出热门技能 print(\n热门技能排名:) for skill in data[hotness][skills][:5]: print(f {skill[skill_name]}: {skill[total_loads]}次加载) return data if __name__ __main__: generate_skill_report() 注意事项时间格式所有时间参数均为纳秒级时间戳数据保留默认数据保留策略为7天可通过配置调整性能影响大量历史数据查询可能影响性能建议使用时间范围过滤安全考虑生产环境建议启用身份验证和访问控制存储位置默认数据库路径为/var/log/sysak/.agentsight/interruption_events.db通过Witty-Insight的完整API套件您可以全面监控AI Agent的运行状态、及时发现中断问题、分析技能使用情况为AI应用的可观测性提供强大支持。【免费下载链接】witty-insightThe witty-insight is an eBPF-based observability framework for tracing agent execution pipelines.项目地址: https://gitcode.com/openeuler/witty-insight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
