API 实战示例

从创建 Cell 到查询用量的端到端 Go 代码示例，展示 wesgine SDK 的典型使用方式。

1. 创建 Hypervisor 并启动引擎

import (
    "github.com/weisyn/wesgine"
    "github.com/weisyn/wesapp/engine"
)

eng, err := engine.StartEngine(ctx, engine.Config{
    DataDir: "/var/lib/myapp",
    Logger:  slog.Default(),
})
if err != nil {
    log.Fatal(err)
}
defer eng.Stop(ctx)

2. 创建 Cell

cell, err := eng.Hypervisor.Cells().GetOrCreate(ctx, wesgine.CellSpec{
    ID:               "dept-legal",
    Timezone:         "Asia/Shanghai",
    Locale:           "zh-CN",
    ProviderStrategy: "shared_only",
})
if err != nil {
    log.Fatal(err)
}

3. 注册 Agent

err = cell.Agents().Register(ctx, agent.AgentConfig{
    ID:          "contract-reviewer",
    Name:        "合同审查助手",
    Description: "专注合同审查的 AI Agent",
    Model:       "gpt-4o",
})

4. 发起 Run（流式）

events, err := cell.Runtime().Run(ctx, wesgine.AppRunRequest{
    Actor:     "alice",
    SessionID: "session-001",
    AgentID:   "contract-reviewer",
    Model:     "gpt-4o",
    Messages: []message.Message{
        {Role: "user", Content: []message.ContentBlock{
            {Type: "text", Text: "请审查这份合同的风险条款"},
        }},
    },
})
if err != nil {
    log.Fatal(err)
}

5. 消费 SSE 事件流

for evt := range events {
    switch evt.Type {
    case engine.EventStreamDelta:
        fmt.Print(evt.Delta) // 流式文本输出
    case engine.EventToolStart:
        fmt.Printf("工具调用: %s\n", evt.ToolName)
    case engine.EventToolEnd:
        fmt.Printf("工具完成: %s\n", evt.ToolName)
    case engine.EventDone:
        fmt.Printf("Run 完成: %s\n", evt.Reason)
    case engine.EventError:
        fmt.Printf("错误: %s\n", evt.Error)
    }
}

6. 查询 Token 用量

usage, err := cell.Observe().TokenUsage(ctx, wesgine.TokenUsageQuery{
    GroupBy: []string{"model", "day"},
    From:    time.Now().AddDate(0, 0, -7),
    To:      time.Now(),
})
for _, u := range usage {
    fmt.Printf("模型=%s 日期=%s 输入=%d 输出=%d\n",
        u.Model, u.Day, u.InputTokens, u.OutputTokens)
}

7. HTTP Gateway 等价操作

对于 HTTP 二进制模式（teleclaw 等），以上操作对应以下端点：

相关文档

• Run API 实战 → run-api-cookbook.md
• Memory API 实战 → memory-api-cookbook.md
• Provider 故障排查 → provider-troubleshooting.md