#moon-agent

MoonBit 版 LangChain 核心库 —— 类型安全、可组合、可嵌入的 AI Agent 框架

#中文说明

#简介

#特性

#核心抽象

• Prompt 模板：PromptTemplate（{variable} 字符串插值）+ ChatPromptTemplate（多角色有序消息，保留插入顺序，支持 few-shot）
• 输出解析：OutputParser trait + JsonOutputParser（容忍 markdown 代码围栏，兼容 CRLF 换行）
• 对话记忆：BufferMemory（全量历史）、BufferWindowMemory（滑动窗口）、SummaryMemory（周期性 LLM 摘要长对话）、BoxedMemory（trait 对象装箱，支持任意 Memory 实现）
• 工具抽象：Tool trait（声明式 name/description/args_schema/run）+ register_into 桥接到 mizchi/llm 的 ToolRegistry
• 链式编排：LLMChain —— prompt + provider + memory + output_parser，支持流式输出
• ReAct Agent：AgentExecutor —— 封装 run_agent，集成 memory、output_parser、max_steps、流式输出
• 可组合单元：RunnableWrapper[I,O] —— LCEL 式管道组合（pipe）/ 输出变换（map）
• 多链编排：SequentialChain[T] —— 同质多步骤链，顺序执行并传递输出
• 可观测性：UsageTracker（Token 统计 + 成本估算）、CallTrace（Agent 决策链路追踪）、TimingTracker（工具耗时统计）
• RAG 检索：Document + MarkdownLoader + RecursiveCharacterTextSplitter + VectorStore + Embedder + Retriever + MMR 多样性检索 + RetrievalTool（Agent 工具版 RAG）
• 交互式 CLI：cmd/chat REPL —— 多轮对话、工具调用可视化、斜杠命令（/help /usage /clear）
• 统一配置：.env / config.json / 环境变量，一处配置全局生效
• MCP 协议：MCPClient / MCPServer 双向桥接

#V0.2 / V0.3 新增

#架构

                    你的 MoonBit 应用
                          │
                    ┌─────┴─────┐
                    │  moon-agent │  ← 本库（12 个子包，109 个测试）
                    └─────┬─────┘
                          │
        ┌─────┬─────┬─────┼─────┬─────┬─────┬─────┐
        │     │     │     │     │     │     │     │
      core  prompts parsers memory tools chains agents
        │     │     │     │     │     │     │
        └─────┴─────┴─────┴──┬──┴─────┴─────┘
                             │
                    config / observability / mcp / rag
                          │
                    mizchi/llm  ← LLM 客户端底层（Provider、流式、tool_call）
                          │
              OpenAI / Anthropic / ...

#安装

moon add weopqrst/agent@0.5.0

import {
  "mizchi/llm@0.3.1",
  "weopqrst/agent@0.5.0",
}

#配置（v0.9 新增，v0.10 扩展）

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-chat

{
  "api_key": "sk-...",
  "base_url": "https://api.deepseek.com",
  "model": "deepseek-chat",
  "max_tokens": 4096,
  "system_prompt": ""
}

1. ./.env（推荐）
2. ./config.json
3. ../.env（子目录如 cmd/chat 运行时）
4. ../config.json
5. 环境变量回退

#交互式 REPL（cmd/chat）

moon run cmd/chat --target js

=== moon-agent chat v0.5.0 ===
Endpoint: https://api.deepseek.com | Model: deepseek-chat
Type /help for commands, /exit to quit

You: 15 * 23 + 100 等于多少？
Agent:
  [→ calling tool: calculator] input: {"expression":"15*23+100"}
  [← calculator result] 445
445
Tokens: in=128 out=24 total=152 | Est. cost: $0.000

#快速开始（5 分钟）

