🎤Micdrop

Write a Custom LLM Agent

The Agent class is the core abstraction for AI conversation handling in Micdrop. It provides a standardized interface for integrating various AI providers into real-time voice conversations.

Available Implementations

Overview

The Agent class is an abstract base class that extends EventEmitter (from eventemitter3) and manages:

  • Conversation history with role-based messages (system, user, assistant)
  • Streaming response generation with both stream and promise interfaces
  • Event emission for conversation state changes
  • Cancellation and cleanup mechanisms
  • Integration with logging systems
export abstract class Agent<
Options extends AgentOptions = AgentOptions,
> extends EventEmitter<AgentEvents> {
public logger?: Logger
public conversation: MicdropConversation
constructor(protected options: Options)
// Generate a streaming response with both stream and promise interfaces
answer(): Readable
// Generate answer implementation (to be implemented by subclasses)
protected abstract generateAnswer(
stream: PassThrough,
signal: AbortSignal
): Promise<void>
// Whether an answer is being generated
get isAnswering(): boolean
// Cancel the current answer, by aborting its signal
cancel(): void
}

Architecture

Core Interfaces

export interface AgentOptions {
systemPrompt: string
// Enable auto ending of the call when user asks to end the call
// You can provide a custom prompt to use instead of the default one by passing a string
autoEndCall?: boolean | string
// Enable detection of an incomplete sentence, and skip the answer (assistant waits)
// You can provide a custom prompt to use instead of the default one by passing a string
autoSemanticTurn?: boolean | string
// Ignore of the last user message when it's meaningless
// You can provide a custom prompt to use instead of the default one by passing a string
autoIgnoreUserNoise?: boolean | string
// Extract a value from the answer
// Value must be at the end of the answer, in JSON or between tags
extract?: ExtractJsonOptions | ExtractTagOptions
// Function called before any answer is generated
// Return true to skip generation, or a text to answer it instead
onBeforeAnswer?: (
this: Agent,
stream: Writable
) => void | boolean | string | Promise<void | boolean | string>
}
export interface AgentEvents {
Message: [MicdropConversationItem]
CancelLastUserMessage: []
SkipAnswer: []
EndCall: []
ToolCall: [MicdropToolCall]
Failed: []
}
export interface MicdropConversationMessage {
role: 'system' | 'user' | 'assistant'
content: string
metadata?: any
}
export interface MicdropToolCall {
name: string
parameters: any
output: any
}
export interface ExtractOptions {
callback?: (value: string) => void
saveInMetadata?: boolean
}
export interface ExtractJsonOptions extends ExtractOptions {
json: true
callback?: (value: any) => void
}
export interface ExtractTagOptions extends ExtractOptions {
startTag: string
endTag: string
}

Conversation Management

The Agent maintains a conversation history as an array of messages:

public conversation: MicdropConversation

The conversation is initialized with the system prompt:

constructor(protected options: Options) {
super()
this.conversation = [{ role: 'system', content: options.systemPrompt }]
}

Abstract Methods

generateAnswer(stream: PassThrough, signal: AbortSignal): Promise<void>

Implementation method for generating answers. This is what subclasses should implement.

Implementation Requirements:

  • Write response chunks to the provided stream
  • Add the complete response to conversation history when finished with addAssistantMessage()
  • Pass signal to the API request, so a cancelled answer stops costing tokens
  • Check signal.aborted before a retry and before adding a message: once it is aborted, the answer is no longer wanted

The signal is aborted when the answer is cancelled, and when a new answer replaces it.

Cancellation

cancel(): void

Cancels the current answer by aborting its signal. An agent that only relies on the signal has nothing to override.

An agent that holds more than the request, a queue or a connection of its own, overrides it and calls super.cancel():

cancel() {
super.cancel()
this.queue = []
}

Public Methods

answer(): Readable

Generates a streaming response based on the current conversation history.

Return Value: A Readable stream that emits text chunks in real-time

Behavior:

  • Calls onBeforeAnswer hook if provided
  • If hook returns true, skips answer generation
  • If hook returns a text, speaks it and adds it to the conversation as the answer, without generating
  • Otherwise calls generateAnswer() implementation, with the signal of this answer
  • Aborts the previous answer, if one was still being generated

addMessage(role: 'user' | 'assistant' | 'system', text: string, metadata?: MicdropAnswerMetadata)

Add any type of message with content to the conversation and emit the Message event.

