Building Intelligent AI Agents with OpenAI: From Raw API to Official Agents SDK

Introduction

Artificial Intelligence agents are revolutionizing how we interact with technology. Unlike traditional chatbots that simply respond to queries, AI agents can understand context, make decisions, and use tools to accomplish complex tasks autonomously. This project demonstrates how to build progressively sophisticated AI agents using both the OpenAI API and the official OpenAI Agents SDK.

Whether you’re a beginner exploring AI development or an experienced developer looking to integrate intelligent agents into your applications, this sample project provides practical, hands-on examples comparing two approaches: custom implementation using raw OpenAI API and using the official Agents SDK.

What is an AI Agent?

An AI agent is an autonomous system powered by a language model that can:

• Understand natural language instructions
• Make intelligent decisions about which tools to use
• Execute functions to interact with external systems
• Reason about results and provide meaningful responses
• Collaborate with other agents to solve complex problems

Think of it as giving your AI assistant a toolbox. Instead of just talking, it can now check the weather, perform calculations, search databases, and much more.

Project Overview

The OpenAI AgentKit Sample Project demonstrates six levels of AI agent sophistication across two implementation approaches:

OpenAI API Approach (Custom Implementation)

1. Basic Agent

A foundational implementation showing how to set up OpenAI’s Chat Completions API.

What you’ll learn:

• Setting up the OpenAI client
• Configuring system and user messages
• Managing model parameters (temperature, tokens)
• Handling API responses

2. Agent with Tools

Introduces function calling where the agent decides when and how to use specific tools.

Available Tools:

• Weather Tool: Retrieves current weather information
• Calculator Tool: Performs mathematical operations
• Time Tool: Gets current date and time across timezones

3. Advanced Agent

Production-ready example with sophisticated features including detailed logging, error handling, and multiple complex tools.

Enhanced Capabilities:

• Wikipedia search integration
• Sentiment analysis
• Timezone-aware time retrieval
• Comprehensive error handling
• Performance statistics and logging

OpenAI Agents SDK Approach (Official Framework)

4. SDK Basic Agent

Simple agent using the official OpenAI Agents SDK with automatic agent loop and simplified API.

Key Features:

• Uses Agent and run from @openai/agents
• Automatic conversation management
• Clean, minimal code

5. SDK Agent with Tools

Agent with tools using proper SDK conventions and automatic schema generation.

Tools:

• Weather lookup with Zod validation
• Mathematical calculations
• Time zone support

Key Features:

• Tools defined with tool() helper
• Zod-powered parameter validation
• Automatic schema generation from TypeScript types

6. SDK Multi-Agent System

Sophisticated multi-agent system with specialized agents and handoffs.

Agents:

• WeatherExpert: Handles weather queries
• MathExpert: Performs calculations
• KnowledgeExpert: Searches knowledge base
• Coordinator: Routes requests to specialists

Technology Stack

OpenAI API
GPT-4o-mini model for intelligent responses
@openai/agents
Official OpenAI Agents SDK
Zod
Runtime type validation and schema generation
Node.js
Runtime environment (22+ required for SDK)
Express.js
Web server framework
dotenv
Environment variable management

Getting Started

Prerequisites

• Node.js 22 or higher (required for OpenAI Agents SDK)
• OpenAI API key (get one at https://platform.openai.com/api-keys)

Installation

1. Clone or download the project

cd openai-agentkit-sample

2. Install dependencies

npm install

This will install:

• openai – Raw OpenAI API client
• @openai/agents – Official Agents SDK
• zod – Schema validation
• Other dependencies

3. Configure environment variables

cp .env.example .env

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=sk-your-actual-api-key-here

Running the Examples

Start the web server:

npm start

Open http://localhost:3000 in your browser

Run OpenAI API examples:

npm run example:basic      # Basic agent
npm run example:tools      # Agent with tools
npm run example:advanced   # Advanced agent

Run OpenAI Agents SDK examples:

npm run example:sdk-basic  # SDK basic agent
npm run example:sdk-tools  # SDK with tools
npm run example:sdk-multi  # Multi-agent system

Comparing the Two Approaches

OpenAI API (Custom Implementation)

Pros:

• Full control over every aspect
• Deep understanding of agent mechanics
• Maximum flexibility
• No framework constraints

Cons:

• More code to write and maintain
• Manual agent loop implementation
• Manual tool schema definition
• More error-prone

Example – Tool Definition (Raw API):

const weatherTool = {
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get the current weather in a given location',
    parameters: {
      type: 'object',
      properties: {
        location: {
          type: 'string',
          description: 'The city and country',
        },
        unit: {
          type: 'string',
          enum: ['celsius', 'fahrenheit'],
        },
      },
      required: ['location'],
    },
  },
};
// Manual tool execution
function executeFunction(functionName, args) {
  switch (functionName) {
    case 'get_weather':
      return getWeather(args.location, args.unit);
    // ... more cases
  }
}

OpenAI Agents SDK (Official Framework)

Pros:

• Less code, faster development
• Automatic agent loop
• Automatic schema generation from Zod
• Built-in handoffs for multi-agent systems
• Production-ready patterns
• Type-safe with TypeScript

Cons:

• Less control over internals
• Framework learning curve
• Tied to SDK conventions
• Node.js 22+ requirement

Example – Tool Definition (Agents SDK):

import { tool } from '@openai/agents';
import { z } from 'zod';
const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the current weather for a given location',
  parameters: z.object({
    location: z.string().describe('The city and country'),
    unit: z.enum(['celsius', 'fahrenheit']).optional().default('celsius'),
  }),
  async execute({ location, unit }) {
    // Tool implementation
    return JSON.stringify({ temperature: 22, condition: 'Sunny' });
  },
});
// Automatic execution - no switch statement needed!
const agent = new Agent({
  tools: [getWeatherTool],
});

