Circulator: Multi-Agent AI Research Assistant

A sophisticated multi-agent AI research assistant built with the OpenAI Agents SDK and Olostep Web API. This system orchestrates multiple specialized agents to produce grounded, source-based research reports.

Features

• Manager Agent: Orchestrates the research workflow and coordinates specialist agents
• Judge Agent: Evaluates the quality of gathered evidence against user requirements
• Analyst Agent: Produces polished, professional Markdown research reports
• Web Research Tools: Integrates Olostep APIs for searching, scraping, and answering queries
• Progressive Research: Starts with quick answers and conducts deeper research only when needed
• Structured Output: Returns well-formatted Markdown reports with citations and references
• Full Tracing: OpenAI trace viewer integration for debugging and monitoring

Project Structure

circulator/
├── main.py                      # Entry point for running the assistant
├── research_assistant.py        # Core implementation
├── pyproject.toml               # Project dependencies
├── .env                         # API keys (create this file)
├── .gitignore                   # Git ignore rules
├── README.md                    # This file
└── Results/                     # Output reports (auto-created, ignored by Git)

Setup

Prerequisites

• Python 3.13+
• uv package manager (https://astral.sh/uv/)
• OpenAI API key (with gpt-5.4-mini model access)
• Olostep API key (free tier available at https://www.olostep.com/)

Installation

1. Clone or navigate to the project:

   cd circulator

2. Create .env file with your API keys:

   OPENAI_API_KEY=your_openai_api_key_here
   OLOSTEP_API_KEY=your_olostep_api_key_here

3. Virtual environment (already initialized with uv init):

   # Dependencies are already installed, verify with:
   uv pip list

Usage

Running the Research Assistant

uv run main.py

The assistant will prompt you to enter your research question. Type your query and press Enter twice to submit:

================================================================================
Multi-Agent AI Research Assistant
================================================================================

Enter your research question below.
(Press Enter twice to submit)

What are the latest developments in AI agents?
[Press Enter twice to submit...]

Output Files

Reports are automatically saved to the Results/ directory with:

1. Filename format: YYYY-MM-DD <truncated-slug>.md
2. Smart slug truncation: The question slug is intelligently truncated to 100 characters max while preserving complete words, keeping the total filename well under Windows' 255-character limit
3. Content format: Each report includes:
   • The original research query at the top (in "Research Query" section)
   • A divider line
   • The full research report with all sections

Example filenames:

• Short question: 2026-07-14 python-data-science-benefits.md
• Long question: 2026-07-14 latest-developments-ai-agents-business-research.md (truncated intelligently)

Key benefits of this approach:

• Date-based: Chronological organization in the file system
• Meaningful slug: Can identify the research topic from the filename
• Windows-safe: Always stays under 255-character filename limit
• Full context preserved: Original query is in the report content

Example report content:

# Research Query

What are the latest developments in AI agents for business research?

---

[Full research report with Executive Summary, Key Findings, etc.]

The Results/ directory is ignored by Git for privacy and to keep the repository clean.

To use the assistant with your own research question, modify main.py:

query = "Your research question here"
report = await run_research_assistant(query)

Using in Your Code

import asyncio
from research_assistant import run_research_assistant

async def my_research():
    query = "What is the latest in quantum computing?"
    report = await run_research_assistant(query)
    print(report.markdown_report)

asyncio.run(my_research())

Workflow

The research assistant follows this intelligent workflow:

1. Initial Answer: Calls Olostep Answer API for a quick initial response
2. First Quality Check: Judge agent evaluates if evidence is sufficient
3. If Needed - Deeper Search: Executes search with scraping for richer content
4. Second Quality Check: Judge agent re-evaluates gathered evidence
5. If Still Needed - Targeted Research: Runs multiple targeted searches and scrapes top results
6. Report Generation: Analyst agent produces the final Markdown report

This progressive approach balances speed and cost while ensuring high-quality output.

API Keys

OpenAI Setup

1. Visit https://platform.openai.com/
2. Go to API keys section
3. Create a new key and add it to .env
4. Ensure your account has billing enabled and at least $5 in credits

Olostep Setup

1. Visit https://www.olostep.com/
2. Create a free account (no credit card required)
3. Generate an API key from your dashboard
4. Free plan includes 500 successful requests

Dependencies

• openai-agents: OpenAI's agent framework
• olostep: Web search and scraping API
• pydantic: Data validation and structured outputs
• python-dotenv: Environment variable management
• jupyter: Optional, for notebook-based experimentation

Debugging

View the full execution trace:

1. Run the assistant - it will print a trace URL
2. Open the URL in your browser: https://platform.openai.com/logs/trace?trace_id=...
3. Inspect manager decisions, agent calls, tool usage, and API interactions

Output Format

The research assistant produces a Markdown report with:

• Executive Summary: High-level overview
• Key Findings: Main insights
• Context: Background information
• Evidence Review: Source analysis
• Detailed Analysis: In-depth examination
• Implications: Significance and impact
• Source Notes: Quality assessment of sources
• References: Complete bibliography with links

Troubleshooting

"API keys not set"

Ensure your .env file has both OPENAI_API_KEY and OLOSTEP_API_KEY.

"Module not found"

Run uv pip list to verify dependencies. If missing, run uv add <package_name>.

"Slow execution"

The assistant may conduct multiple API calls. First run typically takes 30-60 seconds. Monitor progress via OpenAI trace.

Resources

• Machine Learning Mastery Tutorial
• OpenAI Agents SDK Docs
• Olostep API Docs
• Pydantic Documentation

License

This project is provided as-is for educational and research purposes.

Contributing

Suggestions and improvements welcome! Feel free to extend the implementation with:

• Additional specialist agents
• Custom tools for specific domains
• Different output formats
• Performance optimizations