moonkoog

    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.

    koog
    agent
    llm
    tool-calling
    agent-framework
    state-graph
    workflow
    middleware
    multi-agent
    handoff
    supervisor
    swarm
    planner
    goap
    plan-and-execute
    react
    rag
    retrieval
    mcp
    model-context-protocol
    a2a
    agent-to-agent
    acp
    agent-client-protocol
    agent-protocol
    opentelemetry
    otel
    gen-ai
    observability
    tracing
    checkpoint
    human-in-the-loop
    skills
    moonbit
    Download zip
    Version
    0.7.0
    License
    Apache-2.0
    Last updated
    2 days ago
    Downloads
    93

    #moonkoog

    An agent framework for MoonBit: a run is a state graph.

    Check and Test License

    An agent is a loop: ask a model, run what it asked for, feed the result back, ask again. What makes an agent usable in a real program is everything around that loop — the state it keeps, the place it stops, the way it is retried, the budget it may spend, and how it is reached from outside.

    moonkoog puts all of that on one engine. A run is a graph whose nodes talk to a model; the graph checkpoints, resumes, interrupts, and nests, so an agent, a planner, a team and a protocol server are the same machinery configured differently rather than four systems that have to agree.

    moon add moonbitstack/moonkoog

    #A first run

    async 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.")
    }

    create_agent takes a provider — anything implementing Provider — and a config. The config says which model, what the instructions are, which tools may be called, which strategy the run follows, what it may spend, and what middleware wraps its calls.

    #The model

    PieceWhat it is
    StateAgentState: 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.
    StrategyData: 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.
    NodesFour 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.
    MiddlewareA chain around each model and tool call, taking the rest of the chain as a function.
    EventsA run reports what it did; observers watch and interceptors rewrite the value in flight.

    A strategy is data, so a composed strategy — a plan, a team — compiles against the same runtime and gets the same checkpointing, budgets and middleware for free.

    #Tools

    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")
    }

    A tool's body receives the arguments and the run's context, which is what lets a tool keep state: the todo list, the approval gate and the retrieval tool all use it.

    #Tools as annotations

    A tool is usually a function the model may call. #koog.tool makes it one: each parameter becomes a property of the tool's input schema, typed from its MoonBit type, and the ones with a default or an optional type are not required. A parameter whose type is RunContext receives the run's context and stays out of the schema. A String goes back to the model as it is; any other result goes back as JSON.

    #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}" }
    }

    The generator writes tools(), which an agent takes as it is: AgentConfig::new("assistant").with_tools(tools()). It shares the schema derivation with moonmcp's #mcp.tool, so a function described to a model and to an MCP client is described the same way. Wire it into the build once. In moon.mod:

    rule(name: "tool", command: "moonx moonbitstack/moonkoog/cmd/tool@0.7.0 -C \"$mod_dir\" \"$input\" -o \"$output\"")

    and in the moon.pkg of the package holding the functions:

    dev_build(rule: "tool", input: "tools.mbt", output: "tools.g.mbt") formatter(ignore: [ "tools.g.mbt" ])

    The state of a custom graph is annotated the same way, with moonstate's #state.patch. src/examples/07-annotated-tools runs two annotated tools through a scripted model.

    #Middleware

    Thirteen middlewares ship with the module. Each is a type with a new and no hidden global:

    MiddlewareWhat it does
    ModelCallLimitRefuses a call once the run has spent its budget.
    ToolCallLimitRefuses a tool call, in total or for one tool.
    ModelRetryRetries the failures the provider calls retryable, with growing delays.
    ToolRetryRetries a failed tool call.
    ModelFallbackTries the alternatives in order when the primary fails.
    SummarizationFolds an over-long conversation into a summary before sending it.
    ContextEditingClears older tool results, or drops the oldest turns.
    TodoListGives the model a list it writes its plan into.
    HumanInTheLoopStops the run on a tool call until a person answers.
    PiiScrubs personal data out of what the provider sees.
    ToolSelectionAdvertises only the tools a call needs.
    ShellToolGives the model a shell, rooted where you say.
    FileSearchGives 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]")
    }

    #Planning and teams

    plan_and_execute is a strategy: a planner node writes the steps, the model works through them with its tools, and a step whose tool call failed sends the run back to the planner. Goal-oriented planning is a search over world states — GoapAction, GoapGoal, search — independent of any model, for the steps that can be planned without one.

    An agent can also be handed to another one as a tool: as_tool wraps it in a ToolSpec whose argument is a message and whose result is the other agent's answer, which is how a lead agent delegates a sub-task without a second orchestration layer.

    A team is a strategy whose nodes are agents. Each member is a nested graph over the same conversation, so a member sees what the ones before it said; a handover is a tool that records where the conversation should go, and the team's router follows. swarm follows the members' own handovers; supervisor asks its model which member acts next.

    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")
    }

    #Protocols

    Six adapters put an agent behind something else. Each is a translation of events, tools and interrupts the agent already has; none keeps a second copy of that state. All three agent protocols are checked against their official SDKs in another process — the agent as an MCP client, as an A2A server and client, and on ACP over stdio.

    PackageDirection
    moonkoog/mcpA server's tools as this agent's tools; this agent as an MCP server (chat).
    moonkoog/a2aAn agent as an A2A executor; a remote agent as one tool.
    moonkoog/acpAn agent behind ACP: events become session/update, a stop becomes a refusal.
    moonkoog/ragRetrieval as a tool, and retrieval before every call.
    moonkoog/skillsA skill listing in the instructions, a skill's body loaded on demand.
    moonkoog/serveThe Agent Protocol's threads and runs, with routes for moonapi.

    #Observability

    moonkoog/otel turns a run into the two signals a GenAI trace is made of: an invoke_agent span with the tokens it spent, and an execute_tool span per call, with the attribute names from the semantic conventions. The tracer is yours; the library never reads a clock of its own.

    #Consistency

    The test suite runs on all four targets, and every case below passes.

    • The strategy graph, the presets, history compression, agent-as-tool, the middleware, the event stream and a checkpoint each have a case transcribed from the suite of the agent framework this design is measured against. The cases keep the upstream names, so a reader can compare them one by one; the ones this design has no counterpart for are listed in the delivery note.
    • The same graph, run by that other engine with the same scripted answers, produces the same steps node by node. The sequence is generated by a script and replayed as a test, so a change on either side shows up as a difference rather than as a test that keeps passing.
    • MCP, A2A and ACP are checked against their official SDKs in a separate process: the agent calls an MCP server's tools, answers an A2A client, delegates to an A2A server, and is driven by an ACP client over stdio.
    • Checkpoints are checked against a real PostgreSQL: one process stops for approval, another one resumes the thread and runs the approved tool. A thread can be rewound to an earlier checkpoint, and a conversation recorded under a wider tool set is rewritten, not rejected, when the agent that resumes it no longer offers those tools.
    • Nothing is checked against a live model provider: a key and a network are the caller's, and the scripted provider is what a run's own tests use.

    #License

    Apache-2.0.

    Agent

    The agent: what a run is, what it is configured with, and how it is started.

    AgentConfig

    The agent: what a run is, what it is configured with, and how it is started.

    AgentError

    The agent: what a run is, what it is configured with, and how it is started.

    AgentState

    The agent: what a run is, what it is configured with, and how it is started.

    ContextEditing

    The built-in middleware. Each one is a type here and a value with new on it.

    EditingStrategy

    The built-in middleware. Each one is a type here and a value with new on it.

    Event

    The agent: what a run is, what it is configured with, and how it is started.

    EventHandler

    The agent: what a run is, what it is configured with, and how it is started.

    FileSearch

    The built-in middleware. Each one is a type here and a value with new on it.

    GoapAction

    Planning: the goal-oriented search, and the plan-and-execute strategy.

    GoapGoal

    Planning: the goal-oriented search, and the plan-and-execute strategy.

    HumanInTheLoop

    The built-in middleware. Each one is a type here and a value with new on it.

    Limits

    The agent: what a run is, what it is configured with, and how it is started.

    Middleware

    The agent: what a run is, what it is configured with, and how it is started.

    MissingTools

    The agent: what a run is, what it is configured with, and how it is started.

    ModelCallLimit

    The built-in middleware. Each one is a type here and a value with new on it.

    ModelFallback

    The built-in middleware. Each one is a type here and a value with new on it.

    ModelOutcome

    The agent: what a run is, what it is configured with, and how it is started.

    ModelRetry

    The built-in middleware. Each one is a type here and a value with new on it.

    NodeKind

    The agent: what a run is, what it is configured with, and how it is started.

    Options

    The agent: what a run is, what it is configured with, and how it is started.

    Pii

    The built-in middleware. Each one is a type here and a value with new on it.

    PiiRule

    The built-in middleware. Each one is a type here and a value with new on it.

    RequestMode

    The agent: what a run is, what it is configured with, and how it is started.

    RunContext

    The agent: what a run is, what it is configured with, and how it is started.

    ShellTool

    The built-in middleware. Each one is a type here and a value with new on it.

    Strategy

    The agent: what a run is, what it is configured with, and how it is started.

    Structured

    The agent: what a run is, what it is configured with, and how it is started.

    Summarization

    The built-in middleware. Each one is a type here and a value with new on it.

    TodoList

    The built-in middleware. Each one is a type here and a value with new on it.

    ToolCallLimit

    The built-in middleware. Each one is a type here and a value with new on it.

    ToolOutcome

    The agent: what a run is, what it is configured with, and how it is started.

    ToolRetry

    The built-in middleware. Each one is a type here and a value with new on it.

    ToolSelection

    The built-in middleware. Each one is a type here and a value with new on it.

    ToolSpec

    The agent: what a run is, what it is configured with, and how it is started.

    Tools

    The agent: what a run is, what it is configured with, and how it is started.

    Update

    The agent: what a run is, what it is configured with, and how it is started.

    answer_only

    fn answer_only(name? : String) ->
    Strategy

    A strategy with a single model call: no tools, one answer. Useful as a judge, a classifier or the planner half of a plan-and-execute run.

    as_tool

    fn as_tool(agent :
    Agent
    , name? : String, description? : String) ->
    ToolSpec

    An agent as a tool another agent can call.

    The model sees one tool whose argument is a message and whose result is the other agent's answer, so a lead agent delegates a sub-task by asking for it. The called agent keeps its own strategy, its own tools and its own model; only the question and the answer cross the line. A run that fails comes back to the caller as text it can act on rather than as an exception, because a tool that raises leaves the model with nothing to recover from.

    calculator

    A tool that does arithmetic on two numbers.

    Models are unreliable at arithmetic and good at deciding that arithmetic is needed, which is exactly the division of labour a tool exists for. Division by zero is refused rather than answered with infinity: a wrong number that looks like a number is worse than an error.

    chat

    The chat loop: the model must call a tool rather than answer in prose, and the run ends when it calls the exit tool. exit_tool is what the run watches for.

    create_agent

    Build an agent. The strategy defaults to [single_run]; tools from the config are installed first, then whatever the middleware contributes, so a middleware can replace a default tool of the same name.

    default_limits

    The default caps.

    default_options

    Nothing pinned: the provider's defaults, tools left to the model's judgement, no stop sequences.

    describe

    A failure as a line of text, for hooks that only report.

    handoff_tool

    fn handoff_tool(targets : Array[String]) ->
    ToolSpec

    A tool that hands the conversation to another peer of the team.

    The tool records the destination in the run's state rather than jumping: the peer's own graph has no node for an agent outside it, so it ends its turn and the team's router reads the marker. That is what makes a handover work across a graph boundary, and it is why a peer does not need to know how the team is wired.

    plan_and_execute

    Turn the config into a plan-and-execute agent: a planner writes the steps, the model works through them with its tools, and a failed step sends the run back to the planner.

    The loop lives in the graph, so a run that stops — for approval, for a checkpoint, for a cap — resumes at the step it was on with the plan it had.

    react

    fn react(reasoning_prompt? : String, interval? : Int) ->
    Strategy

    Reason-and-act: after each round of tools the model is asked to think about what it learned, without tools in reach, before it acts again. interval spaces the thinking out, so a long loop does not pay for a reasoning call on every round.

    The least-cost sequence of action names that reaches goal from start, or None when no sequence does.

    The search is A* over the state space: the frontier is ordered by the cost so far plus the goal's estimate, and a state reached more cheaply replaces the one recorded. A state is keyed by the value itself, so the state type has to be comparable — for a world state that means a record of flags or a small map, not a mutable object.

    single_run

    fn single_run(streaming? : Bool) ->
    Strategy

    The one-run loop: ask, run whatever was asked for, ask again until the model answers in prose. This is the strategy an agent gets when nothing else is asked for.

    streaming asks each model call to report its deltas as they arrive (on_llm_streaming_frame), instead of handing back one finished reply.

    structured_output

    fn structured_output(name? : String) ->
    Strategy

    Tools first, then one answer that has to fit the schema the agent was configured with (AgentConfig::with_structured). The model may call tools for as many rounds as it needs; the prose answer that would have ended a single_run is instead sent to a final request in structured mode, whose answer is the JSON object the run returns.

    Without a schema on the config the final request returns an empty answer, which is why the strategy is only worth choosing together with with_structured.

    supervisor

    A team with a lead that decides which peer acts next.

    The router asks the model — the agent's own model, with the conversation in hand — which peer should act, and stops when it answers FINISH. A supervisor costs one model call per turn and buys a plan nobody has to write; a swarm costs nothing and only goes where the members send it.

    swarm

    A team whose members hand the conversation to each other through the handoff tool.

    Each peer runs as a nested graph over the same conversation, so a peer sees what the ones before it said. The run starts with the first peer and ends when a peer answers without handing over. Nothing decides the order but the members themselves, which is what makes a swarm different from a supervisor.

    tool_result

    fn[T :
    ToJson
    ] tool_result(value : T) -> String

    What a tool hands back to the model, from any value its function returns: the JSON text of the value. A String is passed through as it is by the code #tool generates, so a tool that answers in prose is not quoted.

    Source Files