Support direct AgentSession kwargs in AgentPool.add

[mahimairaja]

Motivation

• Allow Milestone 3 callers to pass AgentSession options directly to AgentPool.add() while preserving the existing session_kwargs mapping for backward compatibility.
• Keep provider-level named parameters (stt, llm, tts) as the highest-precedence public API and make merging/precedence explicit to avoid surprising overrides.

Description

• Extended AgentPool.add() signature to accept session_kwargs: Mapping[str, Any] | None and **agent_session_kwargs and added validation that session_kwargs must be a mapping when provided.
• Added session_kwargs to AgentConfig and implemented _merge_session_kwargs() to merge mapping-based options with direct kwargs where direct kwargs override the mapping.
• Centralized construction of AgentSession keyword arguments in _build_agent_session_kwargs() so pool defaults (stt, llm, tts, vad, turn_detection) are only used when callers did not provide values.
• Updated _handle_session() to create AgentSession via AgentSession(**self._build_agent_session_kwargs(config, ctx)) and updated the README with an example and documented precedence rules.

Testing

• Added tests in tests/test_pool.py (merging behavior, precedence, rejection of non-mapping session_kwargs, and verification of the kwargs passed into AgentSession) and extended the local LiveKit stub in tests/conftest.py to expose the created session instance for assertions.
• Ran pytest tests/test_pool.py tests/test_discovery.py tests/test_cli.py with all tests passing (22 passed).
• Ran lint checks with ruff on modified files and received no issues.

---

Codex Task

Summary by CodeRabbit

Release Notes

• New Features

  • AgentPool.add() now supports direct AgentSession keyword arguments alongside the existing session_kwargs parameter
  • Direct keyword arguments take precedence over conflicting entries in session_kwargs
  • Simplified agent session configuration with flexible parameter merging

• Documentation

  • Updated README with examples demonstrating the new AgentPool.add() calling convention and parameter precedence rules

[coderabbitai]

Warning

Rate limit exceeded

@mahimairaja has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 19 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 18064e4c-d7bd-4f10-912a-3ab2410c8adb

📥 Commits

Reviewing files that changed from the base of the PR and between 86c82d3 and a54aa40.

📒 Files selected for processing (2)

• src/openrtc/pool.py
• tests/test_pool.py

📝 Walkthrough

Walkthrough

Added per-agent AgentSession keyword argument support to AgentPool. AgentConfig now includes a session_kwargs field, and AgentPool.add() accepts session_kwargs and **agent_session_kwargs parameters that merge with configuration provider defaults.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added documentation section describing the updated AgentPool.add() calling convention with session_kwargs parameter and direct keyword arguments, including precedence rules and a Python example.
Core Implementation src/openrtc/pool.py	Added session_kwargs field to AgentConfig and updated AgentPool.add() signature to accept session_kwargs and **agent_session_kwargs. Introduced _merge_session_kwargs() and _build_agent_session_kwargs() helpers to merge kwargs (with direct arguments overriding session_kwargs) and construct final session kwargs, respectively. Modified _handle_session() to use the new helper instead of explicit parameter passing.
Test Infrastructure tests/conftest.py	Enhanced test stub AgentSession to track instance construction via last_instance class attribute and record start() method arguments/kwargs in started_with instance attribute.
Test Coverage tests/test_pool.py	Added comprehensive test cases covering session_kwargs merging behavior, parameter override precedence, validation of session_kwargs as a mapping, and integration testing of _handle_session() with merged session kwargs.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Pool as AgentPool
    participant Config as AgentConfig
    participant Helper as _build_agent<br/>_session_kwargs
    participant Session as AgentSession
    
    User->>Pool: add(session_kwargs={...},<br/>**agent_session_kwargs)
    Pool->>Pool: _merge_session_kwargs(...)
    Pool->>Config: Create config with<br/>merged session_kwargs
    
    Note over Pool,Config: Configuration Phase Complete
    
    User->>Pool: _handle_session(ctx)
    Pool->>Helper: _build_agent_session_kwargs(config, ctx)
    Helper->>Helper: Deep-copy config kwargs
    Helper->>Helper: Apply defaults for stt/llm/tts
    Helper->>Helper: Apply defaults from ctx.userdata<br/>(vad, turn_detection)
    Helper-->>Pool: Final kwargs dict
    Pool->>Session: AgentSession(**final_kwargs)
    Session-->>User: Ready session

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~23 minutes

Possibly related PRs

• PR #2: Extends AgentPool/AgentConfig session handling with similar kwargs merging and helper utilities.
• PR #3: Also modifies AgentPool.add() and AgentConfig for discovery and defaults functionality, creating potential interaction points.

Poem

🐰 Hop, merge, and configure, our pool grows wise,
Session kwargs blend in harmonious guise,
Direct args triumph with precedence clear,
Agents spring forth when _handle_session draws near! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding support for direct AgentSession keyword arguments to AgentPool.add() method, which is the core feature added across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/update-agentpool.add-for-session_kwargs-support

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}