Agentic AI Applications

Agent Handoff Schema Design for Multi-Agent Systems

24 MIN READ

An agent handoff occurs when one agent passes a task to another, along with the context the receiving agent needs to continue the work. In multi-agent systems, where several AI agents handle different parts of a larger task, these handoffs are a common source of lost context and broken workflows.

This guide defines three schemas that help make those handoffs reliable. The first is the handoff payload, which carries context from one agent to another. The second is the tool-call record, which captures how agents interact with tools and services. The third is the shared state document, which gives agents access to information they need to coordinate their work. 

For each schema, we’ll cover its fields, versioning rules, and read and write boundaries. Guides on building multi-agent AI workflows and optimizing multi-agent AI systems often discuss passing task context between agents. This post gets specific about what that context contains and how to structure it.

All three schemas use JSON documents. In Couchbase, they belong in the same governed data layer as agent memory, the Agent Catalog, and traces. Consistent versioning and explicit access rules help ensure that agents can share the information they need without losing control over how it is read and updated.

What is an agent handoff?

An agent handoff passes ownership of a task from a sending agent to a receiving agent, along with the context needed to finish it. Every handoff answers three questions:

  1. What was done? The steps the sending agent completed.
  2. What’s left? The goal the receiving agent now owns.
  3. What can the receiver assume is true? The facts, inputs, and constraints the receiver doesn’t need to recheck.

How is a handoff different from a tool call or a shared state read?

Agents coordinate in three distinct ways:

  • Handoff – An agent passes ownership of a task to another agent.
  • Tool call – An agent invokes a capability, such as a database query or an API, and gets a result back. Ownership stays with the calling agent.
  • Shared state read – An agent looks up a fact that another agent wrote.

Mixing up these three interactions is a common source of coordination bugs. Coordination problems show up in research, too: inter-agent misalignment is one of three failure categories in MAST, a taxonomy of multi-agent system failures. Calling another agent as a tool when you meant to hand off leaves ownership with the caller, which still treats the task as its job. Some frameworks, such as the OpenAI Agents SDK, present handoffs to the model as tool calls, and that’s fine as long as ownership transfers. A state write disguised as a handoff reaches only the receiving agent. No other agent sees the fact, and it’s archived with the handoff when the task ends.

What objects do multi-agent systems write?

Most multi-agent systems write these three kinds of objects, whether or not they define them explicitly:

Written byRead byLifetimeOwner
Handoff payloadThe sending agentThe receiving agent, onceOne task; archived after completionThe sending agent until accepted, then the receiver
Tool-call recordThe agent framework, once per callDebugging, audit, and cost toolsKept for the audit window; append-onlyThe calling agent
Shared state documentOne owning agent per sectionSeveral agentsLong-lived; outlives any single runEach section’s owning agent

Two design principles apply to all three schemas:

  1. Each object gets one writer role and an explicit reader list. If multiple roles can write to the same field, conflicting updates can occur unless the system defines how it resolves those conflicts.
  2. Every object carries schema_version and trace_id. A trace ID is a shared identifier for one end-to-end run across agents. Without both fields, debugging a multi-agent failure is guesswork.

The examples below are application-level patterns, not formats Couchbase defines. Adapt the field names to your framework.

Schema 1: What should an agent handoff payload contain?

A handoff payload is a JSON document. The sending agent writes it, the receiving agent reads it once, and the system archives it after the task completes. The receiver records that it accepted the handoff outside the payload, for example in its section of the shared state document, so the payload keeps a single writer. Here’s an example for a customer support system where a triage agent hands a refund decision to a refund agent:

What each field is for:

  • handoff_id, schema_version, trace_id – Identifies the handoff, the format version it follows, and the run it belongs to. The handoff_id also works as an idempotency key, so a handoff delivered twice gets processed once.
  • from_agent, to_agent, created_at – Records who passed ownership to whom, and when.
  • task – A single-sentence goal. If the goal needs “and,” split it into two handoffs.
  • inputs – Document keys, not copied data. The receiver reads the current version from the database.
  • context_summary – What was done and what was ruled out, so the receiver doesn’t repeat it.
  • constraints – The deadline, the budget, and any tools the receiver must not call.
  • success_criteria – How the receiver knows the task is done.
  • return_to – The agent or queue that receives the result.

