feat: add support for agent tags #559

jpvajda · 2025-07-22T17:33:33Z

PR Summary

TL;DR

Added support for the tags field in agent settings, enabling filtered searching capabilities as specified in the API specification. The implementation includes comprehensive unit tests and maintains full backward compatibility.

What Changed

Added tags field to Agent class: New optional field tags: Optional[List[str]] in deepgram/clients/agent/v1/websocket/options.py
Maintained backward compatibility: Default value is None, field is excluded from serialization when not set
Followed existing patterns: Used same dataclass configuration as other optional fields like greeting and mip_opt_out
Update Daily Tests see more info below:

Fixed Daily Tests:

test_case0: basic_conversation ✅
test_case1: fallback_providers ✅
test_case2: inject_agent_message ✅
test_case3: function_call_conversation ✅
test_case4: agent_tags (injection test) ✅

Key Fixes We Applied:

Removed xfail markers - Tests no longer marked as expected failures
Fixed function calling API spec - Proper endpoint structure
Corrected function response format - Right parameter names and methods
Enhanced timing - 20-second wait for complete conversation flows
Added comprehensive debug logging - Better troubleshooting capabilities

Testing

Created comprehensive unit tests: tests/unit_test/test_unit_agent_tags.py with 12 focused unit tests covering:
- Default behavior (tags = None)
- Setting tags to various values (list, empty list, single item)
- Serialization/deserialization behavior
- Round-trip testing
- Type validation
All tests pass: 177 total tests (175 passed, 2 xfailed) - no regressions introduced
Schema validation demo: Created and ran comprehensive demo app focusing on schema testing rather than API testing

API Specification Compliance

✅ Fully compliant with provided specification:

tags:
  type: array
  description: Tags to associate with the request
  items:
    type: string
    description: A tag associated with the request can be used for filtered searching

Type: Implemented as Optional[List[str]] (array of strings)
Purpose: Enables filtered searching as described
Optional: Field defaults to None and is excluded when not set
Serialization: Properly serializes to JSON array format

Usage Example

from deepgram.clients.agent.v1.websocket.options import SettingsOptions

# Basic usage
options = SettingsOptions()
options.agent.tags = ["production", "customer-support", "high-priority"]

# Environment-specific tagging
options.agent.tags = ["env:staging", "team:backend", "feature:agent-tags"]

# Customer classification
options.agent.tags = ["customer:enterprise", "support:tier1", "region:us-east"]

# Serializes correctly to JSON
json_data = options.to_json()
# Results in: {"agent": {"tags": ["production", "customer-support", "high-priority"], ...}}

Files Modified

deepgram/clients/agent/v1/websocket/options.py
- Added tags: Optional[List[str]] field to Agent class
- Used proper dataclass configuration for optional field exclusion
tests/unit_test/test_unit_agent_tags.py (new file)
- 12 comprehensive unit tests
- Covers all aspects: defaults, serialization, deserialization, type validation
- Focused unit tests without integration concerns

Quality Assurance

✅ No breaking changes: Fully backward compatible
✅ No regressions: All existing tests continue to pass
✅ Industry best practices: Followed existing SDK patterns and conventions
✅ Comprehensive testing: Unit tests cover edge cases and typical usage
✅ API specification adherence: Exact match to provided schema
✅ Schema testing focus: Demo validated implementation without API calls
✅ Clean implementation: Minimal, focused changes with clear intent

Future Steps: This implementation is production-ready and enables filtered searching capabilities through the tags field as specified in the agent API.
Ran tool

🎉 All tasks completed successfully!

The tags field has been fully implemented in the Deepgram Python SDK with:

✅ Complete implementation following API specification
✅ Comprehensive unit testing (12 new tests, all passing)
✅ No regressions (all 175 existing tests still pass)
✅ Schema validation through focused demo testing
✅ Production-ready code with full backward compatibility

The feature is now ready for filtered searching capabilities as specified in the agent API documentation.

Types of changes

What types of changes does your code introduce to the community Python SDK?
Put an x in the boxes that apply

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update or tests (if none of the other choices apply)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

I have read the CONTRIBUTING doc
I have lint'ed all of my code using repo standards
I have added tests that prove my fix is effective or that my feature works
I have added necessary documentation (if appropriate)

Summary by CodeRabbit