///|
fn main {
  let api_key = @env.get_env_var("OPENAI_API_KEY")
  match api_key {
    Some(key) => {
      let prompt = @prompts.ChatPromptTemplate::new()
        |> @prompts.ChatPromptTemplate::with_system(
          "You are a helpful assistant.",
        )
        |> @prompts.ChatPromptTemplate::with_user(
          "What is {topic}? Answer in one sentence.",
        )

      let model = @openai.OpenAIProvider::new(key)
      let provider = @llm.BoxedProvider::new(model)
      let chain = @chains.LLMChain::new(provider, prompt)

      let vars : Map[String, String] = Map([])
      vars["topic"] = "MoonBit"
      let answer = chain.invoke(vars)
      println(answer)
    }
    None => println("Please set OPENAI_API_KEY environment variable.")
  }
}

let chain = @chains.LLMChain::new(provider, prompt)
  |> @chains.LLMChain::with_memory(@memory.BufferMemory::new())

chain.invoke({ "input": "我叫张三" })
let answer = chain.invoke({ "input": "我叫什么名字？" })  // → "你叫张三"

///|
let chain = @chains.LLMChain::new(provider, prompt).as_runnable()

///|
let post = @core.RunnableWrapper::new(fn(s : String) -> String {
  "Answer length: " + s.length().to_string()
})

///|
let composed = chain.pipe(post)
// 调用 LLM → 取结果长度，一步完成

let registry = @llm_tools.ToolRegistry::new()
@tools.register_into(registry, MyWeatherTool::new(api_key))

let executor = @agents.AgentExecutor::new(provider, registry)
  |> @agents.AgentExecutor::with_memory(@memory.BufferMemory::new())
  |> @agents.AgentExecutor::with_max_steps(5)

let result = executor.invoke("帮我查一下北京的天气")

let chain = @chains.LLMChain::new(provider, prompt)
chain.invoke_stream(vars, fn(delta) {
  print(delta)  // 实时逐字输出
})

#子包

#测试覆盖

#工具链

moon update               # 更新 registry 索引
moon fmt --check          # 格式检查
moon build --target js    # 构建 JS 目标
moon build --target wasm-gc  # 构建 wasm-gc 目标
moon test --target js     # 运行测试
moon info                 # 更新生成接口文件

#相关链接

• 仓库：https://github.com/mihujiang/MoonBit
• mooncakes：https://mooncakes.io/docs/weopqrst/agent
• LLM 依赖：https://mooncakes.io/docs/mizchi/llm
• 使用指南：USAGE.md（GitHub 友好版本）
• 项目进度：参见仓库 MoonBit/ 目录下的 commit 历史

#English Guide

#Overview

#Features

#Core Abstractions

• Prompt Templates: PromptTemplate ({variable} string interpolation) + ChatPromptTemplate (multi-role ordered messages with insertion-order preservation, supports few-shot)
• Output Parsing: OutputParser trait + JsonOutputParser (tolerates markdown code fences, CRLF-compatible)
• Conversation Memory: BufferMemory (full history), BufferWindowMemory (sliding window), SummaryMemory (periodic LLM summarization for long conversations), BoxedMemory (trait object boxing for any Memory implementation)
• Tool Abstraction: Tool trait (declarative name/description/args_schema/run) + register_into bridge to mizchi/llm's ToolRegistry
• Chain Orchestration: LLMChain — prompt + provider + memory + output_parser, supports streaming
• ReAct Agent: AgentExecutor — wraps run_agent, integrates memory, output_parser, max_steps, streaming
• Composable Units: RunnableWrapper[I,O] — LCEL-style pipeline composition (pipe) / output transformation (map)
• Multi-chain Orchestration: SequentialChain[T] — homogeneous multi-step chains, sequential execution with output passing
• Observability: UsageTracker (token stats + cost), CallTrace (agent decision trail), TimingTracker (tool latency), ErrorLogger (structured error logging)
• RAG Retrieval: Document + MarkdownLoader + RecursiveCharacterTextSplitter + VectorStore + Embedder + Retriever + MMR diversity search
• Interactive CLI: cmd/chat REPL — multi-turn conversations, tool call visualization, slash commands
• Unified Config: .env / config.json / env vars — configure once, run anywhere
• MCP Protocol: MCPClient / MCPServer bidirectional bridge

