Skip to content

feat: add support for agent tags#423

Closed
jpvajda wants to merge 4 commits into
mainfrom
feat/agent-tags
Closed

feat: add support for agent tags#423
jpvajda wants to merge 4 commits into
mainfrom
feat/agent-tags

Conversation

@jpvajda

@jpvajda jpvajda commented Jul 21, 2025

Copy link
Copy Markdown
Contributor

PR Summary: Add tags Support to Agent Settings

TL;DR

Added tags field to AgentLiveSchema to support request tagging for filtered searching. The field accepts an array of strings at the root level of agent configuration settings.

Changes Made

Schema Updates

  • File: src/lib/types/AgentLiveSchema.ts
  • Change: Added tags?: string[] field at root level of AgentLiveSchema interface
  • Location: Positioned at top level (not inside agent object) per API specification
  • Updated examples/node-agent-live/index.js to demonstrate agent tags functionality and fixed example to actually run.

Test Coverage

  • File: tests/unit/live-client-message-handling.test.ts
  • Added: 5 comprehensive test cases covering:
    • Multiple tags configuration
    • Empty tags array handling
    • Single tag configuration
    • Optional behavior (no tags)
    • Integration with other agent settings

API Usage

const config = {
  audio: { 
    input: { encoding: "linear16", sample_rate: 16000 } 
  },
  tags: ["customer-service", "priority-high", "english"],
  agent: {
    language: "en",
    speak: {
      provider: { type: "deepgram", model: "aura-2-zeus-en" }
    }
  }
};

agent.configure(config);

Implementation Details

Schema Structure

interface AgentLiveSchema extends Record<string, unknown> {
  experimental?: boolean;
  /**
   * Tags to associate with the request. Can be used for filtered searching.
   */
  tags?: string[];  // ✨ NEW FIELD
  audio: { /* ... */ };
  agent: { /* ... */ };
}

Validation

  • ✅ Field is optional (tags?:)
  • ✅ Accepts array of strings (string[])
  • ✅ Works with empty arrays (tags: [])
  • ✅ Compatible with all existing agent settings
  • ✅ TypeScript compilation successful

Testing Results

✅ All Tests Pass (43/43)
  - 38 existing tests (no regressions)
  - 5 new tags-specific tests

✅ Build Success
  - TypeScript compilation ✓
  - Webpack bundling ✓  
  - Prettier formatting ✓

✅ Schema Validation
  - Multiple tags: ✓
  - Single tag: ✓
  - Empty array: ✓
  - Optional (no tags): ✓
  - Combined with other settings: ✓

✅  Runs with Example 
 - Tags are visible in Deepgram Console ✓

What types of changes does your code introduce to the community JavaScript 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)

Further comments


Summary by CodeRabbit

  • New Features
    • Added optional tags support in live agent settings, allowing you to attach string-based tags to requests for easier filtering and organization.
  • Tests
    • Expanded test coverage to validate tags handling across multiple scenarios, including multiple tags, single tag, empty tags, absence of tags, and combination with other settings.
  • Chores
    • Updated the Node live agent example to include a new development dependency to support fetch in development workflows.

@jpvajda jpvajda requested a review from lukeocodes July 21, 2025 23:17
@coderabbitai

coderabbitai Bot commented Jul 21, 2025

Copy link
Copy Markdown
Contributor

Walkthrough

Added optional tags?: string[] to AgentLiveSchema. Introduced unit tests verifying client.configure accepts and transmits tags in settings. Updated example package.json to include cross-fetch as a devDependency. No other functional changes.

Changes

Cohort / File(s) Summary of changes
Type Definitions
src/lib/types/AgentLiveSchema.ts
Added optional property tags?: string[] to AgentLiveSchema.
Unit Tests
tests/unit/live-client-message-handling.test.ts
Added "tags configuration" tests ensuring Settings messages include tags across multiple scenarios.
Examples Config
examples/node-agent-live/package.json
Added devDependency cross-fetch ^4.1.0; no other changes to scripts or metadata.

Sequence Diagram(s)

sequenceDiagram
  participant App
  participant Client
  participant Connection

  App->>Client: configure({ tags: ["a","b"], ... })
  Client->>Connection: send(JSON.stringify({ type: "Settings", ... , tags: ["a","b"] }))
  Connection-->>Client: ack/continue
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

