Context sharing with collaborator agents

Edit online
Note: The context sharing behavior described in this topic applies when using the GPT-OSS model. For information about model-specific behaviors, see GPT-OSS model behavior and instruction guidelines.

When a supervisor agent delegates work to a collaborator agent, understanding what information is shared between them is critical for designing reliable multi-agent systems. Context sharing follows a specific pattern that affects how you design agent instructions, structure conversations, and manage information flow.

When a supervisor agent delegates to a collaborator agent, the collaborator receives only the information that appears in the chat conversation. This includes:

  • User messages that are part of the conversation history.
  • Agent responses that were displayed to the user or passed between agents.
  • The specific message the supervisor agent sends when delegating to the collaborator.

The collaborator does not automatically receive:

  • Tool outputs that were retrieved but not displayed in the conversation.
  • Internal reasoning or intermediate processing steps from the supervisor agent.
  • Background API responses or data that wasn't surfaced in chat.
  • Context from other collaborators unless explicitly included in the conversation.

Understanding context types

Distinguish between different types of context in multi-agent systems:

  • Conversation context: The visible chat history that includes user messages and agent responses. This is what collaborator agents receive when delegated to by a supervisor agent.
  • Context variables: User-specific data such as user ID, email, or session information that is automatically available to all agents in a conversation through the system. These variables persist across the entire conversation and are accessible to both supervisor and collaborator agents, even though they are not displayed in the chat interface.
  • Tool context: Data retrieved by tools during agent execution. This data is only visible to collaborators if it was displayed in the conversation or explicitly passed in the delegation message.
  • Thread context: Historical conversation state maintained within a specific collaborator thread when using thread IDs. Thread context allows a collaborator to remember previous interactions within its own conversation thread.

When the system delegates to a collaborator, you're primarily working with conversation context. The collaborator sees the visible chat history but doesn't automatically inherit tool outputs or internal processing that wasn't displayed. However, context variables remain accessible to all agents throughout the conversation.

Conversation state management

Collaborator agents can maintain conversation state across multiple interactions through threads. By default, each time the supervisor agent calls a collaborator, the collaborator starts with a fresh context. It has no memory of previous calls unless explicitly configured otherwise.

State resumption with thread IDs

When the supervisor agent calls a collaborator, it can optionally pass a thread_id parameter. This parameter enables the collaborator to resume a previous conversation and maintain context across multiple interactions.

The supervisor agent's language model automatically decides whether to pass a thread ID based on the conversation context. For more information, see Guiding thread ID usage.

Guiding thread ID usage

The language model's decision to pass thread IDs is probabilistic and may not always align with expectations. If you need the supervisor agent to consistently maintain continuity with a collaborator, you can add explicit guidance in the supervisor agent's instructions, for example:

"When interacting with the order_processing collaborator, always pass
the thread_id from the previous response to maintain conversation
continuity. This ensures the collaborator remembers order details
across multiple steps."

As you design your supervisor agent, craft delegation messages that include necessary context while avoiding overwhelming collaborators with irrelevant information. Focus on the specific data the collaborator needs to complete its task.

Preserving non-displayed information

Collaborators only receive visible conversation context. When the supervisor agent retrieves data through tools but doesn't display it in the chat, that information remains unavailable to collaborators. You must explicitly surface any information collaborators need that wasn't displayed to the user.

Consider the following scenario where hidden tool data creates a context gap:

  1. Supervisor agent calls a tool to retrieve customer data. It returns name, email, account_id, subscription_tier, and last_login.
  2. Supervisor agent displays to user: "Welcome back, John!".
  3. User asks: "Upgrade my subscription".
  4. Supervisor agent delegates to billing collaborator.

The billing collaborator cannot access the account_id or current subscription_tier because that information was retrieved but never displayed in the chat.

For preserving non-displayed information, you can work through the following options to ensure collaborators receive the information they need.

Strategy 1: Include context in the delegation message

You can include necessary context when delegating:

Supervisor agent instructions:
"When delegating to the billing collaborator, always include the
customer's account_id and current subscription tier in your message.
For example: 'Upgrade subscription for account ACC-12345, currently
on Basic tier.'"
Strategy 2: Enable collaborators to retrieve data independently

You can give collaborators their own tools to look up information they need, rather than relying entirely on context passing:

