COORDINATION MECHANICS

STRUCTURED HANDOFF OBJECTS RATHER THAN FULL HISTORIES When one agent passes work to another, it must decide what to send. The lazy approach is to forward the entire conversation history, every message from start to finish. The better approach is to send a structured handoff object. A structured handoff object is a small, organized package of exactly the fields the receiver needs, in a fixed format with named fields, rather than a free-form dump of raw text. Often this is written in a format called JSON, a simple way to write labeled data using curly braces, names, and values. Here is a tiny example of what one looks like. [START OF JSON CODE] // A structured handoff object describing a customer support issue to pass to another agent {"customer_id": "C-20418", "issue_summary": "double-charged for order number 1182", "urgency": "high"} [END OF JSON CODE] Notice how it reads almost like a form that someone filled out. Each label, such as customer_id, has a value. Why is this better than sending the whole history? There are four good reasons. First, efficiency: forty raw messages might be thousands of tokens, while the object is a few dozen tokens. Second, focus: the receiving agent's context contains only what matters, avoiding the clutter problem from Chapter 19. Third, fewer errors: a long transcript contains side comments, corrections, and outdated statements, and the receiver might act on the wrong one. Fourth, safety and privacy: a structured object lets you pass only what the receiver is allowed to see, so sensitive details stay out of agents that do not need them. Designing a handoff object is a real skill. Ask what decisions the receiving agent must make, and then ask what information is absolutely required for each decision. Include the task goal, any key identifiers, relevant findings in short form, constraints such as deadlines or budget, and what output is expected back. Exclude anything the receiver does not need. Where possible, define the object's fields formally with a schema, which is a written description of the expected fields and their types, and have the harness validate each handoff against it. If an object is missing a required field or contains something strange, the harness can reject it before the receiving agent acts on bad information. It is also good practice to treat a handoff object as untrusted input, since the sending agent may have read a poisoned web page, as you learned in Chapter 38. Checking field types, lengths, and allowed values is a cheap and effective defense. One caution: do not over-compress. If the handoff leaves out something essential, such as a promise made to the customer, the receiving agent will contradict it. When in doubt, include a short free-text summary field alongside the structured fields, and offer a way to fetch more detail on request, such as a reference ID that points to the full transcript stored elsewhere.