A message whose text is empty or made of whitespace is ignored, so a turn where the LLM only called a tool leaves no empty message behind in the conversation.

agent.addMessage('assistant', 'Hello there!')

addUserMessage(text: string, metadata?: MicdropAnswerMetadata)

Adds a user message to the conversation history and emits a Message event.

agent.addUserMessage('Hello, how are you?')

addAssistantMessage(text: string, metadata?: MicdropAnswerMetadata)

Adds an assistant message to the conversation history and emits a Message event.

agent.addAssistantMessage("I'm doing well, thank you!")

addTool<Schema extends z.ZodObject>(tool: Tool<Schema>)

Adds a custom tool to the agent’s available tools.

import { z } from 'zod'
const weatherTool = {
name: 'get_weather',
description: 'Get current weather for a location',
parameters: z.object({
location: z.string().describe('The city name'),
}),
execute: async ({ location }) => {
// Fetch weather data
return { temperature: 22, conditions: 'sunny' }
},
}
agent.addTool(weatherTool)

removeTool(name: string)

Removes a tool from the agent’s available tools by name.

agent.removeTool('get_weather')

getTool(name: string): Tool | undefined

Retrieves a tool by name from the agent’s available tools.

const tool = agent.getTool('get_weather')
if (tool) {
console.log('Weather tool is available')
}

addToolMessage(message: MicdropConversationToolCall | MicdropConversationToolResult)

Adds a tool call or tool result message to the conversation.

// Add tool call
agent.addToolMessage({
role: 'tool_call',
toolCallId: 'call_123',
toolName: 'get_weather',
parameters: JSON.stringify({ location: 'Paris' }),
})
// Add tool result
agent.addToolMessage({
role: 'tool_result',
toolCallId: 'call_123',
toolName: 'get_weather',
output: JSON.stringify({ temperature: 22, conditions: 'sunny' }),
})

extract(message: string): { message: string; metadata?: MicdropAnswerMetadata }

Extracts structured data from a message based on the configured extraction options. Returns the cleaned message and any extracted metadata.

// With JSON extraction
const result = agent.extract('The answer is 42. {"score":42}')
// Returns: { message: 'The answer is 42.', metadata: { extracted: { score: 42 } } }
// With tag extraction
const result = agent.extract('The answer is 42. <score>42</score>')
// Returns: { message: 'The answer is 42.', metadata: { extracted: '42' } }

It is called automatically when the extract option is provided. It is public so that you can use it to extract data from the answer before adding it to the conversation, if you really need to.

destroy()

Cleans up the agent instance:

  • Removes all event listeners
  • Calls cancel() to stop ongoing operations
  • Logs destruction
agent.destroy()

Protected Methods

endCall()

Emits the EndCall event to signal that the conversation should end.

cancelLastUserMessage()

Removes the last user message from the conversation history (if it exists) and emits the CancelLastUserMessage event.

skipAnswer()

Emits the SkipAnswer event to indicate the agent is skipping the current response.

getDefaultTools(): Tool[]

Returns the default tools based on the agent’s configuration options (autoEndCall, autoSemanticTurn, autoIgnoreUserNoise).

executeTool(toolCall: MicdropConversationToolCall): Promise<{ output: any; skipAnswer?: boolean }>

Executes a tool call and handles the result. This method:

  • Finds the tool by name
  • Adds the tool call to conversation history
  • Executes the tool with the provided parameters
  • Adds the tool result to conversation history
  • Emits a ToolCall event if the tool has emitOutput: true
  • Returns the output and whether to skip the answer

getExtractOptions(): ExtractTagOptions | undefined

Returns the extraction options configured for the agent, converting JSON extraction to tag-based extraction.

log(...message: any[])

Logs messages using the attached logger if available.

agent.log('Processing user message:', userInput)

Public Properties

conversation: MicdropConversation

The full conversation history, starting with the system message.

tools: Tool[]

Array of available tools that the agent can use.

isAnswering: boolean

Whether an answer is being generated, from answer() until its stream ends or the answer is cancelled.

Protected Properties

options: Options

The configuration options passed to the agent constructor.

Events

The Agent emits the following events:

Message

Emitted when a message, a tool call or a tool result is added to the conversation.

agent.on('Message', (message: MicdropConversationItem) => {
console.log('New conversation item:', message)
})

ToolCall

