Inject agent message missing method

[jpvajda]

Bug Report: Missing inject_agent_message Method in Agent WebSocket Client

Summary

The Deepgram Python SDK has all the infrastructure for agent message injection (InjectAgentMessageOptions, events, response handling) but is missing the actual inject_agent_message method implementation in both sync and async agent WebSocket clients.

Environment

• SDK Version: Current main branch
• Python Version: 4.6.0
• OS: darwin 24.5.0
• Files Affected:
  • deepgram/clients/agent/v1/websocket/client.py
  • deepgram/clients/agent/v1/websocket/async_client.py

Issue Description

The SDK imports InjectAgentMessageOptions but provides no corresponding inject_agent_message method to use it, while the parallel inject_user_message method exists and works correctly.

Expected Behavior

The SDK should provide both:

• ✅ inject_user_message(options: InjectUserMessageOptions) - EXISTS
• ❌ inject_agent_message(options: InjectAgentMessageOptions) - MISSING

Actual Behavior

Attempting to call inject_agent_message results in:

AttributeError: 'AgentWebSocketClient' object has no attribute 'inject_agent_message'

Steps to Reproduce

1. Create an agent WebSocket client
2. Try to call inject_agent_message method
3. Observe the AttributeError

from deepgram import DeepgramClient, InjectAgentMessageOptions

client = DeepgramClient()
agent_client = client.agent.websocket.v("1")

# This works (inject_user_message exists)
user_options = InjectUserMessageOptions(content="Hello")
agent_client.inject_user_message(user_options)  # ✅ Success

# This fails (inject_agent_message missing)
agent_options = InjectAgentMessageOptions(message="Hello from agent")
agent_client.inject_agent_message(agent_options)  # ❌ AttributeError

Evidence from Codebase

1. Infrastructure EXISTS

Options Class (deepgram/clients/agent/v1/websocket/options.py:417-423):

@dataclass
class InjectAgentMessageOptions(BaseResponse):
    """
    The client can send an InjectAgentMessage to immediately trigger an agent statement.
    """
    type: str = str(AgentWebSocketEvents.InjectAgentMessage)
    message: str = field(default="")

Event Enum (deepgram/clients/agent/enums.py:33):

InjectAgentMessage: str = "InjectAgentMessage"

Response Handling (deepgram/clients/agent/v1/websocket/response.py:100-109):

@dataclass
class InjectionRefusedResponse(BaseResponse):
    """
    The server will send an InjectionRefused message when an InjectAgentMessage
    request is ignored because it arrived while the user was speaking...
    """

2. Method Implementation MISSING

Sync Client (deepgram/clients/agent/v1/websocket/client.py):

# Line 35: InjectAgentMessageOptions imported ✅
from .options import (
    InjectAgentMessageOptions,  # ✅ IMPORTED
    InjectUserMessageOptions,   # ✅ IMPORTED
    # ...
)

# Line 619: inject_user_message method exists ✅
def inject_user_message(self, options: InjectUserMessageOptions) -> bool:
    """Injects a user message to trigger an agent response from text input."""
    # ... implementation exists ...

# MISSING: inject_agent_message method should be here ❌
# def inject_agent_message(self, options: InjectAgentMessageOptions) -> bool:
#     """Injects an agent message to immediately trigger an agent statement."""
#     # ... NO IMPLEMENTATION FOUND ...

Async Client (deepgram/clients/agent/v1/websocket/async_client.py):

# Line 35: InjectAgentMessageOptions imported ✅
from .options import (
    InjectAgentMessageOptions,  # ✅ IMPORTED
    InjectUserMessageOptions,   # ✅ IMPORTED
    # ...
)

# Line 623: inject_user_message method exists ✅
async def inject_user_message(self, options: InjectUserMessageOptions) -> bool:
    """Injects a user message to trigger an agent response from text input."""
    # ... implementation exists ...

# MISSING: inject_agent_message method should be here ❌
# async def inject_agent_message(self, options: InjectAgentMessageOptions) -> bool:
#     """Injects an agent message to immediately trigger an agent statement."""
#     # ... NO IMPLEMENTATION FOUND ...

Test Evidence

Previous test runs show the exact error:

{
  "error": "'AgentWebSocketClient' object has no attribute 'inject_agent_message'",
  "file": "tests/response_data/agent/websocket/inject_agent_message-800037f7-error.json"
}

Impact Assessment

• Severity: Medium - Feature partially implemented
• User Impact: Users cannot inject agent messages despite having the options class
• API Completeness: SDK doesn't match its own API specification
• Developer Experience: Confusing to have options class but no method to use it

Suggested Fix

Add the missing methods to both client files:

Sync Client (client.py)

def inject_agent_message(self, options: InjectAgentMessageOptions) -> bool:
    """
    Injects an agent message to immediately trigger an agent statement.
    """
    self._logger.spam("AgentWebSocketClient.inject_agent_message ENTER")

    if not isinstance(options, InjectAgentMessageOptions):
        self._logger.error("options must be of type InjectAgentMessageOptions")
        self._logger.spam("AgentWebSocketClient.inject_agent_message LEAVE")
        return False

    self._logger.notice("Sending InjectAgentMessage...")
    ret = self.send(str(options))

    if not ret:
        self._logger.error("inject_agent_message failed")
        self._logger.spam("AgentWebSocketClient.inject_agent_message LEAVE")
        return False

    self._logger.notice("inject_agent_message succeeded")
    self._logger.spam("AgentWebSocketClient.inject_agent_message LEAVE")
    return True

Async Client (async_client.py)

async def inject_agent_message(self, options: InjectAgentMessageOptions) -> bool:
    """
    Injects an agent message to immediately trigger an agent statement.
    """
    self._logger.spam("AsyncAgentWebSocketClient.inject_agent_message ENTER")

    if not isinstance(options, InjectAgentMessageOptions):
        self._logger.error("options must be of type InjectAgentMessageOptions")
        self._logger.spam("AsyncAgentWebSocketClient.inject_agent_message LEAVE")
        return False

    self._logger.notice("Sending InjectAgentMessage...")
    ret = await self.send(str(options))

    if not ret:
        self._logger.error("inject_agent_message failed")
        self._logger.spam("AsyncAgentWebSocketClient.inject_agent_message LEAVE")
        return False

    self._logger.notice("inject_agent_message succeeded")
    self._logger.spam("AsyncAgentWebSocketClient.inject_agent_message LEAVE")
    return True

Files to Modify

1. deepgram/clients/agent/v1/websocket/client.py - Add sync inject_agent_message method
2. deepgram/clients/agent/v1/websocket/async_client.py - Add async inject_agent_message method

Test Cases to Add

After implementing the fix, add test cases to verify:

1. Method exists and is callable
2. Method accepts InjectAgentMessageOptions parameter
3. Method returns boolean success/failure
4. Method sends proper WebSocket message format
5. Method handles injection refused responses
6. Method works in both sync and async contexts

Additional Notes

• The fix should follow the exact same pattern as inject_user_message
• Both methods should have identical error handling and logging
• The implementation gap suggests this feature was planned but never completed
• This affects both the public API and internal consistency of the SDK