🎤Micdrop

OpenAI GPT Agent in Node.js

OpenaiAgent answers with OpenAI models through the Responses API. It works with any speech to text and text to speech.

Installation

Terminal window
npm install @micdrop/openai

The same package also provides a speech to text, a text to speech, the Realtime API and a classifier. The providers page shows what every provider covers.

Usage with MicdropServer

import { OpenaiAgent } from '@micdrop/openai'
import { MicdropServer } from '@micdrop/server'
const agent = new OpenaiAgent({
apiKey: process.env.OPENAI_API_KEY || '',
model: 'gpt-4o', // Default model
systemPrompt: 'You are a helpful assistant',
// Custom OpenAI Responses API settings (optional)
settings: {
temperature: 0.7,
max_output_tokens: 150,
},
})
// Use with MicdropServer
new MicdropServer(socket, {
agent,
// ... other options
})

Usage without MicdropServer

import { OpenaiAgent } from '@micdrop/openai'
const agent = new OpenaiAgent({
apiKey: process.env.OPENAI_API_KEY || '',
systemPrompt: 'You are a helpful assistant',
})
agent.on('Message', (message) => console.log('Message:', message))
agent.addUserMessage('Hello, what can you do?')
// The answer is a text stream, written as the model generates it
agent.answer().on('data', (chunk) => process.stdout.write(chunk))

Events

EventPayloadDescription
MessageMicdropConversationItemA message, a tool call or a tool result was added to the conversation.
ToolCallMicdropToolCallA tool declared with emitOutput ran, with its parameters and output.
CancelLastUserMessagenoneThe last user message was dropped because it carried no intent.
SkipAnswernoneThe agent stays silent and waits for the user to finish their sentence.
EndCallnoneThe agent decided that the call is over.
FailednoneThe agent gave up generating an answer after its retries.

See the Agent interface for the full contract.

Options

OptionTypeDefaultDescription
apiKeystringRequired*Your OpenAI API key (required if openai not provided)
openaiOpenAIOptionalOpenAI instance (alternative to apiKey)
modelstring'gpt-4o'OpenAI model to use
systemPromptstringRequiredSystem prompt for the agent
retryDelaynumber1000Delay in milliseconds between retry attempts
maxRetrynumber3Maximum number of retries on API failures
maxStepsnumber5Maximum number of steps (for tool calls)
autoEndCallboolean | stringfalseAuto-detect when user wants to end call
autoSemanticTurnboolean | stringfalseHandle incomplete user sentences
autoIgnoreUserNoiseboolean | stringfalseFilter meaningless user sounds
extractExtractOptionsundefinedExtract a JSON object from responses
onBeforeAnswerfunctionundefinedHook called before answer generation, returns true to skip it or a text to answer instead
settingsobject{}Additional OpenAI Responses API parameters

A request that fails before writing anything is retried, up to maxRetry times. Once text reached the stream or a tool ran, the answer keeps what it got: the text already said goes in the conversation as the answer, so a retry never says it twice. Cancelling the answer also stops the retries.

Reasoning

A model that reasons thinks before its first word, which delays every answer. OpenaiAgent leaves the level to the model, and for a voice call the lowest level it accepts is usually the right one: none for GPT-5.1 and later, minimal for the first GPT-5 models, low for the o series and the Codex models. The default gpt-4o does not reason, and refuses the setting.

const agent = new OpenaiAgent({
apiKey: process.env.OPENAI_API_KEY || '',
model: 'gpt-5.2',
systemPrompt: 'You are a helpful assistant',
settings: { reasoning: { effort: 'none' } },
})

The OpenAI Agent supports adding and removing custom tools to extend its capabilities. For detailed information about tool management, see the Tools documentation.

Advanced Features

The OpenAI Agent supports advanced features for improved conversation handling:

Langfuse Integration

You can integrate Langfuse for observability by using the openai option with a Langfuse-wrapped OpenAI client:

import { OpenaiAgent } from '@micdrop/openai'
import { Langfuse, observeOpenAI } from 'langfuse'
import OpenAI from 'openai'
// Initialize Langfuse
const langfuse = new Langfuse({
secretKey: process.env.LANGFUSE_SECRET_KEY,
publicKey: process.env.LANGFUSE_PUBLIC_KEY,
baseUrl: process.env.LANGFUSE_BASE_URL, // Optional, defaults to https://cloud.langfuse.com
})
// Get system prompt from Langfuse
const systemPrompt = await langfuse.getPrompt('voice-assistant-system-prompt')
// Create OpenAI client and wrap with Langfuse observability
const openai = observeOpenAI(
new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
{
sessionId: 'session-123',
userId: 'user-456',
}
)
// Create agent with Langfuse-wrapped OpenAI client
const agent = new OpenaiAgent({
openai,
model: 'gpt-4o',
systemPrompt: systemPrompt.prompt,
})

This integration will automatically track all OpenAI API calls, token usage, and conversation flows in your Langfuse dashboard with session and user context.

Listing models

OpenaiAgent.listModels() returns the chat models that can answer a call. OpenAI only gives the ids of its models, so the list is sorted from their names.

const models = await OpenaiAgent.listModels({
apiKey: process.env.OPENAI_API_KEY || '',
})

It returns MicdropModel objects: id, the value the model option takes, then when the provider says it name, description, aliases, languages, reasoning for a model that can reason, and deprecated with its shutdownDate. The list is fetched once, then shared by every call of the process for a day. Pass refresh: true to fetch it again.