Build and Deploy Your First AI Agent with OpenAI Agents SDK

This guide walks you step by step through the entire process of building your first AI agent using the OpenAI Agents SDK in simple, by connecting it with Google Gemini, and deploying it to the internet so you can share your creation with others.

Whether you are a beginner or an experienced developer, this tutorial ensures that you understand each step clearly. By the end, you’ll have a fully working AI agent capable of handling both frontend and backend development questions complete with a live shareable link.

Introduction

In this tutorial, you’ll learn how to build your first AI agent using the OpenAI Agents SDK, connect it to Google Gemini, and deploy it online all from scratch. By the end of this guide, you’ll have a live AI agent that can handle both frontend and backend web development queries with a beautiful UI and it have a shareable link to showcase your project.

This is perfect for developers, students, freelancers, and anyone who wants to build portfolio-ready AI projects.

Step 1: Create and Initialize Your Project

Start by creating a new project folder and open it in your editor, such as Visual Studio Code. Once you are inside that folder, open your integrated terminal and initialize your environment using:

uv init .

This sets up your Python project with the uv package manager, a fast and modern environment tool. It ensures your dependencies and environment stay clean and well-organized.

Step 2: Add Environment Variables

Next, we safely manage sensitive information like API keys. Install python-dotenv:

uv add python-dotenv

Create a .env file in the root of your project and insert your Gemini API key:

GEMINI_API_KEY=your_api_key_here

This ensures you do not hardcode API keys in your code, keeping your project secure, clean, and professional.

Step 3: Install OpenAI Agents SDK

Add the OpenAI Agents SDK to your project:

uv add openai

This SDK allows you to build and run advanced AI agents compatible with OpenAI-style models. It gives you tools to define agents, orchestrate communication, and manage powerful capabilities in a modular way.

Step 4: Build Your Agent

Create a new file name it main.py and paste your agent code inside it.

from agents import Runner, Agent, AsyncOpenAI, OpenAIChatCompletionsModel, RunConfig
from dotenv import load_dotenv
import os
import chainlit as cl

load_dotenv()

gemini_api_key = os.getenv("GEMINI_API_KEY")

external_client = AsyncOpenAI(
    api_key=gemini_api_key,
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

model = OpenAIChatCompletionsModel(
    model="gemini-2.0-flash",
    openai_client=external_client
)

config = RunConfig(
    model=model,
    model_provider=external_client,
    tracing_disabled=True
)

backend_agent = Agent(
    name="Backend Expert",
    instructions="""
You are a backend development expert. You help users with backend topics like APIs, databases, authentication, server frameworks (e.g., Express.js, Django).

Do NOT answer frontend or UI questions.
"""
)

frontend_agent = Agent(
    name="Frontend Expert",
    instructions="""
You are a frontend expert. You help with UI/UX using HTML, CSS, JavaScript, React, Next.js, and Tailwind CSS.

Do NOT answer backend-related questions.
"""
)

web_dev_agent = Agent(
    name="Web Developer Agent",
    instructions="""
You are a generalist web developer who decides whether a question is about frontend or backend.

If the user asks about UI, HTML, CSS, React, etc., hand off to the frontend expert.
If the user asks about APIs, databases, servers, backend frameworks, etc., hand off to the backend expert.
If it’s unrelated to both, politely decline.
""",
    handoffs=[
        frontend_agent,
        backend_agent
    ]
)

@cl.on_chat_start
async def handle_start_chat():
    cl.user_session.set("history", [])
    await cl.Message(content="👋 Hello from Stoppio! Ask anything about web dev.").send()

@cl.on_message
async def handle_message(message: cl.Message):
    history = cl.user_session.get("history")

    history.append({"role": "user", "content": message.content})
    
    # 🔄 RUN the web_dev_agent, NOT frontend_agent directly
    result = await Runner.run(
        web_dev_agent,
        input=history,
        run_config=config
    )
    
    history.append({"role": "assistant", "content": result.final_output})
    cl.user_session.set("history", history)

    await cl.Message(content=result.final_output).send()

This code defines three agents:

• Frontend Expert Agent Specializes in HTML, CSS, JavaScript, frameworks, UI/UX, Tailwind, and frontend optimization.
• Backend Expert Agent can handle databases, APIs, authentication, server logic, and backend frameworks.
• Web Developer Agent (Router) Acts as the central controller that receives a user’s question and intelligently routes it to the correct expert.

These agents communicate with each other to produce accurate, high-quality responses. This multi-agent architecture allows more reliable and domain-specific results.

Step 5: Add Chainlit for Chat UI

To create a clean and interactive interface, install Chainlit:

uv add chainlit

Run your application using:

uv run chainlit run main.py -w

Then visit:

http://localhost:8000

You’ll see your interactive AI agent working with a full chat UI. You can ask frontend or backend questions and watch the router agent delegate tasks intelligently.

Step 6: Prepare for Deployment

Before deploying the agent, we need to create a new file named Procfile in your project root.

Inside it, add this line:

web: chainlit run main.py --port $PORT

This tells your hosting platform how to start your application.

Step 7: Deploy Using Railway

Railway is a powerful hosting platform that makes deployment simple and fast.

1. Go to Railway.app and sign in with GitHub.
2. Create a new GitHub repository and upload your project files manually. Do not upload your .env file.
3. On Railway, choose your repository.
4. Go to the Variables tab and add:

GEMINI_API_KEY = your_api_key_here

Click Deploy.

After a few moments, Railway will give you a public link to your live AI agent.

Step 8: Test and Share

Open your live URL and begin testing. Ask any frontend or backend development question and observe how the agent delegates tasks across the specialized experts.

Now you can share this link in your portfolio, GitHub, LinkedIn, resume, or anywhere else to demonstrate your AI development skills.