Memory and multi-agent systems in TypeScript · Chapter 11 of 16

Handoffs

By the end of this chapter you can let agents pass a conversation to each other with tools: describe a transfer as a tool, run the loop that executes it (the active agent changes, the call gets its result), choose what context goes with it, let a specialist hand back, and keep every request one the API accepts. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Many agents
  • 5 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of Memory and multi-agent systems in TypeScript are free. This one comes with the all labs plan.

Why you need this

Chapter 10's front desk routes one message and forgets it. A family's conversation is not one message. Ananya asks about the Jain counter, then, in the same chat, whether the mandap can have diyas. The first belongs to catering, the second to decor, and the third might go back to catering again.

Rekha works that way already: she passes a family to the catering lead with a one-line note ("Sunita ji is Jain, they want a separate counter"), and the catering lead passes them back when the talk turns to flowers. Karan wants the agents to do the same: hand the conversation over, with what the next one needs, and take it back. Sameer asks what it costs to pass ten months of WhatsApp along with every handover.

A router decides once, from outside, for one message. It keeps no idea of who holds the conversation now, so it cannot hand a family back and on again, and it says nothing about what the next agent should be told.

What you build: 5 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    tools.ts: transfer tools

    Instead of a router, Karan wants the front desk to hand a conversation over itself, with a tool. Write and export transferTool(name, description) in tools.ts: it returns an OpenAI tool schema, a function named transfer_to_ and the name, described as Hand the conversation to the, the name, specialist:, a space, the description and a full stop, with one required string parameter, reason. Then transferTools(team): one transfer tool per specialist of the object, in its order (specialists.ts gives chapter 9's four, each with a name and a description).

    Inside if (import.meta.main), offer the four tools to lab-chat at temperature 0, with a system message of your own for a front desk that hands every request on, for Please make sure there is a Jain counter, no onion and no garlic., Can we pay the second instalment by UPI? and Can the mandap have marigold strings and diyas?, and print the tool the model calls, a space and its arguments as the model wrote them.

  2. Task 2

    handoff.ts: a handoff

    Write and export run(text, weddingId) in handoff.ts, async, returning an object with answer, path (who held the conversation, in order) and history (every message). The front desk asks lab-chat at temperature 0, with a system message of your own, the text, and task 1's transfer tools; without a tool call its reply is the answer and the path is just front desk.

    On a transfer call, add the model's message with its tool call to history, then a tool message answering that call's id with a short JSON result of your own; the specialist in the tool's name now holds the conversation. It answers with lab-chat at temperature 0: its system(weddingId), then the history without the handoff (the user messages, and assistant messages without tool calls). Add its answer to history and return it, with the path front desk then the specialist.

    Inside if (import.meta.main), run Is anyone allergic to peanuts? and Who approves a payment above 2 lakh? for WD1057, and print each as the path joined by a space, an arrow made of a hyphen and a greater-than sign and a space, then a colon, a space and the answer.

  3. Task 3

    context.ts: what to hand over

    Write and export whole(specialist, weddingId, history, question) in context.ts: the specialist's system(weddingId) as the system message, every message of history, then the question as a user message. And brief(specialist, weddingId, reason, question): one system message made of its system(weddingId), a blank line, Handed over by the front desk:, a space and the reason, then the question as a user message.

    Inside if (import.meta.main), take WD1042's messages from sessions 12 to 17 as user messages (baraat.ts's asMessage) as the conversation so far, and ask the venue specialist When is the mehndi? both ways with lab-chat at temperature 0 (for brief, the reason is the question), whole first. Print whole history: then the prompt tokens of the reply's usage, prompt tokens:, and the reply; then the same for notes and reason, for example notes and reason: 123 prompt tokens: and the reply.

  4. Task 4

    back.ts: handing back

    Write and export a class Conversation in back.ts: new Conversation(weddingId) starts with an empty history, active 'front desk' and path ['front desk'], as fields; async send(text) adds the text to history as a user message and returns the answer. send asks whoever is active, lab-chat at temperature 0: the front desk with FRONT_DESK, the whole history and the four transfer tools; a specialist with its system(weddingId), the history without the handoffs, and backTool(name), given in the file.

    A reply with a tool call is a handoff: add the model's message and a tool result for its call to history, make the target active (transfer_to_front_desk means the front desk), add it to path and ask again. A reply without one is the answer: add it to history and return it. After four requests for one message, add PLANNER as the answer and return it.

    Inside if (import.meta.main), send Is anyone allergic to peanuts? and Is there parking at Sawai Haveli? in one Conversation for WD1042; print each message, a space and its answer, then the path joined by a space, an arrow made of a hyphen and a greater-than sign and a space.

  5. Task 5 · interview question

    Interview: fix-me.ts, a handoff without its tool result

    FrontDesk in fix-me.ts hands each client message to a specialist and keeps the conversation in history. Run it: the first message is answered, the second stops with a 400 from the API about tool_call_ids.

    Fix send so that every request it makes is one the API accepts, for as many messages as the family sends: each transfer call in history is followed by its tool result before anything else is added. Keep the class's name and export, its methods and what send returns; it uses task 1's transferTools. The check sends several messages, for other weddings.

What you will learn

  • A handoff is a tool: transfer_to_catering, with a reason.
  • The handoff loop: the active agent changes, the call gets its result, the history goes on.
  • What a specialist sees: the conversation, not the handoff.
  • What context to pass: the whole history, or the notes and a reason.
  • Handing back, and the order the API insists on.

More in Many agents

Build "Handoffs" yourself

Baraat Bliss, a Jaipur wedding planner, must remember months of family decisions across many agents. You build its assistant in TypeScript. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Memory and multi-agent systems in TypeScript are free. This one comes with the all labs plan.