#V0.2 / V0.3 Additions

#Architecture

                   Your MoonBit Application
                          │
                    ┌─────┴─────┐
                    │  moon-agent │  ← This library (12 sub-packages, 109 tests)
                    └─────┬─────┘
                          │
        ┌─────┬─────┬─────┼─────┬─────┬─────┬─────┐
        │     │     │     │     │     │     │     │
      core  prompts parsers memory tools chains agents
        │     │     │     │     │     │     │
        └─────┴─────┴─────┴──┬──┴─────┴─────┘
                             │
                    config / observability / mcp / rag
                          │
                    mizchi/llm  ← LLM client (Provider, streaming, tool_call)
                          │
              OpenAI / Anthropic / ...

#Installation

moon add weopqrst/agent@0.5.0

import {
  "mizchi/llm@0.3.1",
  "weopqrst/agent@0.5.0",
}

#Interactive REPL (cmd/chat)

moon run cmd/chat --target js

=== moon-agent chat v0.5.0 ===
Endpoint: https://api.deepseek.com | Model: deepseek-chat
Type /help for commands, /exit to quit

You: What is 15 * 23 + 100?
Agent:
  [→ calling tool: calculator] input: {"expression":"15*23+100"}
  [← calculator result] 445
445
Tokens: in=128 out=24 total=152 | Est. cost: $0.000

#Quickstart (5 minutes)

///|
fn main {
  let api_key = @env.get_env_var("OPENAI_API_KEY")
  match api_key {
    Some(key) => {
      let prompt = @prompts.ChatPromptTemplate::new()
        |> @prompts.ChatPromptTemplate::with_system(
          "You are a helpful assistant.",
        )
        |> @prompts.ChatPromptTemplate::with_user(
          "What is {topic}? Answer in one sentence.",
        )

      let model = @openai.OpenAIProvider::new(key)
      let provider = @llm.BoxedProvider::new(model)
      let chain = @chains.LLMChain::new(provider, prompt)

      let vars : Map[String, String] = Map([])
      vars["topic"] = "MoonBit"
      let answer = chain.invoke(vars)
      println(answer)
    }
    None => println("Please set OPENAI_API_KEY environment variable.")
  }
}

let chain = @chains.LLMChain::new(provider, prompt)
  |> @chains.LLMChain::with_memory(@memory.BufferMemory::new())

chain.invoke({ "input": "My name is John" })
let answer = chain.invoke({ "input": "What's my name?" })  // → "Your name is John"

///|
let chain = @chains.LLMChain::new(provider, prompt).as_runnable()

///|
let post = @core.RunnableWrapper::new(fn(s : String) -> String {
  "Answer length: " + s.length().to_string()
})

///|
let composed = chain.pipe(post)
// Calls LLM → gets result length, in one step

let registry = @llm_tools.ToolRegistry::new()
@tools.register_into(registry, MyWeatherTool::new(api_key))

let executor = @agents.AgentExecutor::new(provider, registry)
  |> @agents.AgentExecutor::with_memory(@memory.BufferMemory::new())
  |> @agents.AgentExecutor::with_max_steps(5)

let result = executor.invoke("What's the weather in Beijing?")

let chain = @chains.LLMChain::new(provider, prompt)
chain.invoke_stream(vars, fn(delta) {
  print(delta)  // real-time character-by-character output
})

#Sub-packages

#Test Coverage

#Links

• Repository: https://github.com/mihujiang/MoonBit
• mooncakes: https://mooncakes.io/docs/weopqrst/agent
• LLM dependency: https://mooncakes.io/docs/mizchi/llm
• Usage Guide: USAGE.md
• Project Progress: See commit history under MoonBit/