Three design rules keep payloads reliable:

  1. Use references, not copies. A copy goes stale as soon as the source document changes. To let the receiving agent check whether a document changed after the handoff, store the document’s compare-and-swap (CAS) value next to its key. Couchbase updates the CAS value on every write, so a different value means the document has changed.
  2. Give every needed fact a field. Don’t make the receiver parse a free-text blob.
  3. Make the payload readable on its own. The receiver should never need the sender’s chat history.

These rules prevent dropped handoff context, which is one of the multi-agent failures you can read more about in What Are My AI Agents Doing? How to Gain Insight and Control.

Schema 2: What should a tool-call record contain?

A tool-call record is an append-only document. It records that an agent called a tool, the arguments passed, the outcome, and the associated cost. Your agent framework writes the record because the Couchbase Agent Catalog doesn’t execute tools itself. The catalog holds the tool’s definition, and it manages and audits activity such as tool calls, tool results, agent handoffs, and LLM generations. If you use Agent Tracer, it already logs tool calls and tool results, linked by tool_call_id, and its ToolInvocations view pairs them for SQL++ queries. A separate tool-call record makes sense when you want your own fields on every call, such as cost, or when your framework doesn’t log through Agent Tracer.

What each field is for:

  • call_id, schema_version, trace_id, agent – Identify the call, schema version, associated run, and agent that made the call.
  • tool_name and catalog_id – Identify the tool invoked and the specific catalog version used. The Agent Catalog versions tools and prompts through Git and catalog.find() accepts a catalog_id to resolve a specific version.
  • args – Store arguments as structured JSON rather than a formatted prompt string. This makes calls easier to replay, inspect, and compare.
  • started_at, ended_at, latency_ms – Record execution timing for performance analysis.
  • status – Records the outcome of the call. If it fails, include error_type and error_message. Omit these fields on success.
  • result or result_ref – Store small results directly in the document and reference a separate document for larger results.
  • llm_tokens and cost_usd – Record the tokens consumed and model cost of the model turn that requested the call, allowing you to calculate costs across an entire run. If one turn requests several calls, record that cost on only one of them so run totals don’t double-count.

Typed tool models

The Agent Catalog documentation highly recommends declaring every tool’s input and output models with Pydantic or dataclasses. Typed models catch tool schema mismatches, where an agent sends arguments the tool doesn’t expect:

Records are append-only. A retry writes a new record with the same trace_id and never updates the old one, so the attempt history stays intact.

Schema 3: How do you structure shared state for multiple agents?

A shared state document is a durable JSON document that holds facts needed by several agents. It’s written under explicit ownership rules. Structure it as sections, one per owning agent, rather than a flat set of keys every agent can edit.

There’s no revision field in this example because Couchbase tracks one for you. Every document has a CAS value in its metadata that changes on each write. A write that supplies an outdated CAS value fails instead of overwriting newer data.

Three concurrency rules keep shared state consistent:

  1. One writer per section. Other agents read a section but never write it. Write a section with a sub-document operation on that section’s path. Concurrent sub-document writes to different parts of a document don’t conflict, so section owners never overwrite each other.
  2. Use CAS for cross-section updates. Read the document, make the change, and write with the CAS value you read. Retry if another agent wrote first. A full-document write without CAS replaces every section, including ones another agent just changed.
  3. Allow last-writer-wins only for advisory fields that no agent branches on, such as a display note.

Top-level fields need owners too. In this example, the triage agent could own status. A field that every agent updates, such as updated_at, turns every write into a cross-section write, so give each section its own timestamp instead. And because the document outlives any single run, its trace_id can only identify the run that last changed it.

Some data doesn’t belong in shared state:

  • Conversation and profile memory belong in Couchbase Agent Memory, which scopes memory to users and sessions.
  • Tool logs belong in tool-call records.
  • Large artifacts, such as files or long documents, should be stored separately and referenced.

What about LangGraph shared state?

Frameworks such as LangGraph keep shared state in the graph’s state object for the duration of a graph run. With a checkpointer, LangGraph saves that state per thread so a run can pause and resume, and the Couchbase checkpointer for LangGraph stores those checkpoints in Couchbase. Checkpoints are scoped to one thread of one graph, though. Durable shared state is a database document that outlives any single run, so other runs, other agents, and people reviewing the case can all read it, regardless of the framework they use.

