feat: add wrapper layer with Agent, AgentSession, and token support

[fern-support]

feat: add wrapper layer with Agent, AgentSession, and token support

Summary

Ports the custom wrapper layer from the TypeScript SDK to the Python SDK. Adds a src/agoraio/wrapper/ package with:

• Agent — Fluent builder for agent configuration. Supports shorthand strings (e.g. "openai/gpt-4") for LLM/TTS/STT, and converts to Fern-generated StartAgentsRequestProperties via to_properties().
• AgentSession / AsyncAgentSession — Session lifecycle management (start, stop, say, interrupt, update, get_history, get_info) with state tracking and an event emitter (on/off).
• avatar_types — Validation for HeyGen (24kHz) and Akool (16kHz) avatar/TTS sample rate constraints.
• token — generate_rtc_token() that delegates to agora_token_builder if installed, with a hand-rolled HMAC fallback.
• Type aliases — Shorter names (LlmConfig, SttConfig, TtsConfig, etc.) for verbose Fern-generated types.

All wrapper exports are re-exported from the top-level agoraio package. .fernignore updated to protect src/agoraio/wrapper/.

Updates since last revision

• Fixed mypy import-not-found error for optional agora_token_builder dependency (added # type: ignore[import-not-found]).
• Fixed mypy name-defined error for AgentSession return type in agent.py by adding from __future__ import annotations and a TYPE_CHECKING-guarded import.

Review & Testing Checklist for Human

• Token fallback correctness: token.py contains a custom _generate_dynamic_key HMAC fallback used when agora_token_builder is not installed. This is a hand-rolled reimplementation — verify it produces tokens Agora servers actually accept, or decide whether to drop the fallback and require the agora_token_builder dependency instead.
• TTS shorthand returns dict, not Tts model: _parse_tts_shorthand() returns a plain dict while LLM/STT parsers return Pydantic models. Confirm this is compatible when passed to StartAgentsRequestProperties(tts=...) — may silently fail or produce incorrect serialization at runtime.
• to_properties() logic: Complex branching for MLLM mode vs standard mode, token generation, and LLM config merging. Trace through a few representative configs (standard LLM+TTS, MLLM-only, with avatar) to verify correctness.
• create_session relies on hasattr checks: client.app_id if hasattr(client, "app_id") else "" will silently default to an empty string if the client object doesn't have the expected attributes, potentially masking misconfiguration.
• Fidelity to TS SDK: Compare behavior of shorthand parsing, avatar validation, and session lifecycle against the TS wrapper to catch any divergences.
• No tests: There are no unit tests for any wrapper code. Consider adding at least smoke tests for shorthand parsing and avatar validation before merging.

Test Plan

1. Install the SDK: pip install -e .
2. Test basic imports: python -c "from agoraio import Agent, AgentSession, generate_rtc_token"
3. Create an agent with shorthand: agent = Agent(instructions="...", llm="openai/gpt-4", tts="elevenlabs/voice-id")
4. Verify agent.to_properties(...) produces valid StartAgentsRequestProperties
5. Test token generation: generate_rtc_token(app_id="...", app_certificate="...", channel="test", uid=123)
6. Test avatar validation: validate_tts_sample_rate({"vendor": "heygen"}, 24000) (should pass), validate_tts_sample_rate({"vendor": "heygen"}, 16000) (should raise)
7. If possible, create a real session and verify start/stop/say work end-to-end

Notes

• Requested by @fern-support
• Link to Devin run: https://app.devin.ai/sessions/756e000c856649af9c8655b0ef4e1038
• Ruff lint and mypy checks pass; imports verified
• Go SDK wrapper implementation is in a separate PR: feat: add wrapper layer with type-safe vendor classes agora-agents-go#5

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

⚙️ Control Options:

• Disable automatic comment and CI monitoring