Billing collaborator tools:
- lookup_account_by_email
- get_subscription_details
- update_subscription

Supervisor agent message:
"Upgrade subscription for customer john@example.com"

Collaborator:
1. Calls lookup_account_by_email("john@example.com")
2. Gets account_id and current tier
3. Proceeds with upgrade
Strategy 3: Use context variables

For user-specific data that's consistently needed, use context variables that are automatically available to all agents in the conversation.

Design patterns for context management

Pattern 1: Explicit context passing

Use this pattern when collaborators need specific data from the supervisor agent's context. Supervisor agent instructions explicitly state what information to include when delegating.

Supervisor agent instructions:
"When delegating to the inventory collaborator, always include:
- Product SKU
- Requested quantity
- Customer location (for shipping calculation)

Format: 'Check inventory for SKU-12345, quantity 5, ship to US-CA'"
Pattern 2: Self-sufficient collaborators

Use this pattern when collaborators can independently retrieve the data they need. Collaborators have tools to look up information based on minimal input.

Collaborator tools:
- lookup_customer_by_email
- get_order_history
- check_account_status

Supervisor agent message:
"Process refund for customer jane@example.com"

Collaborator independently:
1. Looks up customer
2. Retrieves order history
3. Processes refund
Pattern 3: Conversation summarization

Use this pattern when delegating after a long conversation with multiple data points. The supervisor agent summarizes relevant context before delegating.

Supervisor agent instructions:
"Before delegating to the support collaborator, summarize the issue 
including: customer name, problem description, steps already attempted, 
and error messages encountered."
Pattern 4: Stateful workflows with thread IDs

Use this pattern for multi-step processes where collaborators need to remember previous interactions. The supervisor agent consistently passes thread IDs to maintain collaborator state. You can guide the supervisor agent to pass thread IDs when collaborators need to maintain state across interactions.

Supervisor agent instructions:
"When working with the onboarding collaborator, always pass the
thread_id from previous responses. This allows the collaborator to
track progress through the multi-step onboarding process."

What affects context sharing

Agent instructions

The supervisor agent's instructions determine what information gets included in delegation messages. You can improve reliability by providing clear, specific instructions about context passing. For more information about agent instructions, see Adding instructions and GPT-OSS model behavior and instruction guidelines.

Collaborator descriptions

Well-written collaborator descriptions help the supervisor agent understand what information the collaborator needs. You can include input requirements in the description to improve context passing. Writing clear descriptions that specify what information the collaborator needs helps document context dependencies:

Good description:
"Handles billing inquiries and subscription changes. Requires customer
account ID or email address. Can look up account details, process
upgrades/downgrades, and handle payment issues."

Weak description:
"Billing agent"

For more information about agent description, see Recommendations for agent descriptions.

Tool design

Tools with clear input schemas help agents understand what data to pass. You can use descriptive parameter names and detailed descriptions to improve context flow:

Tool: process_subscription_change
Parameters:
- account_id (required): "Customer account identifier (e.g., ACC-12345)"
- new_tier (required): "Target subscription tier (basic|pro|enterprise)"
- effective_date (optional): "When to apply change (ISO 8601 date)"

For more information about tools, see Managing tools from an agent.

Conversation structure

How you structure the conversation affects what context is available. You can display key information in the chat to make it available to all agents.

Debugging context issues

When collaborators lack necessary information, apply these debugging strategies to identify and resolve context gaps:

  • Check the delegation message: Review traces to see exactly what message the supervisor agent sent to the collaborator. Verify that it includes all necessary information.
  • Verify thread ID usage: If a collaborator should remember previous interactions but doesn't, check whether the supervisor agent passed a thread ID. If not, add explicit guidance in the supervisor agent's instructions.
  • Review tool outputs: Check whether critical information was retrieved but not displayed. If so, either display it in the conversation or include it in delegation messages.
  • Test collaborator independently: Test the collaborator agent directly with the same message the supervisor agent sends. This isolates whether the issue is context-related or a collaborator capability problem. Testing delegation scenarios helps verify that collaborators receive the context they need.
  • Audit conversation history: Review the full conversation to identify where context was lost. Look for information that was mentioned early but not carried forward.

For more information, see Monitoring agents (legacy experience).