Reassemble Kimi Streaming Tool Calls Before Execution

A Kimi response can arrive smoothly in the interface while your application reconstructs the wrong tool request. The danger begins when two calls share a stream, an argument string spans several chunks, or a handler treats the first parseable JSON object as permission to execute. A successful HTTP response does not settle any of those questions.

This walkthrough follows one narrow boundary: turning Kimi Chat Completions tool-call fragments into complete, validated application requests. The examples are synthetic protocol fixtures, not captured production responses or a model benchmark. They let you exercise a decoder without an API key, a network connection, or a live business tool.

If you are still choosing credentials and a model route, the Kimi API developer guide provides broader integration context. Here, assume basic text generation already works. The next acceptance target is precise: no tool receives incomplete arguments, and each result remains attached to the call that requested it.

Read the stream as a set of records

The current Kimi tool-call guide explains that multiple calls can appear in a turn and that their fragments carry an index. Initial fragments provide identifying fields; subsequent fragments extend the serialized arguments. Detect calls from delta.tool_calls, rather than waiting for a display-text convention.

Keep these identities separate:

Field or keyDecoder responsibility
Request attemptOwn one isolated accumulator for this response
Choice indexSeparate alternative assistant choices when the route supports them
Tool-call indexSelect the argument buffer within that assistant choice
Tool-call IDAssociate the eventual tool result with its requested call

Never use the function name as a buffer key. The same function can be called twice with different arguments. Never carry the index map into the next model request: index zero in a new response belongs to that new response.

The example below accepts only choice zero. That is an intentional constraint, consistent with the currently documented model configurations fixing n to one in the model parameter reference. An adapter for another configuration should use a map keyed by both choice and call index, not silently combine choices.

Walk through an interleaved fixture

Imagine a read-only inventory assistant requesting two product lookups. This is an illustrative application, and the following fragments are deliberately arranged to challenge its decoder. They are not a claim about a particular server's scheduling pattern.

