DEV Community

Cover image for Introduction to OpenAI Agent SDK
Asad Hussain
Asad Hussain

Posted on

Introduction to OpenAI Agent SDK

#ai #agents #openai #github

What is an AI Agent?

An AI Agent is a system that can think, decide, and perform actions on behalf of a user.

Unlike a normal chatbot that only responds with text, an AI agent can:

  • Understand a user’s request
  • Decide what action is needed
  • Use external tools (like APIs, databases, or functions)
  • Return useful, real-world results

Think of it like this:

A chatbot talks.
An AI Agent works.

For example:

  • A chatbot may tell you how to check GitHub followers
  • An AI Agent can actually fetch the follower count for you automatically

This makes AI agents far more powerful for real applications.

What is the OpenAI Agent SDK?

The OpenAI Agent SDK helps developers build AI agents easily using JavaScript or TypeScript.

Instead of manually handling prompts, tool calling, and decision-making, the SDK provides a clean structure to:

  • Create agents
  • Define tools
  • Let agents use those tools automatically
  • Run user queries through the agent

This makes development faster, cleaner, and easier to scale.

How Does an AI Agent Work?

The flow usually looks like this:

User Query → Agent → Tool Selection → Tool Execution → Final Answer
Enter fullscreen mode Exit fullscreen mode

Example Flow

Suppose the user says:

Hey agent, my GitHub ID is Asad-bot07
Enter fullscreen mode Exit fullscreen mode

The agent will:

  1. Understand that GitHub information is needed
  2. Decide to use a GitHub tool
  3. Call the GitHub API
  4. Fetch the follower count
  5. Return the final answer to the user

This is exactly what your project does.

What Are Tools?

A Tool is a function the agent can use to perform actions.

Tools help agents interact with the outside world.

Examples of tools:

  • Fetch weather data
  • Search GitHub profiles
  • Send emails
  • Read databases
  • Process payments
  • Generate reports

Without tools, agents are limited to conversation.

With tools, agents become useful assistants.

Project Example: GitHub Stats Agent

In this example, we are building a simple AI agent that checks a GitHub user’s follower count.

The user provides a GitHub username, and the agent automatically fetches the follower count using the GitHub API.

Installation

Before building your first AI agent using the OpenAI Agent SDK, you need to install the required packages and set up your environment.

Step 1: Create a New Node.js Project 

mkdir openai-agent-sdk
cd openai-agent-sdk
npm init -y
Enter fullscreen mode Exit fullscreen mode

This creates a fresh Node.js project with a default package.json file.

Step 2: Install Required Dependencies 

npm install @openai/agents axios zod dotenv
Enter fullscreen mode Exit fullscreen mode

What each package does:

  • @openai/agents → Used to create AI agents and tools
  • axios → Used for making API requests
  • zod → Used for validating tool parameters
  • dotenv → Used for securely loading environment variables

Step 3: Create a .env File

Create a file named:

.env
Enter fullscreen mode Exit fullscreen mode

and add your OpenAI API key inside it:

OPENAI_API_KEY=your_openai_api_key_here
Enter fullscreen mode Exit fullscreen mode

This helps keep your API key secure and prevents exposing sensitive information directly in your code.

Step 4: Basic Project Structure

Your project should look something like this:

openai-agent-sdk/
│
├── node_modules/
├── .env
├── package.json
├── package-lock.json
└── index.js
Enter fullscreen mode Exit fullscreen mode

Your main agent code will be written inside index.js.

Code Breakdown

Step 1: Import Required Packages 

import { Agent, run, tool } from "@openai/agents";
import axios from "axios";
import z from "zod";
import 'dotenv/config'
Enter fullscreen mode Exit fullscreen mode

What these packages do:

@openai/agents

Used for creating agents and tools.

axios

Used to make API requests.

Here, we use it to call the GitHub API.

zod

Used for validating tool parameters.

