Open Responses API Examples

Below are practical examples showing how to use the Julep Open Responses API for various use cases.

The Open Responses API requires self-hosting. See the installation guide below.
Being in Alpha, the API is subject to change. Check back frequently for updates.
For more context, see the OpenAI Responses API documentation.

API Key Configuration

RESPONSE_API_KEY is the API key that you set in the .env file.

Model Selection

While using models other than OpenAI, one might need to add the provider/ prefix to the model name.
For supported providers, see the LiteLLM Providers documentation.

Environment Setup

Add the relevant provider keys to the .env file to use their respective models.

OpenAI's SDK
Agents SDK

Setup

First, set up your environment and create a client:

from openai import OpenAI

# Create an OpenAI client pointing to Julep's Open Responses API
client = OpenAI(base_url="http://localhost:8080/", api_key="RESPONSE_API_KEY")

Using Reasoning Features

Enhance your model’s reasoning capabilities for solving complex problems:

# Create a response with explicit reasoning
reasoning_response = client.responses.create(
    model="o1",
    input="If Sarah has 3 apples and John has 5, and they combine their apples, then how many apples do they have in total? Explain your approach.",
    reasoning={
        "effort": "medium"  # Control reasoning depth with "low", "medium", or "high"
    }
)

# Access the final answer
print(reasoning_response.output_text)
# Output: They would have 8 apples in total. The approach is straightforward: you simply add the number of apples Sarah has (3) to the number of apples John has (5), giving 3 + 5 = 8..

Using Web Search Tool

Python

web_search_response = openai_client.responses.create(
model="gpt-4o-mini",
tools=[{"type": "web_search_preview"}],
    input="What was a positive news story from today?",
)
# The output will include both the text response and any tool calls that were made

Maintaining Conversation History

Create a continuous conversation by referencing previous responses:

# Reference a previous response to continue a conversation
follow_up_response = client.responses.create(
    model="gpt-4o-mini",
    input="What was the final answer?",
    previous_response_id=reasoning_response.id
)

print(follow_up_response.output_text)

Retrieving Past Responses

Access previously created responses by their ID:

# Retrieve a response by ID
retrieved_response = client.responses.retrieve(response_id="your-response-id")

Setup

First, set up your environment and create an async client:

from openai import AsyncOpenAI
from agents import set_default_openai_client

# Create and configure the OpenAI client
custom_client = AsyncOpenAI(base_url="http://localhost:8080/", api_key="RESPONSE_API_KEY")
set_default_openai_client(custom_client)

Creating a Simple Agent

Build a basic agent that can respond to user queries:

from agents import Agent, Runner

# For Jupyter notebooks:
agent = Agent(
    name="Test Agent",
    instructions="You are a helpful assistant that provides concise responses.",
    model="openrouter/deepseek/deepseek-r1",
)

result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

# For Python scripts, you'd use:
# async def test_installation():
#     agent = Agent(
#         name="Test Agent",
#         instructions="You are a helpful assistant that provides concise responses."
#         model="openrouter/deepseek/deepseek-r1",
#     )
#     result = await Runner.run(agent, "Hello! Are you working correctly?")
#     print(result.final_output)
#
# if __name__ == "__main__":
#     asyncio.run(test_installation())

# Output: Great to hear! Let me know how I can help you today—whether it's answering questions, solving problems, or just chatting. 😊

Web Search Integration

Create an agent with web search capabilities:

from agents import Agent, Runner, WebSearchTool

# Create a research assistant with web search capability
research_assistant = Agent(
    name="Research Assistant",
    instructions="""You are a research assistant that helps users find and summarize information.
    When asked about a topic:
    1. Search the web for relevant, up-to-date information
    2. Synthesize the information into a clear, concise summary
    3. Structure your response with headings and bullet points when appropriate
    4. Always cite your sources at the end of your response
   
    If the information might be time-sensitive or rapidly changing, mention when the search was performed.
    """,
    tools=[WebSearchTool()]
)


async def research_topic(topic):
    result = await Runner.run(research_assistant, f"Please research and summarize: {topic}. Only return the found links with very minimal text.")
    return result.final_output

# Usage example (in Jupyter notebook)
summary = await research_topic("Latest developments in personal productivity apps.")
print(summary)

# Output: Here are some links to the latest developments in personal productivity apps:
# - [10 Hot Productivity Apps for 2024](https://francescod.medium.com/10-hot-productivity-apps-for-2024-e45e68f2ee22) - Medium
# - [The Best Productivity Apps in 2025](https://zapier.com/blog/best-productivity-apps/) - Zapier
# - [The Best Productivity Apps for 2025](https://www.pcmag.com/picks/best-productivity-apps) - PCMag

Custom Function Tools

Create an agent with a custom function tool:

import os
import requests
from datetime import datetime
from typing import Optional, List
from dataclasses import dataclass

from agents import Agent, Runner, function_tool
from dotenv import load_dotenv

