Stale examples + unpinned dependencies + MCP server = broken developer experience at scale

[Garry2012]

This repo has a compounding problem that affects every developer using LiveKit - and it gets exponentially worse when AI coding tools are involved.

Layer 1: No dependency pinning. Most examples use requirements.txt with unpinned or loosely pinned dependencies. When a developer runs pip install -r requirements.txt, they get the latest SDK version. But the example code was written for an older version. The code silently breaks - not with import errors, but with subtle runtime bugs (infinite loops, wrong behavior, cryptic exceptions). Developers waste hours thinking the bug is in their code.

Layer 2: Stale code patterns. Many examples use patterns that conflict with the current official documentation. For instance, the medical_office_triage example uses singleton agents stored in a dict, manual chat context truncation, and prev_agent tracking - none of which appear in the current official docs. The official pattern is to return a new Agent instance from @function_tool with chat_ctx=self.chat_ctx. This isn't a nitpick - using the old pattern causes an infinite agent transfer loop.

Layer 3: The MCP server amplifies this to every AI coding tool on earth. LiveKit provides an MCP server at https://docs.livekit.io/mcp with a get_python_agent_example tool that serves code directly from this repo. AI coding tools (Claude Code, Cursor, Windsurf, Copilot, etc.) use this MCP server as an authoritative reference. When a developer asks their AI agent to "build a multi-agent system with LiveKit," the agent calls get_python_agent_example, gets stale code, and uses it as the foundation for the new application. The developer has no idea the patterns are outdated because they came through an "official" channel.

This is not a theoretical risk. We experienced it firsthand building a production Voice AI platform.

What We Observed

1. Ran medical_office_triage example with livekit-agents==1.3.12 (latest at time of testing)
2. Got Exception: cannot access local participant before connecting on first on_enter
3. Got infinite transfer loop: TriageAgent → SupportAgent → TriageAgent → SupportAgent → ...
4. AI coding agent (Claude Code via MCP) spent multiple debugging cycles patching symptoms instead of recognizing the architecture was fundamentally outdated
5. Only discovered the real issue when we manually compared against official docs at /agents/logic/agents-handoffs/

Concrete Examples of Drift

Pattern | This Repo | Official Docs -- | -- | -- Agent handoff | Return pre-created singleton from dict | Return new Agent instance from @function_tool Context preservation | Manual copy + truncate in on_enter | Pass chat_ctx via Agent constructor Agent greeting | Manual chat_ctx.add_message() + generate_reply() | session.generate_reply(instructions="...") Dependencies | Unpinned / >= / requirements.txt | N/A (but should be pinned to tested version)

Impact

• Individual developers: Waste hours debugging examples that look correct but use deprecated patterns
• Teams using AI tools: Their AI agents silently propagate legacy patterns into production codebases via the MCP server. The team has no way to know the patterns are stale because they came from an "official" source
• LiveKit adoption: New developers trying LiveKit for the first time run these examples, hit confusing errors, and may abandon the platform thinking it's unstable

Suggested Fixes

Short term:

1. Pin exact dependency versions in every example's requirements.txt to the SDK version the code was tested against
2. Add a tested_sdk_version field to each example's metadata (the YAML frontmatter already exists)
3. Add a CI job that runs each example against the latest SDK and flags breakages

Medium term: 4. Update all examples to match current official doc patterns 5. Add a staleness warning in the MCP get_python_agent_example tool response when an example hasn't been updated in X releases

Long term: 6. Version-tag examples so the MCP server can serve the right code for the developer's SDK version 7. Consider a last_verified timestamp in example metadata that MCP can surface to AI tools 8. Add integration tests that run examples end-to-end (not just import checks) against each SDK release

Environment

• livekit-agents: 1.3.12
• Python: 3.12
• OS: macOS (Darwin 23.4.0)
• MCP server: https://docs.livekit.io/mcp

We Want to Help

We're building a production Voice AI platform on LiveKit at InTimeTec and are invested in this ecosystem succeeding. Happy to submit PRs to update examples, add version pins, or help design the MCP versioning approach. Let us know how we can contribute.