ArrivalCall indexIdentity or argument fragmentExpected state
A0ID call_a, function lookup, {"sku":"AFirst buffer remains incomplete
B1ID call_b, function lookup, {"sku":"BSecond independent buffer exists
C0-17"}First argument text is now parseable
D1-42"}Second argument text is now parseable
E—Finish reason tool_callsTool intent is established
F—Stream completion markerTransmission is complete

After C, the first argument happens to be valid JSON. The decoder still has work to do. It must complete the response, collect the other call, and apply the execution gate. Parsing progress is useful for diagnostics; it is not a business action.

Notice that arrival order and result order are separate concerns. A slow lookup may finish after another lookup. The application should attach results using the preserved call IDs, rather than zipping a completion-order list with a request-order list. This becomes particularly important when an agent harness runs tools concurrently; see the agent harness integration guide for the surrounding round trip.

Build a decoder that produces a proposal

The following standard-library Python example runs entirely offline. It consumes already decoded SSE payloads plus a literal completion sentinel. It does not implement HTTP, UTF-8 decoding, SSE framing, retries, reasoning-message preservation, or tool execution. Its arbitrary fixture limits are application safeguards, not Moonshot service limits.

import json


def assemble(events):
    calls = {}
    finish = None
    done = False
    for event in events:
        if done:
            raise ValueError("Event after completion")
        if event == "[DONE]":
            done = True
            continue
        for choice in event.get("choices", []):
            if choice.get("index") != 0:
                raise ValueError("This fixture supports choice zero only")
            if choice.get("finish_reason") is not None:
                finish = choice["finish_reason"]
            for part in choice.get("delta", {}).get("tool_calls", []):
                index = part.get("index")
                if type(index) is not int or not 0 <= index < 8:
                    raise ValueError("Invalid call index")
                current = calls.setdefault(index, {
                    "id": None, "type": None, "name": None, "arguments": ""
                })
                function = part.get("function") or {}
                fields = {"id": part.get("id"), "type": part.get("type"),
                          "name": function.get("name")}
                for key, value in fields.items():
                    if value:
                        if not isinstance(value, str):
                            raise ValueError("Invalid metadata")
                        if current[key] not in (None, value):
                            raise ValueError("Conflicting call metadata")
                        current[key] = value
                fragment = function.get("arguments", "")
                if not isinstance(fragment, str):
                    raise ValueError("Arguments must be text fragments")
                current["arguments"] += fragment
                if len(current["arguments"]) > 8000:
                    raise ValueError("Fixture argument limit exceeded")
    if not done or finish != "tool_calls" or not calls:
        raise ValueError("No complete tool-call response")
    proposals = []
    used_ids = set()
    for index in sorted(calls):
        call = calls[index]
        if (not call["id"] or call["id"] in used_ids
                or call["type"] != "function" or call["name"] != "lookup"):
            raise ValueError("Invalid or unsupported call identity")
        args = json.loads(call["arguments"])
        if (not isinstance(args, dict) or set(args) != {"sku"}
                or not isinstance(args["sku"], str) or not args["sku"]):
            raise ValueError("Invalid lookup arguments")
        used_ids.add(call["id"])
        proposals.append({"id": call["id"], "name": call["name"],
                          "arguments": args, "raw": call["arguments"]})
    return proposals


def chunk(index, fragment, first=False):
    part = {"index": index, "function": {"arguments": fragment}}
    if first:
        part.update(id=f"call_{'ab'[index]}", type="function")
        part["function"]["name"] = "lookup"
    return {"choices": [{"index": 0, "delta": {"tool_calls": [part]},
                         "finish_reason": None}]}


fixture = [chunk(0, '{"sku":"A', True),
           chunk(1, '{"sku":"B', True),
           chunk(0, '-17"}'), chunk(1, '-42"}'),
           {"choices": [{"index": 0, "delta": {},
                         "finish_reason": "tool_calls"}]},
           {"choices": [], "usage": {}}, "[DONE]"]
proposals = assemble(fixture)
assert [(p["id"], p["arguments"]["sku"]) for p in proposals] == [
    ("call_a", "A-17"), ("call_b", "B-42")]
try:
    assemble(fixture[:-1])
except ValueError:
    pass
else:
    raise AssertionError("An interrupted stream was accepted")
print("Offline fragment fixtures passed")

The returned objects are proposals. Nothing in this function calls an inventory database. Keeping that boundary visible makes it possible to review the decoded request before introducing any application capability.

The decoder accepts repeated identical metadata but rejects a changed ID, name, or type within one index. It appends every argument fragment, including text that resembles an earlier fragment. Removing repeated strings as a supposed deduplication measure can corrupt valid arguments containing repeated characters or values.

Python's JSON documentation defines json.loads and its decoding errors. JSON parsing establishes syntax, not permission or business validity. This fixture therefore checks a tiny argument shape afterward. A production validator should also enforce the actual SKU format, maximum string length, duplicate-key policy, and the authorization requirements of the real lookup.

Give completion its own gate

The Kimi streaming documentation identifies [DONE] as the transmission-completion marker and warns against treating a finish reason alone as proof of complete delivery. It also documents a possible usage chunk with an empty choices array.

Those details create two distinct decisions. The finish reason tells your application why the assistant stopped generating. The transport completion signal tells the decoder whether the complete response arrived. In this walkthrough, execution requires both a completed transmission and the expected tool-call finish reason.

When using an SDK, determine how its stream abstraction exposes completion and interruptions. The sentinel may be consumed below your application loop. Do not manufacture done=True merely because iteration ended unless that adapter has verified the relevant completion behavior. The offline sentinel makes the required evidence explicit; it is not a suggestion that every SDK yields that literal string.

Also preserve the distinction between text output, reasoning output, and tool arguments. A partial sentence in the UI is not an argument fragment. A reconstructed call should never borrow text from delta.content to repair invalid JSON. If you cannot identify the required fields, stop the tool phase and retain a diagnostic record suitable for reproducing the failure.

Reconstruct the next conversation correctly

Once every proposed call passes validation, execution belongs to your application. The Chat Completions reference requires the tool result's tool_call_id to match the corresponding assistant call ID, and documents preserving the complete assistant message for continuation, including relevant reasoning content.

The small decoder intentionally does not build that full message. A production stream adapter must collect its supported fields separately and reconstruct the assistant turn before appending tool results. Do not replace that turn with a sentence saying that two tools were called. Do not send the local integer index as the tool result's ID.

A useful implementation keeps two representations: the complete assistant message used for protocol continuation, and validated application proposals used for execution. This avoids stripping protocol fields merely to simplify the tool handler. It also prevents a later refactor from serializing a parsed argument dictionary into a field that expects the original argument string.

If the next request fails, that does not prove the preceding tools failed. Record whether execution happened and whether each result is available. Retrying the model request and repeating a business operation are different decisions. The duplicate-request guide offers adjacent application patterns; their identifiers should be scoped to your own operation lifecycle.

Use failures to specify the acceptance boundary

Expand the offline fixture before attaching a live tool. Split the same argument string at every character boundary and confirm that the decoded object stays identical. Include escaped quotes, backslashes, Unicode text, and empty fragments. Add multiple tool fragments in one chunk, because the field is an array and a handler that reads only its first element can lose calls.

Then corrupt one thing at a time. Remove the final sentinel. Change a call ID halfway through. Reuse one ID for two indices. Supply malformed JSON, an unknown function name, or an argument outside the allowed shape. Each case should fail before execution. These tests describe decoder behavior, not Kimi model accuracy.

Finally, test an interrupted response after one call's arguments are complete and the other's are not. That is the case most likely to slip through an eager handler. Keep an execution counter in the harness and assert that it remains zero. An attractive partial result must not change the acceptance rule.

The Chinese LLM API acceptance tests provide a wider evaluation framework. Add this decoder fixture as one specific protocol test inside it, alongside the separate question of whether the model selected the right function and arguments for the user's task.

Locate the fault without guessing from the final answer

When a tool receives the wrong SKU, examine the boundaries in order. First inspect the decoded event payloads for that request attempt. Next compare the per-index accumulated strings with the proposals returned by the validator. Finally inspect the function invocation and its associated result ID. A correct final answer can conceal a decoder defect if the tool or model happened to recover; an incorrect answer can occur even when the decoder performed perfectly.

Keep the evidence small. For an offline reproducer, replace real product identifiers with synthetic values while preserving the original split positions and ordering. Retain whether fields were absent, null, or empty, because collapsing those distinctions can erase the condition that caused the failure. Never include credentials in the fixture. When the arguments contain private material, create a minimal equivalent case instead of distributing the original stream.

Do not compare raw chunk counts across routes as a correctness test. Different fragmentation can produce the same complete call. Compare the ordered argument text within each call, its identity, the completed assistant message, and the validated proposal. Conversely, identical visible text says little about whether the hidden tool fields survived a conversion layer.

If the same fixture passes in a standalone adapter but fails inside WorkBuddy, compare the client integration boundary before changing the model. The WorkBuddy custom-model troubleshooting guide helps place that investigation among endpoint, authentication, and protocol checks. Preserve the failing event sequence while narrowing the adapter difference.

For a repeatable release check, save the fixture, decoder version, expected proposal, and expected execution count together. This creates a precise regression artifact: a future change either preserves the contract or produces a specific discrepancy. The artifact is useful even when a provider cannot reproduce the original network timing, because the application bug can be evaluated from a deterministic event sequence.

Move the proven decoder into a small route pilot

For a live pilot, use a non-sensitive lookup and configure the base URL, credential, and model identifier from the account's current documentation. No live API request was executed for this article. Keep the same offline regression fixtures when changing an SDK, model configuration, or route.

Before evaluating Treerouter, confirm that your account and selected route support the required Kimi streaming tool-call fields, completion behavior, and conversation continuation. Availability of these advanced features is unverified here. A successful plain chat call is the first connectivity check; a complete harmless tool round trip is the next proof you need.

If that pilot exposes a mismatch, bring the smallest failing fixture and the expected reconstructed call to the integration review. This gives both sides something concrete to inspect, while keeping API keys and business data out of the report. Then register or configure the verified route and repeat one successful model call followed by the full tool cycle.

Learn more: Treerouter.