feat(llm): investigate hosted Multi-agent (GPT-5.6 subagents) vs our client-side subagent system

📄 Study page: Hosted Multi-agent vs the OpenHands SDK's client-side subagents

Summary

OpenAI's Multi-agent (beta, GPT‑5.6) lets a model spin up and coordinate subagents in parallel inside a single Responses request — the "subagents" behind GPT‑5.6's ultra mode. Orchestration (spawn/message/wait/synthesize) is hosted by OpenAI, not the client. This issue tracks investigating it and deciding how it relates to the SDK's existing client-side subagent system.

What the feature needs (from the OpenAI docs)

• multi_agent.enabled: true + max_concurrent_subagents (default/recommended 3), beta header OpenAI-Beta: responses_multi_agent=v1 (or betas=["responses_multi_agent=v1"]).
• Six hosted collaboration actions surfaced as multi_agent_call items (do not execute client-side): spawn_agent, send_message, followup_task, wait_agent, interrupt_agent, list_agents.
• New output items: multi_agent_call, multi_agent_call_output, agent_message (encrypted). Items carry an agent attribute (/root, /root/researcher, …); final answer is the /root message with phase == "final_answer".
• Client-defined function_calls still work: any agent may emit one; the app executes it and returns function_call_output as usual.
• Server-side compaction is auto-enabled; /responses/compact, reasoning.summary, and max_tool_calls are not supported when enabled. WebSocket recommended for tool-heavy runs.

The interesting delta: hosted vs client-orchestrated subagents

The SDK already has a subagent story, but it's client-orchestrated:

• openhands-sdk/openhands/sdk/subagent/ — markdown agent definitions + registry
• openhands-tools/openhands/tools/delegate/ — spawn/delegate tool
• openhands-tools/openhands/tools/task/ — TaskTool / TaskToolSet backed by a TaskManager
• openhands-tools/openhands/tools/task_tracker/

So the core question is who orchestrates: our SDK spawns and drives full sub-conversations (portable across models, fully observable/controllable), whereas OpenAI's multi-agent hides orchestration server-side (less code, GPT‑5.6-only, beta, opaque encrypted inter-agent messages). This is a design choice, not just a parsing gap.

Gaps if we wanted to support the hosted mode

• No multi_agent request param plumbing or beta-header handling. → select_responses_options (openhands-sdk/openhands/sdk/llm/options/responses_options.py), _build_responses_call_kwargs (openhands-sdk/openhands/sdk/llm/llm.py:916)
• No parsing of multi_agent_call / multi_agent_call_output / agent_message, and no agent / phase attribution on parsed messages. → openhands-sdk/openhands/sdk/llm/message.py:541

Proposed scope

1. Write up the hosted-vs-client comparison and get a maintainer decision on whether hosted multi-agent is worth supporting at all (given we already have a portable client-side system).
2. If yes: minimal plumbing for multi_agent.enabled + beta header, and parse/preserve the three new item types with agent/phase attribution behind a feature flag.

Notes / open questions

• Beta, schemas may change; GPT‑5.6-only. Encrypted agent_message content limits observability compared to our client-side delegation.
• Recommend keeping the client-side subagent system as the default and treating hosted multi-agent as an optional, model-specific accelerator.

Investigation for GPT‑5.6 feature parity. Companion issues: programmatic tool calling, tool search, WebSocket mode.

Companion investigation issues (GPT‑5.6 Responses features): #4082 (Programmatic Tool Calling) · #4083 (Tool search) · #4084 (WebSocket mode) · #4085 (Multi-agent)

Start with the linked hosted-vs-client comparison, then read the existing subagent directories and the named entry points in responses_options.py, llm.py, and message.py. Confirm how current client-side delegation works and identify the maintainer decision needed before implementation. Done means a documented comparison and decision; if approved, the issue's proposed request plumbing and item attribution are defined behind a feature flag.