Restrict managed OpenAI LLM models in AgentKit

Author: digitallysavvy

docs/concepts/vendors.md

@@ -22,7 +22,7 @@ Used with `agent.with_llm()` for the cascading flow (ASR → LLM → TTS).
 | Class | Provider | Required Parameters |
 |---|---|---|
 | `OpenAI` | OpenAI | `model` for Agora-managed models; `api_key`, `base_url`, `model` for BYOK |
-| `AzureOpenAI` | Azure OpenAI | `api_key`, `endpoint`, `deployment_name` |
+| `AzureOpenAI` | Azure OpenAI | `api_key`, `model`, `endpoint`, `deployment_name` |
 | `Anthropic` | Anthropic | `api_key`, `model`, `url`, `headers`, `max_tokens` |
 | `Gemini` | Google Gemini | `api_key`, `model` |
 | `Groq` | Groq | `api_key`, `model`, `base_url` |

docs/reference/vendors.md

@@ -51,6 +51,7 @@ llm = OpenAI(api_key='your-key', base_url='https://api.openai.com/v1/chat/comple
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `api_key` | `str` | Yes | — | Azure OpenAI API key |
+| `model` | `str` | Yes | — | Deployment's base model name. Emitted as `params.model`. |
 | `endpoint` | `str` | Yes | — | Azure endpoint URL |
 | `deployment_name` | `str` | Yes | — | Azure deployment name |
 | `api_version` | `str` | No | `2024-08-01-preview` | Azure API version |
@@ -73,6 +74,7 @@ from agora_agent import AzureOpenAI
 
 llm = AzureOpenAI(
     api_key='your-azure-key',
+    model='gpt-4o-mini',
     endpoint='https://your-resource.openai.azure.com',
     deployment_name='gpt-4o-mini',
 )
@@ -144,7 +146,7 @@ The SDK also includes named helpers for the remaining Agora-supported LLM provid
 
 | Class | Provider | Key parameters |
 |---|---|---|
-| `Groq` | Groq | `api_key`, `model`, `base_url?` |
+| `Groq` | Groq | `api_key`, `model`, `base_url` |
 | `VertexAILLM` | Google Vertex AI | `api_key`, `model`, `project_id`, `location`, `url?` |
 | `AmazonBedrock` | Amazon Bedrock | `access_key`, `secret_key`, `region`, `model` |
 | `Dify` | Dify | `api_key`, `url`, `model`, `user?`, `conversation_id?` |

src/agora_agent/agentkit/vendors/llm.py

@@ -5,6 +5,7 @@
 from .base import BaseLLM
 
 LlmGreetingConfigs = Dict[str, Any]
+_OPENAI_MANAGED_MODELS = {"gpt-4o-mini", "gpt-4.1-mini", "gpt-5-nano", "gpt-5-mini"}
 
 
 def _ensure_mcp_transport(servers: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
@@ -55,6 +56,10 @@ def _validate_byok_params(self) -> "OpenAIOptions":
             raise ValueError("OpenAI requires base_url when api_key is set")
         if self.api_key is None and self.base_url is not None:
             raise ValueError("OpenAI base_url is only valid when api_key is set")
+        if self.api_key is None and self.model.strip().lower() not in _OPENAI_MANAGED_MODELS:
+            raise ValueError("OpenAI requires api_key unless using a supported Agora-managed model")
+        if self.api_key is None and self.vendor is not None:
+            raise ValueError("OpenAI Agora-managed mode does not allow vendor")
         return self
 
 class OpenAI(BaseLLM):

tests/custom/test_llm_vendors.py

@@ -122,3 +122,13 @@ def test_llm_vendors_reject_missing_required_models() -> None:
 
     with pytest.raises(Exception, match="model"):
         AmazonBedrock(access_key="aws-access", secret_key="aws-secret", region="us-east-1")
+
+
+def test_openai_managed_mode_is_restricted_to_supported_models() -> None:
+    assert OpenAI(model="gpt-5-mini").to_config()["params"]["model"] == "gpt-5-mini"
+
+    with pytest.raises(Exception, match="api_key"):
+        OpenAI(model="gpt-4o")
+
+    with pytest.raises(Exception, match="does not allow vendor"):
+        OpenAI(model="gpt-5-mini", vendor="custom")