The OpenAI Agents SDK for TypeScript is Missing Something—And That’s Ok

The OpenAI Agents SDK for TypeScript is now available, bringing agent capabilities previously available in Python to the JavaScript ecosystem. This gives web developers a new option for building sophisticated agentic applications.

What is the OpenAI Agents SDK?

The OpenAI Agents SDK for TypeScript is a lightweight toolkit that helps developers build AI applications with complex tool-using capabilities. It's designed with two core principles:

1. Providing enough features to be valuable, while keeping the primitives minimal for quick learning
2. Working effectively out of the box, while allowing for customization

The TypeScript version includes the same functionality as the Python SDK, with JavaScript-friendly design patterns.

Key features of the Agents SDK

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
});

const result = await run(
  agent,
  'Explain how to implement MongoDB change streams to track real-time database updates.',
);

console.log(result.finalOutput);

The SDK offers these core capabilities:

• TypeScript-first design: Use TypeScript's type system to improve developer experience.
• Agent loop: Handle the back-and-forth between the LLM and tools, managing the conversation flow automatically.
• Function tools: Convert any TypeScript function into a tool the agent can use, with automatic schema generation.
• Handoffs: Coordinate between multiple specialized agents to solve complex problems.
• Guardrails: Add validation rules that run in parallel to your agent, improving safety and reliability.
• Tracing: Monitor agent behavior with built-in visualization and debugging tools.
• Realtime agents: Support voice-based agents with features like interruption detection and context management.

The missing piece: memory

The Agents SDK provides powerful tooling for building intelligent agents. But there's no built-in memory or history persistence. It intentionally leaves conversation persistence as an implementation detail for developers to handle based on their specific requirements. And I think that was a good decision!

Adding memory capabilities enhances these agents by allowing them to remember past conversations and learn from previous interactions—a valuable feature for creating more helpful AI assistants.

MongoDB works well with the OpenAI Agents SDK. By implementing a MongoDB-based memory system, your agents can:

1. Maintain conversation context: Remember what was discussed earlier in a conversation.
2. Recognize returning users: Personalize interactions based on previous encounters.
3. Learn from past interactions: Improve responses over time by referencing historical exchanges.
4. Track and analyze agent performance: Store conversation data for later review and optimization.

The MongoDB memory implementation

Here's how our demo project implements MongoDB as a memory provider for an OpenAI agent:

import { Agent, run, user, assistant } from '@openai/agents';
import { addToConversationHistory, getConversationHistory } from './db.js';

// Run agent with MongoDB-based memory
export const runAgentWithMemory = async (input, context) => {
  const { db, conversationId, userId } = context;

  // Store user message in MongoDB
  await addToConversationHistory(db, conversationId, 'user', input);

  // Create agent
  const agent = new Agent({
    name: 'Assistant with Memory',
    model: 'gpt-4o-mini',
    instructions: `You are a helpful assistant for user ${userId}.`
  });

  // Get conversation history from MongoDB
  const history = await getConversationHistory(db, conversationId);

  // Format history for the agent
  const messages = history.map(entry => 
    entry.role === 'user' ? user(entry.content) : assistant(entry.content)
  );

  // Run the agent with conversation history
  const result = await run(agent, messages, { context });

  // Store assistant's response in MongoDB
  if (result.finalOutput) {
    await addToConversationHistory(db, conversationId, 'assistant', result.finalOutput);
  }

  return {
    conversationId,
    finalOutput: result.finalOutput || ''
  };
};

The implementation is straightforward:

1. Each conversation is stored in MongoDB with a unique ID.
2. User and assistant messages are added to the conversation history.
3. When the agent runs, it receives the conversation history as context.
4. This allows the agent to maintain context across multiple interactions.

Benefits for TypeScript developers

The Agents SDK for TypeScript offers several advantages:

• Native TypeScript support: No need to work with Python or deal with language barriers
• Seamless integration: Works with existing JavaScript/TypeScript applications
• Web-friendly: Can be used both in Node.js backends and browser environments
• Strong typing: Uses TypeScript's type system for better developer experience
• Reduced complexity: No language bridges or complex deployment setups needed

Real-world applications

With the OpenAI Agents SDK for TypeScript and MongoDB as a memory provider, developers can create applications like:

• Customer support agents that remember previous tickets from the same customer.
• Personal assistants that learn user preferences over time.
• Education tools that track student progress and adapt to their learning style.
• Content creation helpers that maintain consistent style and tone across sessions.
• Research assistants that build on previous findings.
• Stock market analysis agents that track trading patterns and provide personalized investment recommendations based on historical performance.

Getting started

To build with the OpenAI Agents SDK for TypeScript and MongoDB:

1. Use our OpenAI Agents SDK with MongoDB template.
2. Start building intelligent, context-aware agents.

Conclusion

The OpenAI Agents SDK for TypeScript gives TypeScript developers new tools for working with AI. Adding MongoDB as a memory provider lets developers create agents that perform tasks and improve over time.

Combining the SDK's agent capabilities with MongoDB's document model creates a solid base for building AI applications. Let's see what you can build with it!

Say Hello! YouTube | Twitter | LinkedIn | Instagram | TikTok