Fix AgentKit request validation and provider wire-key coverage

Author: digitallysavvy

PYTHON-AGENTKIT-SNAKE-CASE-AUDIT.md

@@ -0,0 +1,27 @@
+# Python AgentKit Snake Case API Audit
+
+Scope: `agora-agents-python` public AgentKit wrappers, docs, and tests.
+
+Search terms:
+
+```bash
+rg -n "apiKey|baseUrl|modelId|voiceId|groupId|keyTerm|turnDetection|inputAudioTranscription|greetingMessage|failureMessage|projectId|adcCredentialsString|sampleRate|targetLanguageCode|resourceName|deploymentName" agora-agents-python
+```
+
+## Result
+
+No shipped camelCase public Python constructor kwargs were found in source or docs examples. No deprecated alias helper is required for this pass.
+
+| File | Class / symbol | Public arg or example | Current spelling | Desired Python spelling | `to_config()` key | Wire key | Action | Compatibility needed | Test coverage |
+|---|---|---|---|---|---|---|---|---|---|
+| `src/agora_agent/agentkit/vendors/tts.py` | `GoogleTTS` | constructor arg | `voice_name` | `voice_name` | `params.VoiceSelectionParams` | `params.VoiceSelectionParams` | keep | no | `tests/custom/test_tts_vendors.py` |
+| `src/agora_agent/agentkit/vendors/tts.py` | `RimeTTS` | constructor arg | `model_id` | `model_id` | `params.modelId` | `params.modelId` | keep | no | `tests/custom/test_tts_vendors.py` |
+| `src/agora_agent/agentkit/vendors/tts.py` | `MurfTTS` | constructor arg | `voice_id` | `voice_id` | `params.voiceId` | `params.voiceId` | keep | no | `tests/custom/test_tts_vendors.py`, `tests/custom/test_request_body.py` |
+| `src/agora_agent/types/rime_tts_params.py` | generated model | generated alias | `modelId` | n/a | `model_id` | `modelId` | keep | no | `tests/custom/test_tts_vendors.py` |
+| `src/agora_agent/types/murf_tts_params.py` | generated model | generated alias | `voiceId` | n/a | `voice_id` | `voiceId` | keep | no | `tests/custom/test_tts_vendors.py` |
+| `tests/custom/test_request_body.py` | wire assertion | payload key | `voiceId` | n/a | `params.voiceId` | `params.voiceId` | keep | no | request-body test |
+| `tests/custom/test_tts_vendors.py` | wire assertion | payload key | `modelId`, `voiceId`, `VoiceSelectionParams` | n/a | generated model fields | wire aliases | keep | no | wire serialization test |
+
+## Guardrail Added
+
+`tests/custom/test_docs_snake_case.py` scans Python markdown code fences and fails on common camelCase kwargs such as `apiKey`, `baseUrl`, `modelId`, `voiceId`, `projectId`, and `greetingMessage`. JSON, TypeScript, Go, shell, and YAML examples are skipped so wire payload examples can retain required non-Python keys.

src/agora_agent/agentkit/agent.py

@@ -76,6 +76,7 @@
 from ..agent_management.types.agent_think_agent_management_response import (
     AgentThinkAgentManagementResponse,
 )
+from ..core.pydantic_utilities import parse_obj_as
 from .vendors.base import BaseAvatar, BaseLLM, BaseMLLM, BaseSTT, BaseTTS
 
 # Top-level aliases
@@ -188,6 +189,13 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     debug: bool
     warn: typing.Callable[[str], None]
 
+
+def _start_properties_from_mapping(
+    properties: typing.Mapping[str, typing.Any],
+) -> StartAgentsRequestProperties:
+    return parse_obj_as(StartAgentsRequestProperties, dict(properties))
+
+
 # LLM sub-type aliases
 LlmGreetingConfigs = typing.Dict[str, typing.Any]
 LlmGreetingConfigsMode = typing.Any
