SendMessage

Your planner sends code-reviewer two messages through the same method. The first asks which languages it reviews, and the answer arrives at once as a message. The second carries a diff, and the answer is a task with an id, a state, and later an artifact.

When you finish this section, you can build a SendMessage request and act on whichever shape comes back.

The request and its configuration

SendMessageRequest: a message, as Message defines it, an optional configuration, and metadata. The configuration has four fields:

• acceptedOutputModes: the media types the client accepts.
• taskPushNotificationConfig: a webhook, as push notification configs explains.
• historyLength: how much history the returned task carries.
• returnImmediately: whether the server answers before the task settles.

A send blocks unless returnImmediately is true:

In 03-blocking-task.http, one SendMessage with no configuration gets task 3d8f7801 in TASK_STATE_COMPLETED, with every artifact. The client never sees TASK_STATE_SUBMITTED or TASK_STATE_WORKING. The specification sets no time limit, and a client that times out never learns the task id.

One sentence of the specification says the opposite (conflict D2): the operation must return at once with either task information or a response message. The proto makes false the default, and the proto is normative. The kit and the reference SDK block.

The SDKs disagree on whether historyLength in the configuration trims the returned task:

Message or Task

SendMessage returns a SendMessageResponse whose payload is a oneof of two members, task and message. The agent decides, and the specification gives it no rule. The agent is allowed to create a new Task and process the message asynchronously. It is also allowed to return a direct Message for a simple exchange.

In the kit, test-runner and deployer create a task for every message. code-reviewer answers with a message when the request has no text/x-diff part and its text ends with a question mark (the kit's agent code). Once a task exists, the choice is over: from then on, the agent returns only Task objects in response to messages.

A message is the whole answer, with no id to poll, cancel, or subscribe to. It carries a contextId, so keep it for a follow-up. A task is a handle on work that can outlive the call. Figure 4.1 puts the two answers from code-reviewer side by side. SendStreamingMessage makes the same choice in its first event, as SendStreamingMessage and SubscribeToTask shows.

Returning at once and polling with GetTask

returnImmediately: a boolean in SendMessageConfiguration that asks the server to answer as soon as the task exists. The operation must return right after it creates the task, even while the work goes on. The flag has no effect on a direct Message reply, on streaming operations, or on push notification configs.

Polling: reading a task with GetTask until its state tells you to stop. In 04-polling.http the kit sends with returnImmediately, then polls task d0c28826 twice with historyLength 0:

    "configuration": {
      "returnImmediately": true
    }
…
        "state": "TASK_STATE_SUBMITTED",
…
  "method": "GetTask",
  "params": {
    "id": "d0c28826-28b8-4b15-8b53-4e01ae7a5a3c",
    "historyLength": 0
  }
…
      "state": "TASK_STATE_WORKING",
…
            "text": "collected 12 items\n"
…
      "state": "TASK_STATE_COMPLETED",

The send returns TASK_STATE_SUBMITTED, while the specification's examples name TASK_STATE_WORKING and TASK_STATE_INPUT_REQUIRED, so switch on the state you get. The first poll finds TASK_STATE_WORKING and one log part. The second finds TASK_STATE_COMPLETED with every artifact. Figure 4.2 sets the blocking call beside the immediate return and its two polls.

Dispatch on the result

The kit's planner tests which member is present before it touches either:

        while True:
            if "error" in reply:
                self.note(f"  error {reply['error']['code']}: {reply['error']['message']}")
                return None
            result = reply["result"]
            if "message" in result:
                self.note("  direct reply, no task to follow")
                return result["message"]
            task = result["task"] if "task" in result else result
            state = task["status"]["state"]
            self.note(f"  task {task['id'][:8]} is {state}")
            if state in TERMINAL:
                return task

The planner checks error first, because JSON-RPC errors arrive inside an HTTP 200 response. Then it checks message and stops. Only then does it branch on the task's state, as Task, TaskStatus, and TaskState defines it. A client walks through the rest of this loop.