Error: expected to receive only one AgentTask when multiple agents/tools respond to a single intent

[Jaya-sys]

Bug Description

When using multiple agents (or tools mapped to different agents) in LiveKit Agents, if a single user intent triggers more than one agent/tool, the system throws the following error and the conversation goes silent:
"""ERROR livekit.agents: expected to receive only one AgentTask from the tool executions""""

After this error:

No audio response is returned

No fallback or partial response is produced

The call/session becomes silent

Expected Behavior

Aggregating multiple tool responses into one AgentTask

Sequential execution guidance

• Explicit orchestration patterns

• At minimum, the system should not fail silently.

Reproduction Steps

Steps to Reproduce

Create two agents (or tools backed by different agents)

Route a single user intent that causes both agents/tools to execute

Each agent/tool returns an AgentTask

LiveKit throws the error and drops the response

Example scenario:

User asks:

“Check my order status and raise a complaint”

Agent A → order status tool

Agent B → complaint tool

Both return AgentTask in the same turn

Operating System

macos intel

Models Used

Azure STT, GPT4.1, Azure TTS

Package Versions

aiocache>=0.12.3",
    "azure-cognitiveservices-speech>=1.46.0",
    "azure-identity>=1.25.1",
    "azure-search-documents>=11.6.0",
    "certifi>=2025.11.12",
    "livekit>=1.0.20",
    "livekit-agents[azure,deepgram,mcp,openai,silero,turn-detector]===1.3.12",
    "livekit-plugins-azure>=1.3.6",
    "livekit-plugins-noise-cancellation",
    "openai<2.0.0,>=1.16.2",
    "opentelemetry-exporter-otlp-proto-http>=1.39.0",
    "python-dotenv>=1.2.1",
    "pyyaml"

Session/Room/Call IDs

No response

Proposed Solution

Additional Context

No response

Screenshots and Recordings

No response

[tinalenguyen]

Hi, thanks for creating this report! If you are looking for sequential AgentTask execution, I would recommend looking into TaskGroup. For this case, is there a reason why you return the AgentTask in the function tool instead of awaiting it in the tool?

taskgroup docs

[longcw]

when you return an Agent from a tool, the session will switch to the new agent. the behavior is unexpected when there are two agents returned from a single turn. maybe you can disable the parallel tool execution or redesign the two tools to avoid this.

[Jaya-sys]

Thanks both, this helps clarify the intended model.

To answer the question returning AgentTask from the tool wasn’t done to explicitly switch agents, but rather because each tool was modeled as a self-contained capability that could independently produce a response. From a developer perspective, this felt like a natural pattern, especially when tools are agent-backed.

The confusion for us came from the fact that tools can return AgentTask, but there’s no obvious signal that doing so from more than one tool in the same turn will cause a hard failure. When this happens, the error manifests as silence, which makes it particularly difficult to diagnose in voice-based flows.

TaskGroup does address sequential execution, and disabling parallel tool execution or restructuring tools makes sense in hindsight. However, it wasn’t immediately clear that:

returning an Agent/AgentTask from a tool implies a session switch

only a single AgentTask is allowed per turn

Having this explicitly documented (or validated at runtime with a clearer error) would significantly improve the developer experience and help avoid accidental multi-agent responses.

Appreciate the guidance — we’ll refactor accordingly, but wanted to flag this as a DX/documentation gap rather than unexpected usage

[tinalenguyen]

Thank you for the detailed feedback @Jaya-sys, we will update the documentation accordingly to provide more clarity!

[Jaya-sys]

Thanks, appreciate it!
If it helps speed things up, I’d be happy to open a small PR to add a note or warning around tools returning AgentTask and the single-AgentTask-per-turn constraint. Just let me know if that would be useful and where you’d prefer it in the docs.

[Jaya-sys]

livekit.agents._exceptions.APIStatusError: Error code: 400 - {'error': {'message': "Invalid value for 'parallel_tool_calls': 'parallel_tool_calls' is only allowed when 'tools' are
specified.", 'type': 'invalid_request_error', 'param': 'parallel_tool_calls', 'code': None}} (status_code=400, request_id=61d2c96d-4d12-4e6d-92f3-ab87c5aac87b, body={'message': "Invalid
value for 'parallel_tool_calls': 'parallel_tool_calls' is only allowed when 'tools' are specified.", 'type': 'invalid_request_error', 'param': 'parallel_tool_calls', 'code': None},
retryable=True)

Passing the parameter parallel_tool_calls = False