AI Agents Demo

This repository contains Jupyter notebooks that demonstrate OpenAI’s conversation flow, tool calling capabilities, and the creation of simple AI agents using the OpenAI Agents SDK. These notebooks were created to accompany the CTO Insights talk presented by Jason Allen, hosted by NextPath and AzTia

Prerequisites

1. Install UV (Python Package Manager)

Install UV for Python package management:

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. OpenAI API Key

You'll need an OpenAI API key to run these notebooks. Get one from OpenAI's platform.

Setup

1. Clone the repository:

   git clone <repository-url>
   cd ai_agents_explained

2. Install dependencies:

   uv sync

3. Create a .env file: Create a .env file in the root directory with your OpenAI API key:

   OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   

   Replace sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual OpenAI API key.

Running the Notebooks

Open the notebooks directly in VSCode or Cursor. The IDE will automatically detect the Python environment managed by UV.

1. Open VSCode or Cursor
2. Open the project folder
3. Click on any .ipynb file to open it
4. Select the Python interpreter from .venv/bin/python when prompted
5. Run the notebook cells directly in the IDE

Notebooks

1. 01_coversation.ipynb

Demonstrates basic conversation flow with OpenAI's API, showing:

• Single API calls
• How to maintain conversation history
• Memory limitations without context

2. 02_tool_calling.ipynb

Shows OpenAI's tool calling (function calling) capabilities:

• Defining function schemas
• Making API calls with tools
• Handling function execution and responses

3. 03_gradio_chat_demo.ipynb

Interactive chat interface using Gradio that demonstrates:

• Real-time tool calling in a chat UI
• Weather function integration
• Conversation management

4. 04_simple_agent.ipynb

Demonstrates single agents and agent chaining patterns:

• Creating and running simple agents
• Chaining multiple agents together
• Agent workflow orchestration
• Using OpenAI traces for monitoring

5. 05_agent_handoffs.ipynb

Shows agent routing and handoff patterns:

• Creating specialized agents (billing, tech support, default)
• Implementing a triage agent for routing
• Agent handoff workflows
• Support ticket routing example

6. 06_agent_tool_calling.ipynb

Compares hosted tools vs function tools for agents:

• Custom weather function implementation
• Using hosted web search tools
• OpenAI platform trace monitoring
• Tool integration patterns

7. 07_agent_deep_search.ipynb

Advanced multi-agent research system demonstrating:

• Complex agent orchestration
• Web search planning and execution
• Research report generation
• Email automation with SendGrid integration
• Multi-step workflow coordination

Usage

1. Open any notebook in Jupyter
2. Run all cells in order
3. For the Gradio demo, click the generated link to open the chat interface
4. Try asking weather-related questions to see tool calling in action

Example Questions for Tool Calling Demo

• "What's the weather like in Tampa?"
• "How's the weather in New York and Los Angeles?"
• "Tell me about the weather in Chicago"
• "What should I wear in Seattle today?"

Dependencies

• openai - OpenAI Python SDK
• python-dotenv - Environment variable management
• gradio - Web UI framework for demos
• ipykernel - Jupyter notebook support
• sendgrid - Email delivery service for agent automation

All dependencies are managed through pyproject.toml and installed via uv sync.

Additional Features

The repository includes:

• Custom agent tools (agent_tools.py)
• Visual diagrams for agent patterns (chaining and routing)
• OpenAI platform trace integration for workflow monitoring
• Examples of both simple and complex agent architectures