moonkoog — an agent framework for MoonBit: prebuilt agents and strategies over the moonstate graph engine, a middleware pipeline, planning, multi-agent composition, and the protocol adapters that put an agent behind MCP, A2A, ACP and the Agent Protocol.
moon add moonbitstack/moonkoogasync test "a first run" {
let provider = @fake.Fake::text("A run is a graph that talks to a model.")
let agent = @moonkoog.create_agent(
provider,
@moonkoog.AgentConfig::new("scripted").with_instructions("Answer in one sentence."),
)
assert_eq(agent.run("What is a run?"), "A run is a graph that talks to a model.")
}| Piece | What it is |
|---|---|
| State | AgentState: the conversation, the run's scratch space, and the calls it has spent. It round-trips through JSON, which is what makes a checkpoint a checkpoint. |
| Strategy | Data: named nodes, what each one does, and the edges between them. single_run, chat, react, answer_only, structured_output and the plan-and-execute loop are presets, and single_run(streaming = true) asks the provider for deltas; a node that decides where to go next returns a Goto. |
| Nodes | Four kinds cover a whole family of behaviours: a request (tools on, off, forced, several candidates, streamed, structured), a tool execution (all, or one), a history compression, and the exit. |
| Middleware | A chain around each model and tool call, taking the rest of the chain as a function. |
| Events | A run reports what it did; observers watch and interceptors rewrite the value in flight. |
async test "a tool" {
let provider = @fake.Fake::new([
@moonmuse.Reply::new(
@moonmuse.Message::new(@moonmuse.Assistant, [
@moonmuse.Part::call("c1", "echo", Json::object(Map([("text", Json::string("hi"))]))),
]),
finish=@moonmuse.Finish::Calls,
),
@moonmuse.Reply::new(@moonmuse.Message::assistant("done")),
])
let tool = @moonkoog.ToolSpec::new(
name="echo",
description="Echo the text back.",
schema=Json::object(Map([("type", Json::string("object"))])),
run=fn(args, _context) {
match args {
Object(fields) =>
match fields.get("text") {
Some(String(text)) => text
_ => ""
}
_ => ""
}
},
)
let agent = @moonkoog.create_agent(
provider,
@moonkoog.AgentConfig::new("scripted").with_tools([tool]),
)
assert_eq(agent.run("echo hi"), "done")
}#koog.tool(description="Multiply two numbers")
fn multiply(a : Double, b : Double) -> Double {
a * b
}
#koog.tool(name="greet", description="Greet someone, loudly when asked")
fn hello(name : String, loud~ : Bool = false) -> String {
if loud { "HELLO, \{name}" } else { "hello, \{name}" }
}rule(name: "tool", command: "moonx moonbitstack/moonkoog/cmd/tool@0.7.0 -C \"$mod_dir\" \"$input\" -o \"$output\"")dev_build(rule: "tool", input: "tools.mbt", output: "tools.g.mbt")
formatter(ignore: [ "tools.g.mbt" ])| Middleware | What it does |
|---|---|
| ModelCallLimit | Refuses a call once the run has spent its budget. |
| ToolCallLimit | Refuses a tool call, in total or for one tool. |
| ModelRetry | Retries the failures the provider calls retryable, with growing delays. |
| ToolRetry | Retries a failed tool call. |
| ModelFallback | Tries the alternatives in order when the primary fails. |
| Summarization | Folds an over-long conversation into a summary before sending it. |
| ContextEditing | Clears older tool results, or drops the oldest turns. |
| TodoList | Gives the model a list it writes its plan into. |
| HumanInTheLoop | Stops the run on a tool call until a person answers. |
| Pii | Scrubs personal data out of what the provider sees. |
| ToolSelection | Advertises only the tools a call needs. |
| ShellTool | Gives the model a shell, rooted where you say. |
| FileSearch | Gives the model a glob and a file reader, rooted where you say. |
async test "a pipeline" {
let provider = @fake.Fake::text("ok")
let agent = @moonkoog.create_agent(
provider,
@moonkoog.AgentConfig::new("scripted")
.with_middleware(@middleware.ModelCallLimit::new(limit=2))
.with_middleware(@middleware.Pii::standard()),
)
assert_eq(agent.run("write to leo@example.com"), "ok")
assert_eq(provider.seen()[0].messages[1].text_content(), "write to [email]")
}async test "a team" {
let first = @fake.Fake::new([
@moonmuse.Reply::new(
@moonmuse.Message::new(@moonmuse.Assistant, [
@moonmuse.Part::call("c1", "handoff", Json::object(Map([("to", Json::string("writer"))]))),
]),
finish=@moonmuse.Finish::Calls,
),
])
let second = @fake.Fake::new([@moonmuse.Reply::new(@moonmuse.Message::assistant("written"))])
let researcher = @moonkoog.create_agent(
first,
@moonkoog.AgentConfig::new("scripted", name="researcher")
.with_tools([@moonkoog.handoff_tool(["writer"])]),
)
let writer = @moonkoog.create_agent(second, @moonkoog.AgentConfig::new("scripted", name="writer"))
let team = @moonkoog.create_agent(
first,
@moonkoog.swarm(@moonkoog.AgentConfig::new("scripted", name="team"), [researcher, writer]),
)
assert_eq(team.run("write a line"), "written")
}| Package | Direction |
|---|---|
| moonkoog/mcp | A server's tools as this agent's tools; this agent as an MCP server (chat). |
| moonkoog/a2a | An agent as an A2A executor; a remote agent as one tool. |
| moonkoog/acp | An agent behind ACP: events become session/update, a stop becomes a refusal. |
| moonkoog/rag | Retrieval as a tool, and retrieval before every call. |
| moonkoog/skills | A skill listing in the instructions, a skill's body loaded on demand. |
| moonkoog/serve | The Agent Protocol's threads and runs, with routes for moonapi. |
fn supervisor(config : AgentConfig, members : Array[Agent], instruction? : String, max_turns? : Int) -> AgentConfigInstall
Download zipmoonkoog — an agent framework for MoonBit: prebuilt agents and strategies over the moonstate graph engine, a middleware pipeline, planning, multi-agent composition, and the protocol adapters that put an agent behind MCP, A2A, ACP and the Agent Protocol.