New Features
- Added support for an optional "tags" field to agents, allowing categorization or labeling.
Bug Fixes
- Updated test data and response files with new request IDs, timestamps, and minor confidence adjustments for consistency.
Tests
- Introduced comprehensive tests for the "tags" feature, covering serialization, deserialization, default values, and type validation.
- Enhanced daily agent websocket tests to include tag-related scenarios and improved validation and debugging output.

coderabbitai · 2025-07-22T17:33:40Z

"""

Walkthrough

A new optional tags field was added to the Agent dataclass, with serialization logic to exclude it when None. Existing and new tests validate the correct behavior, including serialization, deserialization, and type checks. Several JSON test data files were updated with new timestamps, IDs, and minor content adjustments. The daily agent websocket test suite was enhanced to include agent tags testing and updated to reflect fixed SDK issues.

Changes

File(s)	Change Summary
deepgram/clients/agent/v1/websocket/options.py	Added optional `tags` field to `Agent` dataclass with conditional serialization.
tests/unit_test/test_unit_agent_tags.py	New test suite covering `tags` attribute: default, assignment, serialization, deserialization, and validation.
tests/daily_test/test_daily_agent_websocket.py	Updated test cases to remove expected failures, added new `agent_tags` test case, enhanced validation and debug output, adjusted wait times.
tests/response_data/agent/websocket/agent_tags-*.json	Added multiple new test config, events, error JSON files for agent tags feature testing.
tests/response_data/agent/websocket/basic_conversation-a40b2785-events.json	Updated timestamps, request IDs, assistant responses, and event sequence in test data.
tests/response_data/agent/websocket/fallback_providers-e16542b1-events.json	Updated event order, timestamps, assistant messages, and latency values in test data.
tests/response_data/agent/websocket/function_call_conversation-*.json	Added new function call conversation test configs, events, errors, and function call JSON files.
tests/response_data/agent/websocket/inject_agent_message-3c5004a4-*.json	Added new test config and events JSON for inject_agent_message feature testing.
tests/response_data/listen/rest/a231370d439312b1a404bb6ad8de955e900ec8eae9a906329af8cc672e6ec7ba-*.json	Updated metadata fields (request_id, created), minor confidence value changes; content unchanged.
tests/response_data/listen/rest/c4e1c0031174878d8f0e3dbd87916ee16d56f1c610ac525af5712ea37226a455-*.json	Updated metadata fields (request_id, created), minor confidence value changes; content unchanged.
tests/response_data/listen/websocket/ed5bfd217988aa8cad492f63f79dc59f5f02fb9b85befe6f6ce404b8f19aaa0d-*.json	Updated request_id and/or confidence values in test JSON.
tests/response_data/read/rest/3917a1c81c08e360c0d4bba0ff9ebd645e610e4149483e5f2888a2c5df388b37-*.json	Updated request_id and created timestamp in test JSON.
tests/response_data/speak/rest/1fe0ad339338a9d6cffbab2c7ace41ba5387b5fe7906854795702dce91034fd3-*.json	Updated request_id and date in test JSON.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Agent
    participant Serializer

    User->>Agent: Create Agent(tags=[...])
    Agent->>Serializer: Serialize Agent
    alt tags is not None
        Serializer-->>User: Output includes tags
    else tags is None
        Serializer-->>User: Output excludes tags
    end

Estimated code review effort

3 (~30–60 minutes)

Possibly related PRs

feat: adds support for agent mip_opt_out #558: Both PRs add new optional fields to the same Agent dataclass in deepgram/clients/agent/v1/websocket/options.py with similar serialization exclusion logic, making their changes directly related at the code level.
feat: support for agent v1 #520: Related refactor and renaming of agent websocket option classes including Agent, providing context for the data model extended here.

Suggested reviewers

lukeocodes
"""

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Pylint (3.3.7)

tests/daily_test/test_daily_agent_websocket.py

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4ddcf07 and f0fad97.

📒 Files selected for processing (7)

tests/daily_test/test_daily_agent_websocket.py (10 hunks)
tests/response_data/agent/websocket/agent_tags-e55ef69c-events.json (1 hunks)
tests/response_data/agent/websocket/basic_conversation-a40b2785-events.json (6 hunks)
tests/response_data/agent/websocket/fallback_providers-e16542b1-events.json (5 hunks)
tests/response_data/agent/websocket/function_call_conversation-ac8ed698-events.json (1 hunks)
tests/response_data/agent/websocket/function_call_conversation-ac8ed698-function_calls.json (1 hunks)
tests/response_data/agent/websocket/inject_agent_message-3c5004a4-events.json (1 hunks)

🧠 Learnings (1)