load_dotenv()


@dataclass
class WeatherInfo:
    temperature: float
    feels_like: float
    humidity: int
    description: str
    wind_speed: float
    pressure: int
    location_name: str
    rain_1h: Optional[float] = None
    visibility: Optional[int] = None


@function_tool
def get_weather(lat: float, lon: float) -> str:
    """Get the current weather for a specified location using OpenWeatherMap API.

    Args:
        lat: Latitude of the location (-90 to 90)
        lon: Longitude of the location (-180 to 180)
    """
    # Get API key from environment variables
    WEATHER_API_KEY = os.getenv("OPENWEATHERMAP_API_KEY")

    # Build URL with parameters
    url = f"https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={WEATHER_API_KEY}&units=metric"

    try:
        response = requests.get(url)
        response.raise_for_status()
        data = response.json()

        # Extract weather data from the response
        weather_info = WeatherInfo(
            temperature=data["main"]["temp"],
            feels_like=data["main"]["feels_like"],
            humidity=data["main"]["humidity"],
            description=data["weather"][0]["description"],
            wind_speed=data["wind"]["speed"],
            pressure=data["main"]["pressure"],
            location_name=data["name"],
            visibility=data.get("visibility"),
            rain_1h=data.get("rain", {}).get("1h"),
        )

        # Build the response string
        weather_report = f"""
        Weather in {weather_info.location_name}:
        - Temperature: {weather_info.temperature}°C (feels like {weather_info.feels_like}°C)
        - Conditions: {weather_info.description}
        - Humidity: {weather_info.humidity}%
        - Wind speed: {weather_info.wind_speed} m/s
        - Pressure: {weather_info.pressure} hPa
        """
        return weather_report

    except requests.exceptions.RequestException as e:
        return f"Error fetching weather data: {str(e)}"

Using the Tool with an Agent

Create an agent that uses the custom function tool:

# Create a weather assistant
weather_assistant = Agent(
    name="Weather Assistant",
    instructions="""You are a weather assistant that can provide current weather information.
   
    When asked about weather, use the get_weather tool to fetch accurate data.
    If the user doesn't specify a country code and there might be ambiguity,
    ask for clarification (e.g., Paris, France vs. Paris, Texas).
   
    Provide friendly commentary along with the weather data, such as clothing suggestions
    or activity recommendations based on the conditions.
    """,
    tools=[get_weather]
)

async def main():
    runner = Runner()

    simple_request = await runner.run(weather_assistant, "What are your capabilities?")
    request_with_location = await runner.run(weather_assistant, "What's the weather like in Tashkent right now?")

    print(simple_request.final_output)
    print("-"*70)
    print(request_with_location.final_output)

await main()

# Output: 
# I'm a weather assistant that can provide you with current weather information. If you ask about the weather for a specific location, I can use a tool to fetch accurate and up-to-date weather data for that place. 
# 
# Additionally, I can offer friendly suggestions based on the weather, like what to wear or what activities might be suitable. If the location you mention is ambiguous (like Paris, which could be in France or Texas), I might ask for clarification to ensure I provide you with the correct weather information.
# ----------------------------------------------------------------------
# Right now in Tashkent, it's a bit cool with a temperature of 8.84°C, feeling slightly cooler at 7.06°C. The sky is overcast with lots of clouds, and the humidity is at 76%, so you might feel a bit of dampness in the air. There's a gentle breeze with the wind blowing at 3.09 m/s.
# 
# With these conditions, I'd recommend wearing a warm jacket if you're heading out. It's a great day to enjoy indoor activities or perhaps a warm drink at a cozy café! Stay comfortable!

Next Steps

You’ve got Open Responses running – here’s what to explore next:

Learn more about the Open Responses API Concepts – To learn more about core concepts and how Open Responses structures these building blocks in your applications.
Learn more about the Open Responses API Roadmap – To see upcoming features.
OpenAI’s Responses API Documentation - For more insight into the original API that inspired Julep’s Responses
OpenAI Agents SDK - Explore OpenAI’s Agents SDK that works with Julep’s Open Responses API
Learn more about Julep - To learn more about Julep and its features
Julep’s GitHub Repository - To contribute to the project

Documentation Index

​Open Responses API Examples

​API Key Configuration

​Model Selection

​Environment Setup

​Setup

​Using Reasoning Features

​Using Web Search Tool

​Maintaining Conversation History

​Retrieving Past Responses

​Setup

​Creating a Simple Agent

​Web Search Integration

​Custom Function Tools

​Using the Tool with an Agent

​Next Steps

Open Responses API Examples

API Key Configuration

Model Selection

Environment Setup

Setup

Using Reasoning Features

Using Web Search Tool

Maintaining Conversation History

Retrieving Past Responses

Setup

Creating a Simple Agent

Web Search Integration

Custom Function Tools

Using the Tool with an Agent

Next Steps