@@ -896,7 +904,7 @@ def to_properties(
                 if self._failure_message is not None:
                     mllm_config.setdefault("failure_message", self._failure_message)
                 base_kwargs["mllm"] = mllm_config
-            return StartAgentsRequestProperties(**base_kwargs)
+            return _start_properties_from_mapping(base_kwargs)
 
         if skip_vendor_validation:
             warnings.warn(
@@ -925,7 +933,7 @@ def to_properties(
         base_kwargs["turn_detection"] = turn_detection_config
 
         if skip_vendor_validation:
-            return StartAgentsRequestProperties(**base_kwargs)
+            return _start_properties_from_mapping(base_kwargs)
 
         if self._tts is None and not (skip_tts_validation or allow_missing_tts):
             raise ValueError("TTS configuration is required. Use with_tts() to set it.")
@@ -938,7 +946,7 @@ def to_properties(
         if self._tts is not None and not skip_tts_validation:
             base_kwargs["tts"] = self._tts
 
-        return StartAgentsRequestProperties(**base_kwargs)
+        return _start_properties_from_mapping(base_kwargs)
 
     def _resolve_llm_config(self) -> typing.Dict[str, typing.Any]:
         llm_config = dict(self._llm or {})

src/agora_agent/agentkit/agent_session.py

@@ -15,8 +15,7 @@
     AgentThinkAgentManagementResponse as AgentThinkResponse,
 )
 from ..agents.types.get_turns_agents_response import GetTurnsAgentsResponse
-from ..agents.types.start_agents_request_properties import StartAgentsRequestProperties
-from .agent import Agent, GetTurnsOptions, SayOptions, ThinkOptions
+from .agent import Agent, GetTurnsOptions, SayOptions, ThinkOptions, _start_properties_from_mapping
 from .avatar_types import (
     is_akool_avatar,
     is_anam_avatar,
@@ -350,6 +349,44 @@ def _build_start_properties(
 
         return properties
 
+    @staticmethod
+    def _request_properties_for_start(
+        resolved_properties: typing.Dict[str, typing.Any],
+        *,
+        resolved_preset: typing.Optional[str],
+        pipeline_id: typing.Optional[str],
+    ) -> typing.Any:
+        try:
+            return _start_properties_from_mapping(resolved_properties)
+        except Exception as exc:
+            if pipeline_id:
+                return resolved_properties
+            if resolved_preset:
+                preset_categories = {
+                    category
+                    for item in normalize_preset_input(resolved_preset).split(",")
+                    for category in [get_preset_category(item)]
+                    if category is not None
+                }
+                error_categories = _AgentSessionBase._validation_error_categories(exc)
+                if error_categories and error_categories.issubset(preset_categories):
+                    return resolved_properties
+            raise
+
+    @staticmethod
+    def _validation_error_categories(exc: Exception) -> typing.Set[str]:
+        errors = getattr(exc, "errors", None)
+        if not callable(errors):
+            return set()
+        categories: typing.Set[str] = set()
+        for error in errors():
+            loc = error.get("loc") if isinstance(error, dict) else None
+            if isinstance(loc, tuple) and loc:
+                field = loc[0]
+                if field in {"asr", "llm", "tts"}:
+                    categories.add(typing.cast(str, field))
+        return categories
+
     def _vendor_validation_categories(
         self,
         pipeline_id: typing.Optional[str],
@@ -514,10 +551,11 @@ def start(self) -> str:
                     "properties": resolved_properties,
                 })
 
-            try:
-                request_properties: typing.Any = StartAgentsRequestProperties(**resolved_properties)
-            except Exception:
-                request_properties = resolved_properties
+            request_properties = self._request_properties_for_start(
+                resolved_properties,
+                resolved_preset=resolved_preset,
+                pipeline_id=pipeline_id,
+            )
 
             response = self._client.agents.start(
                 self._app_id,
@@ -841,10 +879,11 @@ async def start(self) -> str:
                     "properties": resolved_properties,
                 })
 
-            try:
-                request_properties: typing.Any = StartAgentsRequestProperties(**resolved_properties)
-            except Exception:
-                request_properties = resolved_properties
+            request_properties = self._request_properties_for_start(
+                resolved_properties,
+                resolved_preset=resolved_preset,
+                pipeline_id=pipeline_id,
+            )
 
             response = await self._client.agents.start(
                 self._app_id,

tests/custom/test_docs_snake_case.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+SCANNED_MARKDOWN = [
+    ROOT / "README.md",
+    *sorted((ROOT / "docs").rglob("*.md")),
+]
+
+SKIP_LANGS = {
+    "bash",
+    "console",
+    "go",
+    "javascript",
+    "js",
+    "json",
+    "shell",
+    "sh",
+    "text",
+    "ts",
+    "typescript",
+    "yaml",
+    "yml",
+}
+
+PYTHON_HINTS = (
+    "from agora_agent",
+    "import agora_agent",
+    "Agent(",
+    "OpenAI(",
+    "OpenAITTS(",
+    "OpenAISTT(",
+    "MiniMaxTTS(",
+    "DeepgramSTT(",
+    "GoogleTTS(",
+    "RimeTTS(",
+    "VertexAI(",
+    "VertexAILLM(",
+)
+
+BLOCKED_TERMS = {
+    "apiKey": "api_key",
+    "baseUrl": "base_url",
+    "modelId": "model_id",
+    "voiceId": "voice_id",
+    "groupId": "group_id",
+    "projectId": "project_id",
+    "resourceName": "resource_name",
+    "deploymentName": "deployment_name",
+    "inputAudioTranscription": "input_audio_transcription",
+    "greetingMessage": "greeting_message",
+    "failureMessage": "failure_message",
+    "turnDetection": "turn_detection",
+    "adcCredentialsString": "adc_credentials_string",
+    "sampleRate": "sample_rate",
+    "targetLanguageCode": "target_language_code",
+}
+
+FENCE_RE = re.compile(r"^```(?P<lang>[^\n`]*)\n(?P<body>.*?)(?:^```)", re.MULTILINE | re.DOTALL)
+
+
+def _should_scan(lang: str, body: str) -> bool:
+    lang_parts = lang.strip().split(maxsplit=1)
+    normalized = lang_parts[0].lower() if lang_parts else ""
+    if normalized in {"python", "py"}:
+        return True
+    if normalized in SKIP_LANGS:
+        return False
+    if normalized:
+        return False
+    return any(hint in body for hint in PYTHON_HINTS)
+
+
+def test_python_docs_examples_use_snake_case_kwargs() -> None:
+    failures: list[str] = []
+
+    for path in SCANNED_MARKDOWN:
+        text = path.read_text()
+        for match in FENCE_RE.finditer(text):
+            body = match.group("body")
+            if not _should_scan(match.group("lang"), body):
+                continue
+
+            line_offset = text[: match.start("body")].count("\n")
+            for term, replacement in BLOCKED_TERMS.items():
+                for term_match in re.finditer(rf"\b{re.escape(term)}\b", body):
+                    line = line_offset + body[: term_match.start()].count("\n") + 1
+                    failures.append(f"{path.relative_to(ROOT)}:{line}: use {replacement} instead of {term}")
+
+    assert not failures, "CamelCase kwargs found in Python docs examples:\n" + "\n".join(failures)

tests/custom/test_llm_vendors.py

@@ -63,8 +63,10 @@ def test_vertex_ai_llm_includes_project_routing() -> None:
     assert config["api_key"] == "vertex-token"
     assert config["style"] == "gemini"
     assert config["params"]["model"] == "gemini-2.0-flash"
-    assert config["params"]["project_id"] == "project"
-    assert config["params"]["location"] == "us-central1"
+    assert "project" in config["url"]
+    assert "us-central1" in config["url"]
+    assert "project_id" not in config.get("params", {})
+    assert "location" not in config.get("params", {})
 
 
 def test_amazon_bedrock_serializes_as_bedrock_style() -> None: