#Agent Observability Demo

• 智能体插桩库
• 已插桩的智能体项目示例

#演示Demo

#实现了基础的交互和LLM插桩

Agent基础交互，包含多轮对话和工具调用:

使用OTEL_STDOUT开启遥测信号回显：

使用CAPTURE_CONTENT开启对用户输入和LLM响应的采集：

#Grafana 仪表盘

#Agent架构

flowchart TD
    User["👤 User / API"]

    subgraph Agent["🧠 Agent"]
        direction TB
        A1["多轮对话状态管理"]
        A2["上下文窗口累积"]
        A3["自动 Tool Call 闭环（≤10 轮）"]
        A4["工具执行记录返回"]
    end

    subgraph Client["🔌 Client（LLMGateway）"]
        C1["通用 GenAI 提供商封装"]
        C2["HTTP RPC 调用"]
        C3["请求 / 响应 JSON 序列化"]
        C4["OpenTelemetry GenAI 插桩"]
    end

    API["☁️ GenAI Provider API<br/>（默认 StepFun）"]

    subgraph TR["🔧 ToolRegistry"]
        T1["工具注册与路由"]
        T2["参数解析与执行"]
        T3["安全策略（命令白名单）"]
    end

    subgraph Tools["🛠️ External Tools"]
        TW["🌤️ get_weather / lookup_city（QWeather）"]
        TC["💻 execute_command（安全受限）"]
    end

    OTel["📊 OpenTelemetry<br/>trace / span / event 插桩"]

    User --> Agent
    Agent --> Client
    Client --> API
    Agent --> TR
    TR --> Tools

    OTel -.->|全链路插桩| Agent
    OTel -.->|GenAI 语义约定| Client
    OTel -.-> TR

#核心模块

#快速开始

#依赖

• MoonBit 工具链
• Linux 系统需安装 build-essential（提供 C 头文件用于 native 编译）

#配置

cp .env.example .env
# 编辑 .env，填入你的 API Key

#运行

# 检查类型
moon check

# 运行 REPL
moon run cmd/main

# 非交互式单次运行（适合 CI / 演示 / 脚本）
moon run cmd/main -- --ask "北京今天天气怎么样？"

#测试

# 运行所有 async test
moon test

#本地可观测性栈

cd deploy/minimum
docker compose up -d

• OTLP HTTP receiver: http://localhost:4318
• OTLP gRPC receiver: http://localhost:4317
• Jaeger UI: http://localhost:16686

OTEL_STDOUT=false moon run cmd/main

#agent-telemetry 库

#项目结构

agent-observability/
├── agent-telemetry/         # 独立 MoonBit 插桩库（已发布到 mooncakes.io）
│                            # 封装 OTel 初始化、tracer、GenAI/Tool/Agent 语义 helper
├── cmd/main/                # REPL 可执行入口
├── deploy/                  # 一键部署配置
│   ├── minimum/             #   本地 Collector + Jaeger（docker-compose）
│   └── greptime/            #   生产级 GreptimeDB + Grafana 栈
├── docs/                    # 文档
│   ├── instrumentation.md   #   插桩位置与 Span 命名详解
│   └── findings.md          #   开发过程中的技术发现记录
├── scripts/                 # 辅助脚本
├── proposal.md              # 比赛申报书
├── report.md                # 结项报告
├── AGENTS.md                # 开发指南与约定
├── .env.example             # 环境变量配置模板
└── moon.work                # 工作区定义（根包 + agent-telemetry）

#技术栈

#已知问题

#moon check 中的 unused_package 警告

1. moonbitlang/async 报 unused：async fn / async test 语法需要此包，但编译器只检测 @async.xxx 显式调用，不把关键字本身算作"使用"。
2. 测试依赖报 unused（@sdk 等）：这些包在测试文件中使用，但 MoonBit 的 moon.pkg 是包级配置，编译器不把测试文件中的使用算作"库的使用"。
3. agent-telemetry 包与根应用通过 moon.work 组成工作区；根应用导入本地 cybershang/agent-telemetry 包。
4. agent-telemetry 默认后端为 native：opentelemetry/otlp 依赖的 async/http、async/socket 接口只在 native 后端可用，因此库模块声明了 preferred_target = "native"。

#许可证