How do you version agent schemas without breaking running agents?

Agents built at different times will read each other’s documents, so schema changes need rules. Four practices keep versions compatible:

  1. Put schema_version on every document, and have readers pin the major version they understand. This works the same way catalog_id pins an Agent Catalog version.
  2. Make only additive changes within a major version. New optional fields are fine. Renaming or removing a field requires a new major version. Readers should ignore fields they don’t recognize, or even additive changes will break them.
  3. Give breaking changes a dual-write window. Writers emit both versions, readers migrate to the new one, and the old version is retired once no reader pins it.
  4. Record which agent build wrote each version so a malformed payload traces back to the deployment that produced it.

What are the read and write boundaries for each object?

Every object needs a rule for who can write it, who can read it, and what’s explicitly forbidden.

Written byRead byLifetimeOwner
Handoff payloadThe sending agentThe receiving agent, onceOne task; archived after completionThe sending agent until accepted, then the receiver
Tool-call recordThe agent framework, once per callDebugging, audit, and cost toolsKept for the audit window; append-onlyThe calling agent
Shared state documentOne owning agent per sectionSeveral agentsLong-lived; outlives any single runEach section’s owning agent

Two design principles apply to all three schemas:

  1. Each object gets one writer role and an explicit reader list. If multiple roles can write to the same field, conflicting updates can occur unless the system defines how it resolves those conflicts.
  2. Every object carries schema_version and trace_id. A trace ID is a shared identifier for one end-to-end run across agents. Without both fields, debugging a multi-agent failure is guesswork.

The examples below are application-level patterns, not formats Couchbase defines. Adapt the field names to your framework.

Schema 1: What should an agent handoff payload contain?

A handoff payload is a JSON document. The sending agent writes it, the receiving agent reads it once, and the system archives it after the task completes. The receiver records that it accepted the handoff outside the payload, for example in its section of the shared state document, so the payload keeps a single writer. Here’s an example for a customer support system where a triage agent hands a refund decision to a refund agent:

What each field is for:

  • handoff_id, schema_version, trace_id – Identifies the handoff, the format version it follows, and the run it belongs to. The handoff_id also works as an idempotency key, so a handoff delivered twice gets processed once.
  • from_agent, to_agent, created_at – Records who passed ownership to whom, and when.
  • task – A single-sentence goal. If the goal needs “and,” split it into two handoffs.
  • inputs – Document keys, not copied data. The receiver reads the current version from the database.
  • context_summary – What was done and what was ruled out, so the receiver doesn’t repeat it.
  • constraints – The deadline, the budget, and any tools the receiver must not call.
  • success_criteria – How the receiver knows the task is done.
  • return_to – The agent or queue that receives the result.

Three design rules keep payloads reliable:

  1. Use references, not copies. A copy goes stale as soon as the source document changes. To let the receiving agent check whether a document changed after the handoff, store the document’s compare-and-swap (CAS) value next to its key. Couchbase updates the CAS value on every write, so a different value means the document has changed.
  2. Give every needed fact a field. Don’t make the receiver parse a free-text blob.
  3. Make the payload readable on its own. The receiver should never need the sender’s chat history.

These rules prevent dropped handoff context, which is one of the multi-agent failures you can read more about in What Are My AI Agents Doing? How to Gain Insight and Control.

Schema 2: What should a tool-call record contain?

A tool-call record is an append-only document. It records that an agent called a tool, the arguments passed, the outcome, and the associated cost. Your agent framework writes the record because the Couchbase Agent Catalog doesn’t execute tools itself. The catalog holds the tool’s definition, and it manages and audits activity such as tool calls, tool results, agent handoffs, and LLM generations. If you use Agent Tracer, it already logs tool calls and tool results, linked by tool_call_id, and its ToolInvocations view pairs them for SQL++ queries. A separate tool-call record makes sense when you want your own fields on every call, such as cost, or when your framework doesn’t log through Agent Tracer.