Key Concepts

Function Calling / Tool Usage

Both approaches support function calling, where the AI model can “call” functions you define:

1. Define tool: Describe function, parameters, and purpose
2. Model decides: Model automatically decides when to use tools
3. Execute tool: Your code executes the function
4. Return result: Send result back to model
5. Final response: Model uses result to create answer

OpenAI Agents SDK Advantages

The Agents SDK provides several powerful features:

Automatic Schema Generation:

// SDK automatically generates JSON schema from Zod!
z.object({
  city: z.string(),
  unit: z.enum(['celsius', 'fahrenheit']).optional(),
})

Agent Handoffs:

const coordinator = new Agent({
  handoffs: [weatherAgent, mathAgent, knowledgeAgent],
});
// Coordinator can automatically route to specialists

Built-in Agent Loop:

// SDK handles the entire conversation loop
const result = await run(agent, "What's the weather in Hanoi?");
console.log(result.finalOutput);

Practical Use Cases

Customer Service Automation

• Answer questions using knowledge bases
• Check order status
• Process refunds
• Escalate to human agents
• Route to specialized agents

Personal Assistant Applications

• Schedule management
• Email drafting
• Research and information gathering
• Task automation
• Multi-task coordination

Data Analysis Tools

• Query databases
• Generate reports
• Perform calculations
• Visualize insights
• Collaborate across data sources

Best Practices

1. Clear Tool Descriptions

Make function descriptions detailed and specific:

Good:
description: 'Get the current weather including temperature, conditions, and humidity for a specific city and country'
Bad:
description: 'Get weather'

2. Use Zod for Validation (SDK)

parameters: z.object({
  email: z.string().email(),
  age: z.number().min(0).max(120),
  role: z.enum(['admin', 'user', 'guest']),
})

3. Error Handling

Always implement comprehensive error handling:

async execute({ city }) {
  try {
    const result = await weatherAPI.get(city);
    return JSON.stringify(result);
  } catch (error) {
    return JSON.stringify({ error: error.message });
  }
}

4. Tool Modularity

Create small, focused tools rather than monolithic ones:

// Good - specific tools
const getWeatherTool = tool({...});
const getForecastTool = tool({...});
// Bad - one giant tool
const weatherAndForecastAndHistoryTool = tool({...});

Multi-Agent Patterns

The Agents SDK excels at multi-agent workflows:

Specialist Pattern

const weatherExpert = new Agent({
  name: 'WeatherExpert',
  tools: [getWeatherTool],
});
const mathExpert = new Agent({
  name: 'MathExpert',
  tools: [calculateTool],
});
const coordinator = new Agent({
  handoffs: [weatherExpert, mathExpert],
});

Hierarchical Delegation

• Coordinator receives user request
• Analyzes which specialist is needed
• Hands off to appropriate agent
• Aggregates results
• Returns unified response

API Endpoints

The project includes a web server with both approaches:

Raw API:

• POST /api/chat/basic – Basic chat completion
• POST /api/chat/with-tools – Manual tool handling

Agents SDK:

• POST /api/chat/agents-sdk – SDK-powered agent with tools

When to Use Which Approach?

Use OpenAI API (Custom Implementation) When:

• You need full control and customization
• Learning how agents work at a low level
• Implementing highly custom logic
• Working with existing codebases
• Framework constraints are a concern

Use OpenAI Agents SDK When:

• Building production applications quickly
• Need multi-agent workflows
• Want type-safe tool definitions
• Prefer less boilerplate code
• Following best practices matters
• Team collaboration is important

Performance Considerations

• Model Selection: GPT-4o-mini offers great balance of capability and cost
• Caching: Consider caching frequent queries
• Async Operations: Use Promise.all() for parallel tool execution
• Response Streaming: Implement for better UX
• Rate Limiting: Monitor and manage API rate limits

Troubleshooting

Issue: “Invalid API Key”

• Verify .env file contains correct API key
• Check key is active in OpenAI dashboard

Issue: Tools Not Being Called

• Ensure tool descriptions are clear and specific
• Try more explicit user prompts
• Check parameter schemas are correctly formatted

Issue: “Unsupported tool type”

• Use tool() helper with Agents SDK
• Ensure Zod schemas are properly defined
• Check you’re importing from @openai/agents

Resources

• OpenAI API Documentation
• Function Calling Guide
• OpenAI Node.js Library
• OpenAI Agents SDK Documentation
• OpenAI Agents SDK GitHub
• AgentKit Official Announcement
• Zod Documentation

Comparison Table

Conclusion

This project demonstrates two powerful approaches to building AI agents:

1. Raw OpenAI API: Provides deep understanding and maximum control. Perfect for learning and custom implementations.
2. OpenAI Agents SDK: Offers productivity, type safety, and production-ready patterns. Ideal for building real applications quickly.

Both approaches have their place. Start with the SDK for production work, but understanding the raw API approach gives you insights into how agents actually work.

Next Steps

1. Experiment: Run all six examples
2. Compare: Notice the differences in code complexity
3. Customize: Create your own tools
4. Integrate: Connect real APIs
5. Deploy: Move to production with proper error handling
6. Scale: Implement multi-agent systems for complex tasks

Contributing

Contributions, suggestions, and improvements are welcome! Feel free to:

• Report issues
• Submit pull requests
• Share your custom tools
• Suggest new examples

License

MIT License – Feel free to use this project for learning, development, or commercial purposes.

Ready to build your own AI agents?
Clone the repository, follow the setup instructions, and start with whichever approach fits your needs. The future of intelligent automation is in your hands!