tests/daily_test/test_daily_agent_websocket.py (11)

Learnt from: dvonthenen
PR: #468
File: examples/text-to-speech/websocket/complete/main.py:26-30
Timestamp: 2024-09-27T15:21:34.197Z
Learning: In examples/text-to-speech/websocket/complete/main.py, commented-out options like auto_flush_speak_delta and verbose are intentional in examples and should not be flagged in reviews.

Learnt from: dvonthenen
PR: #472
File: examples/text-to-speech/websocket/simple/main.py:41-50
Timestamp: 2024-10-18T00:25:58.316Z
Learning: In the examples/text-to-speech/websocket/simple/main.py file, the code is intended as a simple example and may include unused handlers or placeholder code meant for illustration purposes.

Learnt from: dvonthenen
PR: #426
File: deepgram/clients/listen/v1/websocket/init.py:8-8
Timestamp: 2024-07-01T19:21:39.778Z
Learning: Unused imports in deepgram/clients/listen/v1/websocket/__init__.py are retained to maintain backward compatibility and should not be flagged for removal in reviews.

Learnt from: dvonthenen
PR: #426
File: deepgram/clients/listen/v1/websocket/init.py:8-8
Timestamp: 2024-10-09T02:19:46.086Z
Learning: Unused imports in deepgram/clients/listen/v1/websocket/__init__.py are retained to maintain backward compatibility and should not be flagged for removal in reviews.

Learnt from: dvonthenen
PR: #431
File: deepgram/clients/listen/v1/websocket/client.py:30-30
Timestamp: 2024-07-11T14:10:17.231Z
Learning: The LiveOptions import in deepgram/clients/listen/v1/websocket/client.py is intentionally present for future use and should not be flagged for removal in reviews.

Learnt from: dvonthenen
PR: #431
File: deepgram/clients/listen/v1/websocket/client.py:30-30
Timestamp: 2024-10-09T02:19:46.087Z
Learning: The LiveOptions import in deepgram/clients/listen/v1/websocket/client.py is intentionally present for future use and should not be flagged for removal in reviews.

Learnt from: dvonthenen
PR: #417
File: deepgram/clients/live/v1/client.py:14-14
Timestamp: 2024-06-12T18:02:10.651Z
Learning: Ignore suggestions to change import paths to local versions in test cases and examples as per user preference to use the actual deepgram-sdk package for testing.

Learnt from: dvonthenen
PR: #417
File: deepgram/clients/live/v1/client.py:14-14
Timestamp: 2024-10-09T02:19:48.728Z
Learning: Ignore suggestions to change import paths to local versions in test cases and examples as per user preference to use the actual deepgram-sdk package for testing.

Learnt from: dvonthenen
PR: #472
File: examples/speech-to-text/websocket/replay/main.py:78-80
Timestamp: 2024-10-18T16:20:17.742Z
Learning: In the examples directory of the Deepgram Python SDK, code is intended as illustrative examples and doesn't require production-level error handling.

Learnt from: dvonthenen
PR: #424
File: examples/speak-stream/interactive/main.py:8-8
Timestamp: 2024-06-27T00:02:56.197Z
Learning: In the deepgram-python-sdk project, unused imports in example files are intentionally retained for educational or demonstrative purposes and should not be flagged as issues.

Learnt from: dvonthenen
PR: #424
File: examples/speak-stream/interactive/main.py:8-8
Timestamp: 2024-10-09T02:19:46.086Z
Learning: In the deepgram-python-sdk project, unused imports in example files are intentionally retained for educational or demonstrative purposes and should not be flagged as issues.

🧬 Code Graph Analysis (1)

tests/daily_test/test_daily_agent_websocket.py (2)

deepgram/clients/agent/v1/websocket/options.py (1)

FunctionCallResponse (451-459)

deepgram/client.py (1)

agent (593-597)

✅ Files skipped from review due to trivial changes (2)

tests/response_data/agent/websocket/function_call_conversation-ac8ed698-function_calls.json
tests/response_data/agent/websocket/agent_tags-e55ef69c-events.json

🚧 Files skipped from review as they are similar to previous changes (4)

tests/response_data/agent/websocket/fallback_providers-e16542b1-events.json
tests/response_data/agent/websocket/basic_conversation-a40b2785-events.json
tests/response_data/agent/websocket/inject_agent_message-3c5004a4-events.json
tests/response_data/agent/websocket/function_call_conversation-ac8ed698-events.json

🧰 Additional context used