What each field is for:

  • call_id, schema_version, trace_id, agent – Identify the call, schema version, associated run, and agent that made the call.
  • tool_name and catalog_id – Identify the tool invoked and the specific catalog version used. The Agent Catalog versions tools and prompts through Git and catalog.find() accepts a catalog_id to resolve a specific version.
  • args – Store arguments as structured JSON rather than a formatted prompt string. This makes calls easier to replay, inspect, and compare.
  • started_at, ended_at, latency_ms – Record execution timing for performance analysis.
  • status – Records the outcome of the call. If it fails, include error_type and error_message. Omit these fields on success.
  • result or result_ref – Store small results directly in the document and reference a separate document for larger results.
  • llm_tokens and cost_usd – Record the tokens consumed and model cost of the model turn that requested the call, allowing you to calculate costs across an entire run. If one turn requests several calls, record that cost on only one of them so run totals don’t double-count.

Typed tool models

The Agent Catalog documentation highly recommends declaring every tool’s input and output models with Pydantic or dataclasses. Typed models catch tool schema mismatches, where an agent sends arguments the tool doesn’t expect:

Records are append-only. A retry writes a new record with the same trace_id and never updates the old one, so the attempt history stays intact.

Schema 3: How do you structure shared state for multiple agents?

A shared state document is a durable JSON document that holds facts needed by several agents. It’s written under explicit ownership rules. Structure it as sections, one per owning agent, rather than a flat set of keys every agent can edit.

There’s no revision field in this example because Couchbase tracks one for you. Every document has a CAS value in its metadata that changes on each write. A write that supplies an outdated CAS value fails instead of overwriting newer data.

Three concurrency rules keep shared state consistent:

  1. One writer per section. Other agents read a section but never write it. Write a section with a sub-document operation on that section’s path. Concurrent sub-document writes to different parts of a document don’t conflict, so section owners never overwrite each other.
  2. Use CAS for cross-section updates. Read the document, make the change, and write with the CAS value you read. Retry if another agent wrote first. A full-document write without CAS replaces every section, including ones another agent just changed.
  3. Allow last-writer-wins only for advisory fields that no agent branches on, such as a display note.

Top-level fields need owners too. In this example, the triage agent could own status. A field that every agent updates, such as updated_at, turns every write into a cross-section write, so give each section its own timestamp instead. And because the document outlives any single run, its trace_id can only identify the run that last changed it.

Some data doesn’t belong in shared state:

  • Conversation and profile memory belong in Couchbase Agent Memory, which scopes memory to users and sessions.
  • Tool logs belong in tool-call records.
  • Large artifacts, such as files or long documents, should be stored separately and referenced.

What about LangGraph shared state?

Frameworks such as LangGraph keep shared state in the graph’s state object for the duration of a graph run. With a checkpointer, LangGraph saves that state per thread so a run can pause and resume, and the Couchbase checkpointer for LangGraph stores those checkpoints in Couchbase. Checkpoints are scoped to one thread of one graph, though. Durable shared state is a database document that outlives any single run, so other runs, other agents, and people reviewing the case can all read it, regardless of the framework they use.

How do you version agent schemas without breaking running agents?

Agents built at different times will read each other’s documents, so schema changes need rules. Four practices keep versions compatible:

  1. Put schema_version on every document, and have readers pin the major version they understand. This works the same way catalog_id pins an Agent Catalog version.
  2. Make only additive changes within a major version. New optional fields are fine. Renaming or removing a field requires a new major version. Readers should ignore fields they don’t recognize, or even additive changes will break them.
  3. Give breaking changes a dual-write window. Writers emit both versions, readers migrate to the new one, and the old version is retired once no reader pins it.
  4. Record which agent build wrote each version so a malformed payload traces back to the deployment that produced it.

What are the read and write boundaries for each object?

Every object needs a rule for who can write it, who can read it, and what’s explicitly forbidden.

ObjectWriterReadersExplicitly not permitted
Handoff payloadSending agentReceiving agent; audit and debugging toolsEdits after the receiver accepts it; reads by unrelated agents
Tool-call recordAgent framework, on behalf of the calling agentAudit, debugging, and cost toolsUpdates or deletes inside the retention window
Shared state documentEach section’s owning agentAgents listed in the schema’s reader listWrites to a section by any agent other than its owner; reads across tenants

Agent Memory offers a pattern to copy. It scopes every memory block to a session within a user, and it recommends one user per application identity and one session per conversation or workflow run. Apply the same kind of explicit rule to each object rather than leaving access implicit.