Suggested reviewers

  • naomi-lgbt
  • lukeocodes

📜 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 95224d6 and a55a3c9.

📒 Files selected for processing (3)
  • examples/node-agent-live/package.json (1 hunks)
  • src/lib/types/AgentLiveSchema.ts (1 hunks)
  • tests/unit/live-client-message-handling.test.ts (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
  • examples/node-agent-live/package.json
  • src/lib/types/AgentLiveSchema.ts
  • tests/unit/live-client-message-handling.test.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: Test Browser Builds
✨ Finishing Touches
  • 📝 Generate Docstrings
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch feat/agent-tags

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Explain this complex logic.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai generate unit tests to generate unit tests for this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@codecov-commenter

codecov-commenter commented Jul 21, 2025

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.17%. Comparing base (6634e40) to head (a55a3c9).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #423   +/-   ##
=======================================
  Coverage   75.17%   75.17%           
=======================================
  Files          26       26           
  Lines        1152     1152           
  Branches      292      292           
=======================================
  Hits          866      866           
  Misses        286      286           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jpvajda

jpvajda commented Aug 1, 2025

Copy link
Copy Markdown
Contributor Author

I validated the approach in JS and it was correct so this is ready for review @lukeocodes

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
examples/node-agent-live/index.js (1)

75-122: LGTM! Well-structured audio streaming with good lifecycle management.

The implementation properly handles stream lifecycle, includes appropriate timeouts, and provides good error handling. The demonstration effectively showcases the tags feature integration.

Consider these minor improvements for production robustness:

  1. Make the stream duration configurable
  2. Add fallback audio sources in case the BBC stream is unavailable
  3. Add retry logic for network failures
+const STREAM_DURATION = process.env.STREAM_DURATION || 15000;
+const AUDIO_SOURCES = [
+  "http://stream.live.vc.bbcmedia.co.uk/bbc_world_service",
+  "https://example.com/fallback-stream" // Add fallback sources
+];
📜 Review details

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

📥 Commits

Reviewing files that changed from the base of the PR and between bf7c88b and 8fc0119.

📒 Files selected for processing (2)
  • examples/node-agent-live/index.js (1 hunks)
  • examples/node-agent-live/package.json (1 hunks)
✅ Files skipped from review due to trivial changes (1)
  • examples/node-agent-live/package.json
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: Test Browser Builds
🔇 Additional comments (5)
examples/node-agent-live/index.js (5)

8-16: LGTM! Excellent defensive programming.

The explicit API key validation with helpful error messages and usage instructions is a great improvement for the example. Early validation prevents confusing runtime errors later.


40-46: LGTM! Good error handling approach.

The specific handling of timeout errors with appropriate fallback for other error types provides a better user experience and debugging information.


52-73: LGTM! Excellent demonstration of the new tags feature.

The configuration correctly implements the new tags property at the root level as specified in the API. The example tags and comprehensive agent configuration provide a clear demonstration of the feature usage.


124-143: LGTM! Comprehensive event handling with great UX.

The event handlers provide excellent visibility into the agent conversation lifecycle. The descriptive logging with emoji makes the example output clear and engaging for developers.


5-5: LGTM! Appropriate dependency for Node.js compatibility.

Adding cross-fetch ensures compatibility across different Node.js versions where native fetch might not be available.

Comment thread examples/node-agent-live/index.js Outdated
@jpvajda

jpvajda commented Aug 2, 2025

Copy link
Copy Markdown
Contributor Author

I fixed the agent example it runs successfully now and tags are sent correctly

Comment thread examples/node-agent-live/package.json Outdated
@jpvajda jpvajda requested a review from lukeocodes August 4, 2025 22:00
@jpvajda jpvajda mentioned this pull request Aug 4, 2025
lukeocodes
lukeocodes previously approved these changes Aug 6, 2025

@lukeocodes lukeocodes left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove the change to the example and then this is good

Comment thread examples/node-agent-live/index.js
@jpvajda

jpvajda commented Aug 11, 2025

Copy link
Copy Markdown
Contributor Author

@lukeocodes I updated the example from main, back to you.

@jpvajda

jpvajda commented Oct 8, 2025

Copy link
Copy Markdown
Contributor Author

Closing as we'll opt to generate this feature from the API Spec in the next major release of this SDK.

@jpvajda jpvajda closed this Oct 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants