tessl/pypi-openai-agents

Lightweight framework for building multi-agent workflows with LLMs, supporting handoffs, guardrails, tools, and 100+ LLM providers

Overview

Eval results

Files

Model Providers

Name: tessl/pypi-openai-agents
Author: tessl

Model providers enable the SDK to work with different LLM backends. The SDK includes built-in support for OpenAI models and can integrate with 100+ LLMs through the LiteLLM provider. Custom providers can be implemented for proprietary or specialized models.

Capabilities

Model Interface

Base interface for LLM implementations.

class Model:
    """Base interface for LLM."""

    async def get_response(
        input: list[TResponseInputItem],
        instructions: str | None,
        tools: list[Tool],
        model_settings: ModelSettings,
        response_id: str | None,
        tracing: ModelTracing
    ) -> ModelResponse:
        """
        Get response from model.

        Parameters:
        - input: Input items
        - instructions: System instructions
        - tools: Available tools
        - model_settings: Model configuration
        - response_id: Response ID for continuation
        - tracing: Tracing configuration

        Returns:
        - ModelResponse: Model response with outputs and usage
        """

    async def stream_response(
        input: list[TResponseInputItem],
        instructions: str | None,
        tools: list[Tool],
        model_settings: ModelSettings,
        response_id: str | None,
        tracing: ModelTracing
    ) -> AsyncIterator[TResponseStreamEvent]:
        """
        Stream response from model.

        Parameters:
        - Same as get_response

        Returns:
        - AsyncIterator[TResponseStreamEvent]: Stream of response events
        """

Model Provider Interface

Base interface for model providers.

class ModelProvider:
    """Base interface for model provider."""

    def get_model(model_name: str) -> Model:
        """
        Get model by name.

        Parameters:
        - model_name: Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet")

        Returns:
        - Model: Model instance

        Raises:
        - ValueError: If model not supported
        """

OpenAI Provider

Provider for OpenAI models using official API.

class OpenAIProvider(ModelProvider):
    """
    OpenAI model provider.

    Supports OpenAI models through both Responses API
    and Chat Completions API.
    """

    def get_model(model_name: str) -> Model:
        """
        Get OpenAI model by name.

        Parameters:
        - model_name: OpenAI model name

        Returns:
        - Model: OpenAI model instance
        """

Usage example:

from agents import Agent, Runner, RunConfig, OpenAIProvider

provider = OpenAIProvider()
config = RunConfig(
    model="gpt-4o",
    model_provider=provider
)

agent = Agent(name="Assistant")
result = Runner.run_sync(agent, "Hello", run_config=config)

Multi Provider

Provider that automatically routes to appropriate backend based on model name.

class MultiProvider(ModelProvider):
    """
    Multi-provider model lookup.

    Automatically selects appropriate provider based on
    model name patterns. Default provider for RunConfig.

    Supported:
    - OpenAI models (gpt-*, o1-*, etc.)
    - Anthropic models (claude-*)
    - Other providers via LiteLLM
    """

    def get_model(model_name: str) -> Model:
        """
        Get model from appropriate provider.

        Parameters:
        - model_name: Model identifier

        Returns:
        - Model: Model instance from appropriate provider
        """

Usage example:

from agents import Agent, Runner, RunConfig, MultiProvider

# MultiProvider is default, routes automatically
config = RunConfig(model="gpt-4o")  # Uses OpenAI
agent = Agent(name="Assistant")
result = Runner.run_sync(agent, "Hello", run_config=config)

# Can also specify explicitly
provider = MultiProvider()
config = RunConfig(model="claude-3-5-sonnet-20241022", model_provider=provider)

OpenAI Chat Completions Model

Implementation using OpenAI Chat Completions API.

class OpenAIChatCompletionsModel(Model):
    """
    OpenAI Chat Completions API model.

    Uses the chat.completions endpoint for text generation.
    """

    async def get_response(...) -> ModelResponse:
        """Get response from Chat Completions API."""

    async def stream_response(...) -> AsyncIterator[TResponseStreamEvent]:
        """Stream response from Chat Completions API."""

OpenAI Responses Model

Implementation using OpenAI Responses API (newer API).

class OpenAIResponsesModel(Model):
    """
    OpenAI Responses API model.

    Uses the responses endpoint for advanced features
    like response chaining and conversation management.
    """

    async def get_response(...) -> ModelResponse:
        """Get response from Responses API."""

    async def stream_response(...) -> AsyncIterator[TResponseStreamEvent]:
        """Stream response from Responses API."""

Model Tracing Configuration

Enum for configuring model tracing behavior.

class ModelTracing(Enum):
    """
    Tracing configuration for models.

    Values:
    - DISABLED: No tracing
    - ENABLED: Full tracing with data
    - ENABLED_WITHOUT_DATA: Tracing without sensitive data
    """

    DISABLED = "disabled"
    ENABLED = "enabled"
    ENABLED_WITHOUT_DATA = "enabled_without_data"

    def is_disabled() -> bool:
        """
        Check if tracing is disabled.

        Returns:
        - bool: True if disabled
        """

    def include_data() -> bool:
        """
        Check if should include data in traces.

        Returns:
        - bool: True if data should be included
        """

LiteLLM Provider

Provider for accessing 100+ LLMs through LiteLLM unified interface.

# In agents.extensions.models
class LiteLLMProvider(ModelProvider):
    """
    LiteLLM model provider.

    Provides access to 100+ LLMs including:
    - Anthropic (Claude)
    - Google (Gemini, PaLM)
    - Cohere
    - Mistral
    - Together AI
    - Replicate
    - Azure OpenAI
    - AWS Bedrock
    - And many more

    Requires: pip install litellm
    """

    def __init__(self, **kwargs):
        """
        Initialize LiteLLM provider.

        Parameters:
        - **kwargs: Configuration passed to LiteLLM
        """

    def get_model(model_name: str) -> Model:
        """
        Get model from LiteLLM.

        Parameters:
        - model_name: Model identifier (e.g., "claude-3-5-sonnet-20241022")

        Returns:
        - Model: LiteLLM model instance
        """

Usage example:

from agents import Agent, Runner, RunConfig
from agents.extensions.models import LiteLLMProvider

# Use Claude via LiteLLM
provider = LiteLLMProvider()
config = RunConfig(
    model="claude-3-5-sonnet-20241022",
    model_provider=provider
)

agent = Agent(
    name="Assistant",
    instructions="You are helpful."
)

result = Runner.run_sync(agent, "Hello", run_config=config)

# Use Gemini
config = RunConfig(
    model="gemini/gemini-1.5-pro",
    model_provider=provider
)

# Use AWS Bedrock
config = RunConfig(
    model="bedrock/anthropic.claude-3-sonnet-20240229-v1:0",
    model_provider=provider
)

Configuration

Global OpenAI Configuration

Configure OpenAI client globally for all agents.

from agents import set_default_openai_key, set_default_openai_client, set_default_openai_api
from openai import AsyncOpenAI

# Set API key
set_default_openai_key("sk-...", use_for_tracing=True)

# Set custom client
client = AsyncOpenAI(
    api_key="sk-...",
    base_url="https://api.openai.com/v1"
)
set_default_openai_client(client, use_for_tracing=True)

# Set default API mode
set_default_openai_api("responses")  # or "chat_completions"

Per-Agent Model Configuration

from agents import Agent, ModelSettings

agent = Agent(
    name="Assistant",
    model="gpt-4o",  # Specify model
    model_settings=ModelSettings(
        temperature=0.7,
        max_tokens=1000
    )
)

Per-Run Model Configuration

from agents import RunConfig, ModelSettings

config = RunConfig(
    model="gpt-4o-mini",  # Override agent model
    model_settings=ModelSettings(
        temperature=0.0,
        top_p=0.9
    )
)

result = Runner.run_sync(agent, "Hello", run_config=config)

Custom Model Provider

Implement a custom provider for proprietary or specialized models:

from agents import Model, ModelProvider, ModelResponse, ModelTracing
from agents.models.interface import TResponseInputItem, TResponseStreamEvent

class MyCustomModel(Model):
    """Custom model implementation."""

    def __init__(self, model_name: str):
        self.model_name = model_name

    async def get_response(
        self,
        input: list[TResponseInputItem],
        instructions: str | None,
        tools: list,
        model_settings,
        response_id: str | None,
        tracing: ModelTracing
    ) -> ModelResponse:
        # Call your model API
        response = await my_model_api.call(
            messages=input,
            system=instructions,
            temperature=model_settings.temperature
        )

        # Convert to ModelResponse
        return ModelResponse(
            output=[...],  # Convert response
            usage=Usage(...),  # Usage stats
            response_id=response.id
        )

    async def stream_response(
        self,
        input,
        instructions,
        tools,
        model_settings,
        response_id,
        tracing
    ):
        # Stream from your model
        async for chunk in my_model_api.stream(...):
            yield convert_chunk(chunk)

class MyModelProvider(ModelProvider):
    """Custom model provider."""

    def get_model(self, model_name: str) -> Model:
        if model_name.startswith("my-model-"):
            return MyCustomModel(model_name)
        raise ValueError(f"Unsupported model: {model_name}")

# Use custom provider
from agents import RunConfig

provider = MyModelProvider()
config = RunConfig(
    model="my-model-v1",
    model_provider=provider
)

result = Runner.run_sync(agent, "Hello", run_config=config)

Model Selection Strategies

Agent-Level Model

# Each agent uses specific model
research_agent = Agent(
    name="Researcher",
    model="gpt-4o",  # More capable
    instructions="Research deeply."
)

summary_agent = Agent(
    name="Summarizer",
    model="gpt-4o-mini",  # Faster, cheaper
    instructions="Summarize briefly."
)

Dynamic Model Selection

def select_model(input: str) -> str:
    """Select model based on input complexity."""
    if len(input) > 1000 or "complex" in input.lower():
        return "gpt-4o"
    return "gpt-4o-mini"

# Use in run config
model = select_model(user_input)
config = RunConfig(model=model)
result = Runner.run_sync(agent, user_input, run_config=config)

Fallback Strategy

async def run_with_fallback(agent, input):
    """Try primary model, fallback to secondary."""
    try:
        config = RunConfig(model="gpt-4o")
        return await Runner.run(agent, input, run_config=config)
    except Exception as e:
        print(f"Primary model failed: {e}, trying fallback")
        config = RunConfig(model="gpt-4o-mini")
        return await Runner.run(agent, input, run_config=config)