Before building, run a boundary test. Can any agent write a section it doesn’t own, or read another tenant’s state? If the answer is yes, the schema isn’t done. Keep the rules in the schema definition itself so reviewers can check them.

Couchbase can enforce the collection-level rules: Data Reader and Data Writer roles can be granted per collection, so each agent’s database credentials can reach only the collections that agent needs. Rules that roles can’t express, such as section ownership and append-only records, belong in application code.

Why keep handoffs, tool calls, and state in one data layer?

The handoff payloads, tool-call records, and shared state documents are all JSON documents. Keeping them in Couchbase alongside agent memory, the Agent Catalog, and agent traces provides a common query language, access model, backup process, and retention policy.

Here’s a layout that works for most applications:

LocationContents

handoff collection
Handoff payloads

tool_call collection
Tool-call records

agent_state collection
Shared state documents
Agent Catalog bucketTool and prompt definitions, plus activity logs
Couchbase Agent MemoryConversation, profile, and semantic memory

A shared trace_id lets you connect related agent activity across handoffs, tool calls, and state changes. If you use Agent Tracer, set a custom session on the root span that matches your trace_id, so tracer logs join to these documents too. Agent Catalog activity logs are stored as JSON in Couchbase and can be queried with SQL++ through the Query Service or Couchbase Operational Insights. Agent Tracer also generates SQL++ views over these logs, and its Sessions view can include agent handoffs, which you can filter with kind = “edge”. With a common trace_id, you can use SQL++ to combine handoff payloads and tool-call records and reconstruct the sequence of a run.

Both collections need a secondary index on trace_id for this query.

When these records are spread across separate systems, it becomes much harder to reconstruct an agent run. Handoffs might live in a message queue, tool-call logs in an observability platform, and shared state in a cache. Each system has its own query interface and retention policy, making it difficult to get a complete picture of what happened in one place.

For the broader design decisions behind an agentic app, such as models, frameworks, and storage, read Plan Your Agentic App, and for trace queries, see Query Agent Catalog Traces with SQL++.

Key takeaways

  1. An agent handoff transfers a task from one agent to another, along with the context the receiving agent needs to pick up where the first left off. 
  2. Handoffs, tool calls, and shared state reads are different coordination moves, and conflating them is a common source of multi-agent bugs.
  3. Most multi-agent systems write three objects: a handoff payload, a tool-call record, and a shared state document.
  4. Each object needs one writer role, an explicit reader list, a schema_version, and a trace_id.
  5. Handoff payloads should carry references, not copies, and be readable without the sender’s chat history.
  6. Tool-call records are append-only and should record the Agent Catalog version each call resolved to.
  7. Shared state works best as sections owned by individual agents, with sub-document writes within a section and CAS for cross-section updates.
  8. Keeping all three objects in one Couchbase data layer lets a single SQL++ query reconstruct a run by trace_id.

Agent handoff FAQs

What is an agent handoff? An agent handoff is the transfer of a task from one AI agent to another, along with the context the receiving agent needs to continue. A good handoff states what was done, what’s left to do, and what the receiving agent can assume is true.

What should an agent handoff payload contain? An agent handoff payload should contain a single-sentence task, references to input documents, a summary of what was done and ruled out, constraints, success criteria, and a return target. It should also carry a schema_version and a trace_id.

What is the difference between an agent handoff and a tool call? A handoff transfers task ownership to another agent. A tool call invokes a capability, such as a database query, and returns the result to the same agent, which keeps ownership of the task.

How do you structure shared state for multiple agents? Structure shared state as one durable JSON document with sections owned by individual agents. Each section has one writer, which updates it with sub-document operations; cross-section updates use compare-and-swap, and large data is stored separately and referenced.

How do you version agent schemas? Put a schema_version field on every document, make only additive changes within a major version, and give breaking changes a dual-write window. Readers pin the version they understand, the same way Agent Catalog’s catalog_id pins a catalog version.

Should handoff payloads carry data or references? Handoff payloads should carry references. Copied data goes stale as soon as the source document changes, and references keep payloads small enough to log and replay.

Share this article

Author

Leave a comment

Leave database sprawl in the past

Every stack addition means another bill, and more to manage. Estimate how you could save in 2 minutes.