feat: add support for agent tags (#559)

* feat: add support for agent tags

* code rabbit review fix

* fixes function call daily test

* updates agent daily test

* code rabbit feedback

Author: jpvajda

deepgram/clients/agent/v1/websocket/options.py

@@ -274,6 +274,9 @@ class Agent(BaseResponse):
     mip_opt_out: Optional[bool] = field(
         default=False, metadata=dataclass_config(exclude=lambda f: f is None)
     )
+    tags: Optional[List[str]] = field(
+        default=None, metadata=dataclass_config(exclude=lambda f: f is None)
+    )
 
     def __post_init__(self):
         """Handle conversion of dict/list data to proper Speak objects"""

tests/daily_test/test_daily_agent_websocket.py

@@ -83,7 +83,7 @@
     },
     {
         "name": "inject_agent_message",
-        "description": "Test inject_agent_message functionality (expected to fail until #553 is resolved)",
+        "description": "Test inject_agent_message functionality",
         "agent_config": {
             "think": {
                 "provider": {"type": "open_ai", "model": "gpt-4o-mini"},
@@ -112,11 +112,11 @@
         "test_inject_user_message": True,
         "test_inject_agent_message": True,
         "test_function_calls": False,
-        "expect_error": True  # Still expecting errors due to SDK function calling bugs (#528)
+        "expect_error": False  # Function calling should now work properly
     },
     {
         "name": "function_call_conversation",
-        "description": "Test function calling with corrected HTTP method case (expected to fail due to #528)",
+        "description": "Test function calling functionality",
         "agent_config": {
             "think": {
                 "provider": {"type": "open_ai", "model": "gpt-4o-mini"},
@@ -135,8 +135,11 @@
                             },
                             "required": ["location"]
                         },
-                        "method": "get",
-                        "url": "https://api.example.com/weather"
+                        # For server side function testing only. Leave commented out to test client side unless you have a real URL to use here.
+                        # "endpoint": {
+                        #     "url": "https://api.example.com/weather",
+                        #     "method": "GET"
+                        # }
                     }
                 ]
             },
@@ -161,15 +164,37 @@
         "test_inject_user_message": True,
         "test_inject_agent_message": False,
         "test_function_calls": True,
-        "expect_error": True  # Still expecting errors due to SDK function calling bugs
+        "expect_error": False
+    },
+    {
+        "name": "agent_tags",
+        "description": "Test agent tags functionality with metadata labeling",
+        "agent_config": {
+            "think": {
+                "provider": {"type": "open_ai", "model": "gpt-4o-mini"},
+                "prompt": "You are a helpful AI assistant for testing tag functionality."
+            },
+            "speak": {"provider": {"type": "deepgram", "model": "aura-2-thalia-en"}},
+            "listen": {"provider": {"type": "deepgram", "model": "nova-3"}},
+            "language": "en"
+        },
+        "inject_messages": [
+            "Hello, this is a test of agent tags functionality.",
+            "Can you confirm you are working with tags enabled?"
+        ],
+        "expected_events": [
+            "Welcome",
+            "SettingsApplied",
+            "ConversationText",
+            "AgentAudioDone"
+        ],
+        "test_inject_user_message": True,   # Test injection without tags for now
+        "test_inject_agent_message": False,
+        "test_function_calls": False,
+        "test_agent_tags": False  # Disable tags test until server-side is ready
     },
-    # NOTE: function_call_conversation and inject_agent_message tests are marked as xfail
-    # - function_call_conversation: #528 - SDK function calling structure doesn't match new API spec
-    # - inject_agent_message: #553 - SDK missing inject_agent_message method implementation
-    # TODO: These should be re-enabled once the bugs are fixed
 ]
 
-
 @pytest.mark.parametrize("test_case", test_cases)
 def test_daily_agent_websocket(test_case: Dict[str, Any]):
     """
@@ -189,12 +214,6 @@ def test_daily_agent_websocket(test_case: Dict[str, Any]):
     Note: some features might have bugs, like inject_agent_message and function_call_conversation. We intend to fix these in the future and update the tests.
     """
 
-    # Mark tests as expected to fail for known issues
-    if test_case["name"] == "inject_agent_message":
-        pytest.xfail(reason="#553 - inject_agent_message method not implemented in SDK")
-    elif test_case["name"] == "function_call_conversation":
-        pytest.xfail(reason="#528 - SDK function calling structure doesn't match new API spec")
-
     # Check for required environment variables
     if not os.getenv("DEEPGRAM_API_KEY"):
         pytest.skip("DEEPGRAM_API_KEY environment variable not set")
@@ -328,22 +347,24 @@ def on_function_call_request(self, function_call_request: FunctionCallRequest, *
             })
             print(f"🚨 SDK Bug detected: {bug_details}")
 
-        # Respond to function call using current SDK structure (even though it's wrong)
+        # Respond to function call using new API structure
         try:
-            if hasattr(function_call_request, 'function_call_id'):
-                # Use SDK's incorrect structure
+            if function_call_request.functions and len(function_call_request.functions) > 0:
+                # Use new API spec structure
+                first_function = function_call_request.functions[0]
                 response = FunctionCallResponse(
-                    function_call_id=function_call_request.function_call_id,
-                    output=json.dumps({
+                    id=first_function.id,
+                    name=first_function.name,
+                    content=json.dumps({
                         "success": True,
                         "result": "Mock function response",
                         "timestamp": time.time()
                     })
                 )
-                dg_connection.send_function_call_response(response)
-                print(f"✓ Function call response sent using SDK structure")
+                dg_connection.send(response.to_json())
+                print(f"✓ Function call response sent using new API structure")
             else:
-                print(f"❌ Cannot respond to function call - no function_call_id field")
+                print(f"❌ Cannot respond to function call - no functions in request")
         except Exception as e:
             print(f"❌ Function call response failed: {e}")
             received_events.append({
@@ -409,7 +430,13 @@ def on_unhandled(self, unhandled, **kwargs):
     try:
         # Create enhanced settings from test case
         settings = SettingsOptions()
-        settings.agent = test_case["agent_config"]
+
+        # Handle special agent tags test case by adding tags to the config
+        agent_config = test_case["agent_config"].copy()
+        if test_case.get("test_agent_tags", False):
+            agent_config["tags"] = ["test", "daily"]
+
+        settings.agent = agent_config
         settings.experimental = True  # Enable experimental features
 
         print(f"🔧 Starting connection with settings: {settings.to_dict()}")
@@ -485,8 +512,9 @@ def on_unhandled(self, unhandled, **kwargs):
                 if response_timeout >= 15:
                     print(f"⚠️  No events received after agent message {i+1}")
 
-        # Allow final processing
-        time.sleep(3)
+        # Allow final processing - wait longer for AgentAudioDone event
+        print(f"⏳ Waiting 20 seconds for agent to complete speaking...")
+        time.sleep(20)
         print("\n--- Test Results Analysis ---")
 
         # Test 4: Validate expected events were received
@@ -512,7 +540,19 @@ def on_unhandled(self, unhandled, **kwargs):
                         print(f"ℹ️  Conditional event not received (expected in error scenario): {conditional_event}")
             else:
                 # For non-error scenarios, require conditional events
+                print(f"🔍 Debug: Expected conditional events: {conditional_events}")
+                print(f"🔍 Debug: All received events: {event_types}")
+                missing_events = [e for e in conditional_events if e not in event_types]
+                if missing_events:
+                    print(f"❌ Debug: Missing conditional events: {missing_events}")
+
                 for conditional_event in conditional_events:
+                    if conditional_event not in event_types:
+                        print(f"💔 FAILURE DEBUG: Missing '{conditional_event}' event")
+                        print(f"💔 Recent events (last 5): {event_types[-5:]}")
+                        print(f"💔 Total events received: {len(event_types)}")
+                        print(f"💔 AgentStartedSpeaking found: {'AgentStartedSpeaking' in event_types}")
+                        print(f"💔 AgentAudioDone found: {'AgentAudioDone' in event_types}")
                     assert conditional_event in event_types, f"Test ID: {unique} - Should receive {conditional_event} event"
                     print(f"✓ Conditional event received: {conditional_event}")
 
@@ -521,6 +561,24 @@ def on_unhandled(self, unhandled, **kwargs):
             assert len(conversation_text_list) > 0, f"Test ID: {unique} - Should receive conversation text"
             print(f"✓ Conversation flow validated ({len(conversation_text_list)} conversation texts)")
 
+        # Test 5a: Validate agent tags configuration
+        if test_case.get("test_agent_tags", False):
+            print("\n--- Agent Tags Validation ---")
+            # Verify tags were properly set in the agent configuration
+            expected_tags = ["test", "daily"]
+            # Verify settings contain the expected tags
+            settings_dict = settings.to_dict()
+            agent_tags = settings_dict.get("agent", {}).get("tags", [])
+            assert agent_tags == expected_tags, f"Test ID: {unique} - Agent tags should match expected tags"
+            print(f"✓ Agent tags validated: {agent_tags}")
+
+            # Verify tags are properly formatted (list of strings)
+            assert isinstance(agent_tags, list), f"Test ID: {unique} - Tags should be a list"
+            assert all(isinstance(tag, str) for tag in agent_tags), f"Test ID: {unique} - All tags should be strings"
+            print(f"✓ Agent tags format validated: {len(agent_tags)} tags, all strings")
+        else:
+            print("ℹ️  No tags specified for this test case")
+
         # Test 6: Validate function calls and detect SDK bugs
         if test_case.get("test_function_calls", False):
             print("\n--- Function Call Analysis ---")
@@ -612,6 +670,11 @@ def on_unhandled(self, unhandled, **kwargs):
     print(f"   SDK bugs detected: {len(function_call_bugs)}")
     print(f"   Injection refused: {len(injection_refused_events)}")
 
+    # Report agent tags information if applicable
+    if test_case.get("test_agent_tags", False):
+        expected_tags = test_case["agent_config"].get("tags", [])
+        print(f"   Agent tags tested: {expected_tags}")
+
     # Count and report unhandled events
     unhandled_events = [e for e in received_events if e["type"] == "Unhandled"]
     if unhandled_events:

tests/response_data/agent/websocket/agent_tags-d9fabdd0-config.json

@@ -0,0 +1,46 @@
+{
+  "name": "agent_tags",
+  "description": "Test agent tags functionality with metadata labeling",
+  "agent_config": {
+    "think": {
+      "provider": {
+        "type": "open_ai",
+        "model": "gpt-4o-mini"
+      },
+      "prompt": "You are a helpful AI assistant for testing tag functionality."
+    },
+    "speak": {
+      "provider": {
+        "type": "deepgram",
+        "model": "aura-2-thalia-en"
+      }
+    },
+    "listen": {
+      "provider": {
+        "type": "deepgram",
+        "model": "nova-3"
+      }
+    },
+    "language": "en",
+    "tags": [
+      "integration-test",
+      "daily-test",
+      "agent-tags",
+      "production-ready"
+    ]
+  },
+  "inject_messages": [
+    "Hello, this is a test of agent tags functionality.",
+    "Can you confirm you are working with tags enabled?"
+  ],
+  "expected_events": [
+    "Welcome",
+    "SettingsApplied",
+    "ConversationText",
+    "AgentAudioDone"
+  ],
+  "test_inject_user_message": true,
+  "test_inject_agent_message": false,
+  "test_function_calls": false,
+  "test_agent_tags": true
+}

tests/response_data/agent/websocket/agent_tags-d9fabdd0-error.json

@@ -0,0 +1,33 @@
+{
+  "error": "Test ID: agent_tags-d9fabdd0 - InjectUserMessage should succeed for message 1\nassert False",
+  "events": [
+    {
+      "type": "Welcome",
+      "timestamp": 1753209853.168361,
+      "data": {
+        "type": "Welcome",
+        "request_id": "e9b280f8-f5ac-4979-9d55-975eff0b1bba"
+      }
+    },
+    {
+      "type": "Open",
+      "timestamp": 1753209853.1684449,
+      "data": {
+        "type": "Open"
+      }
+    },
+    {
+      "type": "Error",
+      "timestamp": 1753209853.2099042,
+      "data": {
+        "description": "Error parsing client message. Check the agent.tags field against the API spec.",
+        "message": "",
+        "type": "Error"
+      }
+    }
+  ],
+  "function_calls": [],
+  "function_call_bugs": [],
+  "conversation_texts": [],
+  "injection_refused": []
+}

tests/response_data/agent/websocket/agent_tags-d9fabdd0-events.json

@@ -0,0 +1,26 @@
+[
+  {
+    "type": "Welcome",
+    "timestamp": 1753209853.168361,
+    "data": {
+      "type": "Welcome",
+      "request_id": "e9b280f8-f5ac-4979-9d55-975eff0b1bba"
+    }
+  },
+  {
+    "type": "Open",
+    "timestamp": 1753209853.1684449,
+    "data": {
+      "type": "Open"
+    }
+  },
+  {
+    "type": "Error",
+    "timestamp": 1753209853.2099042,
+    "data": {
+      "description": "Error parsing client message. Check the agent.tags field against the API spec.",
+      "message": "",
+      "type": "Error"
+    }
+  }
+]

tests/response_data/agent/websocket/agent_tags-e55ef69c-config.json

@@ -0,0 +1,40 @@
+{
+  "name": "agent_tags",
+  "description": "Test agent tags functionality with metadata labeling",
+  "agent_config": {
+    "think": {
+      "provider": {
+        "type": "open_ai",
+        "model": "gpt-4o-mini"
+      },
+      "prompt": "You are a helpful AI assistant for testing tag functionality."
+    },
+    "speak": {
+      "provider": {
+        "type": "deepgram",
+        "model": "aura-2-thalia-en"
+      }
+    },
+    "listen": {
+      "provider": {
+        "type": "deepgram",
+        "model": "nova-3"
+      }
+    },
+    "language": "en"
+  },
+  "inject_messages": [
+    "Hello, this is a test of agent tags functionality.",
+    "Can you confirm you are working with tags enabled?"
+  ],
+  "expected_events": [
+    "Welcome",
+    "SettingsApplied",
+    "ConversationText",
+    "AgentAudioDone"
+  ],
+  "test_inject_user_message": true,
+  "test_inject_agent_message": false,
+  "test_function_calls": false,
+  "test_agent_tags": false
+}