Guide
From one call to a team behind a protocol. Every block on this page is a test in the repository, and every output is what it printed.
#1. Install
moon add moonbitstack/moonkoog
A run needs a provider; the examples use moonmuse/fake, a scripted provider that answers from a list, so nothing on this page needs a key.
#2. A first agent
An agent is a config and a provider. The config says which model, what the instructions are, which tools may be called, and which strategy the run follows — the default is the single-run loop.
async test "a first agent" {
let provider = @fake.Fake::text("A state graph is a program made of nodes.")
let agent = @moonkoog.create_agent(
provider,
@moonkoog.AgentConfig::new("scripted").with_instructions("Answer in one sentence."),
)
assert_eq(agent.run("What is a state graph?"), "A state graph is a program made of nodes.")
assert_eq(provider.seen()[0].messages[0].role, @moonmuse.System)
}
#3. Tools
A tool is a descriptor and a body. The body gets the arguments and the run's context, and returns the text the model reads.
fn shout() -> @moonkoog.ToolSpec {
@moonkoog.ToolSpec::new(
name="shout",
description="Repeat the text in capitals.",
schema=Json::object(
Map([
("type", Json::string("object")),
("properties", Json::object(Map([
("text", Json::object(Map([("type", Json::string("string"))]))),
]))),
]),
),
run=fn(args, _context) {
match args {
Object(fields) =>
match fields.get("text") {
Some(String(text)) => text.to_upper()
_ => "error: no text"
}
_ => "error: no text"
}
},
)
}
async test "a tool call" {
let provider = @fake.Fake::new([
@moonmuse.Reply::new(
@moonmuse.Message::new(@moonmuse.Assistant, [
@moonmuse.Part::call("c1", "shout", Json::object(Map([("text", Json::string("hello"))]))),
]),
finish=@moonmuse.Finish::Calls,
),
@moonmuse.Reply::new(@moonmuse.Message::assistant("HELLO")),
])
let agent = @moonkoog.create_agent(
provider,
@moonkoog.AgentConfig::new("scripted").with_tools([shout()]),
)
assert_eq(agent.run("shout hello"), "HELLO")
}
#4. The pipeline
Middleware wraps the model call or the tool call. The ones here cap the calls a run may spend and scrub an address before it leaves the process.
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]")
}
#5. Structured answers
When the answer has to fit a schema, give the agent one and run the preset that asks for it: tools work as usual, and the last request is held to the schema. A reply that does not fit is sent back with the failure, twice, before the run gives up.
async test "a structured answer" {
let schema = Json::object(Map([
("type", Json::string("object")),
("properties", Json::object(Map([
("slots", Json::object(Map([("type", Json::string("number"))]))),
]))),
]))
let provider = @fake.Fake::new([
@moonmuse.Reply::new(@moonmuse.Message::assistant("{\"slots\": 3}")),
])
let agent = @moonkoog.create_agent(
provider,
@moonkoog.AgentConfig::new("scripted")
.with_structured(@moonkoog.Structured::new("meeting", schema))
.with_strategy(@moonkoog.structured_output()),
)
assert_eq(agent.run("three of us").contains("\"slots\""), true)
}
#6. Checkpoints and resumption
A thread is a name. Pass a saver and the run checkpoints each node boundary under that name; pass the same name again and the run continues from what it had, budgets included. A finished thread starts a new turn, and rewind puts its head back on an earlier checkpoint when a decision has to be taken again. A thread outlives the configuration that wrote it, so an agent built without a tool can still read the conversation that used it: with_missing_tools(Convert) turns those calls and results into text before the request leaves.
async test "a checkpointed thread" {
let provider = @fake.Fake::text("remembered")
let saver = @moonstate.MemorySaver::new()
let agent = @moonkoog.create_agent(provider, @moonkoog.AgentConfig::new("scripted"), saver~)
assert_eq(agent.run("first", thread="t1"), "remembered")
let snapshot = agent.state("t1").unwrap()
assert_eq(snapshot.state.text(), "remembered")
}
async test "a thread taken back" {
let provider = @fake.Fake::new([
@moonmuse.Reply::new(@moonmuse.Message::assistant("first")),
@moonmuse.Reply::new(@moonmuse.Message::assistant("again")),
])
let saver = @moonstate.MemorySaver::new()
let agent = @moonkoog.create_agent(provider, @moonkoog.AgentConfig::new("scripted"), saver~)
let _ = agent.run("first", thread="t2")
let mut point = ""
for snapshot in agent.history("t2") {
if point == "" && snapshot.next.contains("model") {
point = snapshot.id
}
}
agent.rewind("t2", point)
assert_eq(agent.continue_run("t2"), "again")
}
#7. Planning
Plan-and-execute writes the steps first, then works through them. A step whose tool call failed sends the run back to the planner.
async test "a plan" {
let provider = @fake.Fake::new([
@moonmuse.Reply::new(@moonmuse.Message::assistant("[\"look it up\", \"report it\"]")),
@moonmuse.Reply::new(@moonmuse.Message::assistant("six times seven is forty-two")),
@moonmuse.Reply::new(@moonmuse.Message::assistant("Reported: forty-two.")),
])
let agent = @moonkoog.create_agent(
provider,
@moonkoog.plan_and_execute(@moonkoog.AgentConfig::new("scripted")),
)
assert_eq(agent.run("Work out six times seven."), "Reported: forty-two.")
assert_eq(provider.hits(), 3)
}
#8. Teams
A team is a strategy whose nodes are agents. A member hands the conversation on with the handoff tool; the router follows the marker it leaves.
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")
}
One member can also be handed to another as a tool, which needs no team at all: the lead agent asks for it, and the answer comes back as a tool result.
async test "an agent as a tool" {
let helper = @moonkoog.create_agent(
@fake.Fake::text("the helper's answer"),
@moonkoog.AgentConfig::new("scripted", name="helper"),
)
let lead = @moonkoog.create_agent(
@fake.Fake::new([
@moonmuse.Reply::new(
@moonmuse.Message::new(@moonmuse.Assistant, [
@moonmuse.Part::call("c1", "helper", Json::object(Map([("message", Json::string("help"))]))),
]),
finish=@moonmuse.Finish::Calls,
),
@moonmuse.Reply::new(@moonmuse.Message::assistant("done")),
]),
@moonkoog.AgentConfig::new("scripted", name="lead")
.with_tools([@moonkoog.as_tool(helper)]),
)
assert_eq(lead.run("delegate this"), "done")
}
#9. Behind a protocol
The adapters are translations. This one serves an agent over MCP and calls it back over the in-memory transport, which is the same code path a stdio server takes.
async test "an agent behind MCP" {
let served = @moonkoog.create_agent(
@fake.Fake::text("from the served agent"),
@moonkoog.AgentConfig::new("scripted", name="helper"),
)
let client = @client.Client::connect(@client.Memory::new(@mcp.serve(served)))
let specs = @mcp.tools(client)
assert_eq(specs.length(), 1)
assert_eq(specs[0].tool.name, "chat")
}
#10. Traces
The otel package turns a run into two spans — the agent and each tool call — with the attribute names a GenAI collector expects.
async test "a trace" {
let sink = @trace.Recorder::new()
let tracer = @trace.Tracer::new(
rand=n => Bytes::make(n, b'\x07'),
sink~,
sampler=@trace.always,
)
let otel = @otel.Otel::new(tracer~, now=fn() { 0L })
let agent = @moonkoog.create_agent(
@fake.Fake::text("traced"),
@moonkoog.AgentConfig::new("scripted").with_events(otel.install(@moonkoog.EventHandler::new())),
)
assert_eq(agent.run("hello"), "traced")
assert_eq(sink.spans()[0].name, "invoke_agent agent")
}
#Where to read next
The API reference has every public item. The tasks a run can be interrupted on, the middleware's contracts, and the way a strategy is data are all in the doc comments there.