Emitted when a tool declared with emitOutput has run, with its parameters and its output.

agent.on('ToolCall', (toolCall: MicdropToolCall) => {
console.log(`Tool ${toolCall.name} returned`, toolCall.output)
})

CancelLastUserMessage

Emitted when the last user message is cancelled.

agent.on('CancelLastUserMessage', () => {
console.log('Last user message was cancelled')
})

SkipAnswer

Emitted when the agent decides to skip answering.

agent.on('SkipAnswer', () => {
console.log('Agent skipped answering')
})

EndCall

Emitted when the agent determines the call should end.

agent.on('EndCall', () => {
console.log('Call should end')
})

Failed

Emitted when the agent gives up generating an answer, for example after exhausting its retries. FallbackAgent listens to it to switch to the next agent.

agent.on('Failed', () => {
console.error('Agent failed to answer')
})

Debug Logging

Enable detailed logging for development:

import { Logger } from '@micdrop/server'
agent.logger = new Logger('CustomAgent')

Custom Agent Implementation

Creating a Custom Agent Implementation

import { Agent, AgentOptions } from '@micdrop/server'
import { PassThrough, Writable } from 'stream'
interface CustomAgentOptions extends AgentOptions {
apiKey: string
model?: string
settings?: any // Provider-specific settings
}
const DEFAULT_MODEL = 'gpt-5.6-terra'
class CustomAgent extends Agent<CustomAgentOptions> {
constructor(options: CustomAgentOptions) {
super(options)
}
protected async generateAnswer(
stream: PassThrough,
signal: AbortSignal
): Promise<void> {
try {
// Build messages for your AI provider
const messages = this.conversation.map((msg) => ({
role: msg.role,
content: msg.content,
}))
// Make API call to your AI provider
const response = await fetch('https://api.your-provider.com/chat', {
method: 'POST',
headers: {
Authorization: `Bearer ${this.options.apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
messages,
model: this.options.model || DEFAULT_MODEL,
stream: true,
...this.options.settings,
}),
// Stops the request as soon as the answer is cancelled
signal,
})
if (!response.ok) {
throw new Error(`API request failed: ${response.statusText}`)
}
const reader = response.body?.getReader()
let fullResponse = ''
while (reader) {
const { done, value } = await reader.read()
if (done) break
// Parse streaming response (format depends on your provider)
const chunk = new TextDecoder().decode(value)
if (chunk) {
this.log(`Answer chunk: "${chunk}"`)
stream.write(chunk)
fullResponse += chunk
}
}
// A cancelled answer stays out of the conversation
if (!signal.aborted) {
this.addAssistantMessage(fullResponse)
}
} catch (error: any) {
// Aborting the request throws, which is no failure
if (!signal.aborted) console.error('[CustomAgent] Error:', error)
}
}
}

Using Custom Agent with MicdropServer

// Create custom agent
const agent = new CustomAgent({
apiKey: process.env.YOUR_API_KEY || '',
systemPrompt: 'You are a helpful assistant.',
model: 'your-model-name',
})
// Add logging
agent.logger = new Logger('CustomAgent')
// Setup event handlers
agent.on('Message', (message) => {
console.log(`${message.role}: ${message.content}`)
})
// Create server with custom agent
new MicdropServer(socket, {
agent,
// ...other options
})

Simple Echo Agent Example

import { Agent, MicdropConversationMessage } from '@micdrop/server'
import { PassThrough } from 'stream'
class EchoAgent extends Agent {
protected async generateAnswer(
stream: PassThrough,
signal: AbortSignal
): Promise<void> {
// Get the last user message
const lastUserMessage = this.conversation
.filter((msg) => msg.role === 'user')
.pop() as MicdropConversationMessage
if (lastUserMessage) {
// Simulate a delay before responding
await new Promise((resolve) => setTimeout(resolve, 100))
if (signal.aborted) return
const response = `You said: "${lastUserMessage.content}"`
// Stream the response
stream.write(response)
// Add to conversation
this.addAssistantMessage(response)
}
}
}
// Usage
const echoAgent = new EchoAgent({
systemPrompt: 'You are an echo agent that repeats what users say.',
})
echoAgent.addUserMessage('Hello!')
const stream = echoAgent.answer()
stream.on('data', (chunk) => {
console.log('Chunk:', chunk.toString())
})
stream.on('end', async () => {
console.log('Stream ended')
echoAgent.destroy()
})