It ensures the tool receives the correct input.

dotenv

Used for loading environment variables securely.

Step 2: Creating a Tool 

const getGitStats = tool({
  name: "get git stats",
  description: "returns the git following of the user",
Enter fullscreen mode Exit fullscreen mode

Here we define a tool called:

get git stats
Enter fullscreen mode Exit fullscreen mode

This tool is responsible for fetching GitHub follower data.

Step 3: Defining Tool Parameters 

parameters: z.object({
  userName: z.string().describe("Name of the user"),
})
Enter fullscreen mode Exit fullscreen mode

This tells the agent:

The tool requires a userName as input.

Since we use Zod, the input is validated automatically.

This prevents invalid tool usage.

Step 4: Tool Execution Logic 

execute: async function ({ userName }) {
  const url = `https://api.github.com/users/${userName}`;
  const res = await axios.get(url);
  const user = res.data;
  return `The followers of ${userName} is : ${user.followers}`;
}
Enter fullscreen mode Exit fullscreen mode

This is where the actual work happens.

What happens here:

  1. A GitHub API URL is created
  2. Axios sends a request
  3. GitHub returns user data
  4. We extract the followers value
  5. The tool returns the final response

Example output:

The followers of Asad-bot07 is : 120
Enter fullscreen mode Exit fullscreen mode

Step 5: Creating the Agent 

const getGitAgent = new Agent({
  name: "get git stats agent",
  instructions:
    "Youre an agent who takes the github username of an user and returns the git stats of the username",
  tools: [getGitStats],
});
Enter fullscreen mode Exit fullscreen mode

Now we create the actual AI agent.

This agent knows:

  • Its role
  • Its responsibility
  • Which tools it can use

The tools array connects the tool to the agent.

This means the agent can now use getGitStats() automatically.

Step 6: Running the Agent 

const query = "Hey agent, my github id is Asad-bot07";

run(getGitAgent, query).then((result) => {
  console.log(result.finalOutput);
});
Enter fullscreen mode Exit fullscreen mode

This sends the user query to the agent.

The SDK handles:

  • understanding the request
  • choosing the correct tool
  • executing the tool
  • generating the final answer

Finally:

console.log(result.finalOutput)
Enter fullscreen mode Exit fullscreen mode

prints the response.

Final Output

Run Your Project 

node index.js
Enter fullscreen mode Exit fullscreen mode

This will execute your AI agent and display the output in the terminal.

The followers of Asad-bot07 is : 120
Enter fullscreen mode Exit fullscreen mode

Simple, clean, and powerful.

Why Use OpenAI Agent SDK?

Because it helps you build real AI applications faster.

Benefits:

  • Cleaner code
  • Automatic tool calling
  • Better architecture
  • Scalable projects
  • Real-world integrations
  • Production-ready systems

Instead of writing complex logic manually, the SDK handles most of it for you.

Real-World Use Cases

You can build agents for:

  • Customer support
  • GitHub assistants
  • Personal productivity apps
  • Research assistants
  • AI coding assistants
  • Business automation
  • Finance tracking
  • CRM systems
  • SaaS products

This is just the beginning.

Conclusion

AI Agents are the future of software.

They are not just chatbots—they are systems that can think, decide, and act.

With the OpenAI Agent SDK, building these agents becomes much easier.

In this project, we created a GitHub Stats Agent that fetches follower counts using tools and API calls.

This is a simple example, but the same concept can be scaled into powerful production systems.

Once you understand Agents + Tools + Execution Flow, you can build almost anything.

And that is where the real power begins.

Next Step

Try extending this project by adding:

  • Repository count
  • Following count
  • Public gists
  • Starred repositories
  • Latest commits

This will help you understand how powerful agent-based development can become.

Source Code

You can find the complete source code for this project in the GitHub repository below:

🔗 GitHub Repository: https://github.com/snackoverflowasad/Git-Agent

Top comments (0)