OpenAI AgentKit Tutorial: Step-by-Step Guide to Building AI Agents (2025)

Understanding OpenAI AgentKit

On October 6, 2025, OpenAI unveiled AgentKit at DevDay 2025—a comprehensive platform designed to democratize AI agent development. Whether you're a developer building customer support systems, an enterprise automating workflows, or a product team adding conversational experiences, AgentKit provides the tools you need to build production-ready AI agents.

AgentKit represents OpenAI's vision for making AI agents accessible to developers and enterprises of all sizes. Instead of requiring deep machine learning expertise or complex infrastructure setup, AgentKit provides a visual interface for composing agent logic, pre-built components for common patterns, and integrated tools for optimization.

What Makes AgentKit Different

Unlike traditional automation platforms that rely on rigid if-then logic, AgentKit puts AI reasoning at the center of every workflow. This enables:

AgentKit is included with standard API pricing—no additional platform fees or subscriptions required. You only pay for the API calls your agents make, making it cost-effective for projects of any size.

Four Core Components

AgentKit consists of four interconnected components that work together to provide a complete agent development platform:

Agent Builder: Visual Workflow Design

Agent Builder provides a visual canvas for designing agentic workflows without writing code. Every agent consists of nodes (individual processing steps) that can be connected in sequential or parallel patterns.

Key Features

Multi-Agent Architecture

Agent Builder supports complex multi-agent workflows where multiple AI agents collaborate to solve problems. A common pattern uses three specialized agents:

Context Variables

Agents can reference data from previous nodes using bracket notation:

// Reference workflow input
{{workflow.input_as_text}}

// Reference previous node output
{{input.output_text}}

// Reference specific fields
{{extraction_agent.skills}}
{{analysis_agent.recommendations}}

ChatKit: Embeddable Chat Experiences

ChatKit makes it simple to embed chat-based agents that feel native to your product. Deploying chat UIs for agents can be surprisingly complex—handling streaming responses, managing threads, showing the model thinking, and designing engaging in-chat experiences.

ChatKit solves these challenges with a pre-built React component that you can customize and embed in minutes.

Key Features

• Streaming Responses: Real-time message streaming with proper loading states and animations
• Thread Management: Automatic conversation thread handling with history and context retention
• Model Thinking Display: Shows agent reasoning and decision-making process to users
• In-Chat Experiences: Widget support for rich content like charts, tables, and interactive elements
• Customizable Theming: Use ChatKit Studio's playground to generate custom theme configurations
• Session Management: Schema-based configuration for user sessions and authentication

Quick Start with ChatKit

Setting up ChatKit takes less than 5 minutes:

git clone https://github.com/openai/chatkit-starter
cd chatkit-starter

# .env.local
NEXT_PUBLIC_CHATKIT_WORKFLOW_ID=your_workflow_id_here
OPENAI_API_KEY=your_api_key_here

npm install
npm run dev

Custom Integration Example

For custom implementations, integrate ChatKit directly:

import { ChatKit } from '@openai/chatkit-react';

export default function AgentChat() {
  return (
    <ChatKit
      workflowId={process.env.NEXT_PUBLIC_CHATKIT_WORKFLOW_ID}
      apiKey={process.env.OPENAI_API_KEY}
      theme={{
        primaryColor: '#3b82f6',
        backgroundColor: '#ffffff',
        fontSize: '14px'
      }}
      onMessage={(message) => {
        console.log('User message:', message);
      }}
      onResponse={(response) => {
        console.log('Agent response:', response);
      }}
    />
  );
}

Connector Registry & MCP

The Connector Registry consolidates data sources into a single admin panel across ChatGPT and the OpenAI API. This unified approach makes it easy for administrators to manage how data sources and tools connect across all OpenAI products.

Pre-Built Connectors

AgentKit includes pre-built connectors for popular enterprise services:

Model Context Protocol (MCP)

Model Context Protocol (MCP) is an open standard for connecting AI models to external data sources and tools. The Connector Registry supports third-party MCP connectors, enabling you to integrate any hosted MCP server with your agents.

Enterprise Data Security

The Connector Registry provides centralized control over data access:

• Role-Based Access Control: Define who can access which connectors and data sources
• Audit Logging: Track all data access and connector usage for compliance
• Encrypted Credentials: API keys and secrets stored with AES-256 encryption
• Secure Token Management: OAuth tokens automatically refreshed and rotated

Evals for Agent Optimization

AgentKit includes powerful evaluation tools to help you improve agent performance. The Evals feature provides four key capabilities for optimization:

Single Agent Optimization

To optimize a single agent in your workflow:

Full Workflow Optimization

Use trace grading to assess end-to-end performance across multiple agents:

• Multi-Agent Evaluation: Test how agents work together in complex workflows
• Cross-Agent Dependencies: Identify bottlenecks and issues in data flow between agents
• End-to-End Metrics: Measure overall workflow success rate, latency, and token usage
• A/B Testing: Compare different workflow configurations to find optimal setups

Building Your First AI Agent

Let's build a practical example: a career development assistant that analyzes resumes and recommends courses. This workflow uses three specialized agents working together.

Step 1: Set Up Agent Builder

1. Navigate to https://platform.openai.com/agent-builder
2. Log in with OpenAI credentials
3. Ensure billing details are added
4. Verify your organization in account settings

Step 2: Create Resume Extraction Agent

{
  "skills": ["JavaScript", "React", "Node.js"],
  "experience": [
    {
      "title": "Software Engineer",
      "company": "Tech Co",
      "years": 3
    }
  ],
  "education": {
    "degree": "BS Computer Science",
    "school": "University Name"
  }
}

Step 3: Create Career Analysis Agent

Analyze the following resume data and identify skill gaps
for senior software engineering roles:

{{input.output_text}}

Provide:
1. Current skill level assessment
2. Missing skills for target role
3. Recommended learning path
4. Estimated time to proficiency

Step 4: Create Course Recommendation Agent

Step 5: Test and Deploy

Deployment & Integration

AgentKit provides multiple deployment options depending on your use case and infrastructure requirements:

// Install ChatKit
npm install @openai/chatkit-react

// Embed in your app
import { ChatKit } from '@openai/chatkit-react';

<ChatKit
  workflowId="your-workflow-id"
  apiKey={process.env.OPENAI_API_KEY}
/>

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const response = await client.workflows.run({
  workflow_id: 'your-workflow-id',
  input: {
    user_message: 'Analyze this resume...',
    context: { user_id: '123' }
  }
});

console.log(response.output);

# Clone starter template
git clone https://github.com/openai/chatkit-starter
cd chatkit-starter

# Configure
echo "NEXT_PUBLIC_CHATKIT_WORKFLOW_ID=your-workflow-id" > .env.local
echo "OPENAI_API_KEY=your-api-key" >> .env.local

# Deploy
vercel deploy

Version Management

Agent Builder includes full version control for workflows:

• Version History: Track all changes to your workflow configuration
• Rollback Support: Revert to previous versions if issues arise
• Version Comparison: Compare different versions side-by-side
• Safe Testing: Test changes in preview mode before deploying to production
• Deployment Tags: Tag specific versions for production, staging, and development

Pricing & Availability

As of October 6, 2025, AgentKit tools are included with standard OpenAI API pricing. There are no additional platform fees, subscriptions, or usage charges for using Agent Builder, ChatKit, Connector Registry, or Evals.

What's Included

Cost Structure

You only pay for the OpenAI API calls your agents make:

Getting Started

To start building with AgentKit:

Real-World Use Cases

AgentKit enables a wide range of practical applications across industries. Here are proven use cases that demonstrate the platform's versatility:

Frequently Asked Questions