Runlet

Runlet is a small, provider-neutral Python agent runtime library.

It is designed for applications that want explicit control over model calls, tool execution, context budgeting, and structured observability without adopting a large framework.

When to use Runlet

Runlet is a good fit when you want to:

• embed agent execution inside an existing Python application
• keep model providers behind adapters
• enforce context preparation before model calls
• stream model output while still executing tools inside the runtime loop
• observe runs through structured events
• build your own application-level conversation, memory, or state policies

When not to use Runlet

Runlet is not trying to be:

• a hosted agent platform
• a web framework
• a graph workflow engine
• a UI or trace viewer
• a full memory framework

If you want a batteries-included platform with orchestration, persistence, and application scaffolding built in, Runlet is intentionally narrower than that.

Quickstart

Install Runlet:

pip install runlet

Install the OpenAI optional dependency:

pip install "runlet[openai]"

Install the Anthropic optional dependency:

pip install "runlet[anthropic]"

If you prefer .env based local development:

pip install python-dotenv

Example .env:

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-endpoint.example/v1
OPENAI_MODEL=qwen-plus

Minimal example:

import asyncio
import os

from dotenv import load_dotenv

from runlet import Agent, Runtime
from runlet.providers import OpenAIChatCompletionsProvider


async def main() -> None:
    load_dotenv()

    provider = OpenAIChatCompletionsProvider(
        model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),
        api_key=os.environ["OPENAI_API_KEY"],
        base_url=os.environ.get("OPENAI_BASE_URL"),
    )

    agent = Agent(
        name="assistant",
        instructions="Be concise and helpful.",
        model=provider,
    )

    result = await Runtime().run(agent, "用一句中文介绍 Runlet。")
    print(result.output)


asyncio.run(main())

Core capabilities

• provider-neutral runtime loop
• async model execution
• streaming text output
• runtime-managed streaming tool execution
• request-level provider options
• structured runtime events
• hook points around model and tool execution
• lightweight state store primitives

Documentation

Start here:

• Installation
• First Agent
• OpenAI Chat Completions
• Anthropic Messages
• OpenAI Responses
• Streaming
• Tool Calling
• Full Example

Guides:

• Conversation State
• Provider Options
• Reasoning
• Observability

Concepts:

• Runtime Boundary
• Core Models
• Provider Neutrality

Project background:

• Architecture
• Design Principles
• Comparison
• Roadmap
• Contributing
• Security

Providers

Runlet currently includes three built-in providers:

• OpenAIChatCompletionsProvider
• OpenAIResponsesProvider
• AnthropicMessagesProvider

For most third-party OpenAI-compatible gateways, start with OpenAIChatCompletionsProvider. It is usually the more portable option.

For Anthropic's official API, use AnthropicMessagesProvider.

Project status

Runlet is currently in beta. The API may still evolve before a stable 0.x release.

Development

Run the test suite:

PYTHONPATH=src python3 -m unittest discover tests

Run type checking:

pyright

Release

Runlet publishes to PyPI from Git tags through GitHub Actions.

Typical release flow:

1. Update the version in pyproject.toml
2. Merge to main
3. Create a tag such as v0.2.0b3
4. Push the tag

git tag v0.2.0b3
git push origin v0.2.0b3