Skip to content

fix(runtime): resolve transfer_task caller from pinned session agent - #3893

Open
yangtuooc wants to merge 1 commit into
docker:mainfrom
yangtuooc:fix/background-agent-transfer-task
Open

fix(runtime): resolve transfer_task caller from pinned session agent#3893
yangtuooc wants to merge 1 commit into
docker:mainfrom
yangtuooc:fix/background-agent-transfer-task

Conversation

@yangtuooc

Copy link
Copy Markdown

What

Fixes transfer_task failing inside a run_background_agent sub-session. See issue #3886.

Problem

A coordinator (root) fans out work via run_background_agent to a composite agent (pipeline) that has its own sub_agents (e.g. director). When pipeline calls transfer_task(agent="director"), it fails with:

Agent root cannot transfer task to director: target agent not in sub-agents list. Available agent IDs are: pipeline

The error names root as the caller even though the call originates from pipeline, whose sub-agents do include director.

Root cause

handleTaskTransfer resolves the calling agent via r.CurrentAgent(), which returns the runtime's shared current-agent field. Background sub-sessions are created with PinAgent: true + WithAgentName(cfg.AgentName) (RunAgentrunCollecting), which pins the session to pipeline but deliberately does not mutate currentAgent (it stays root). So validation runs against root.SubAgents() = [pipeline] and rejects director.

agentRouter.ResolveSession already handles pinned sessions ("when sess pins a specific agent (e.g. background agent tasks), that agent is returned directly"), but handleTaskTransfer wasn't using it.

Fix

Resolve the caller via resolveSessionAgent(sess) instead of CurrentAgent(). This returns the pinned agent when the session pins one, and falls back to CurrentAgent() otherwise — so ordinary transfer_task behavior is unchanged.

Tests

Adds TestHandleTaskTransfer_UsesPinnedSessionAgent: a session pinned to pipeline (as run_background_agent does) transfers to director while the runtime's current-agent is root.

  • Without fix: fails with the exact error above
  • With fix: passes

go test ./pkg/runtime/ passes.

Closes #3886

transfer_task inside a background sub-session failed because handleTaskTransfer
resolved the calling agent via CurrentAgent(), which returns the shared
current-agent (the root coordinator) rather than the agent pinned to the
sub-session. Background sub-sessions pin their agent (PinAgent) without
mutating currentAgent, so a pipeline dispatched via run_background_agent
could not delegate to its own sub-agents.

Resolve the caller via resolveSessionAgent(sess), which returns the pinned
agent when the session pins one and falls back to CurrentAgent otherwise.
Adds a regression test reproducing the background delegation failure.

Closes docker#3886
@yangtuooc
yangtuooc requested a review from a team as a code owner August 3, 2026 12:13
@aheritier aheritier added kind/fix PR fixes a bug (maps to fix:). Use on PRs only. area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection labels Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection kind/fix PR fixes a bug (maps to fix:). Use on PRs only.

Projects

None yet

2 participants