runlet 0.2.0b1

A tiny observable runtime for Python agents.

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]"

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
• 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 two OpenAI-compatible providers:

• OpenAIChatCompletionsProvider
• OpenAIResponsesProvider

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

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.0b1
4. Push the tag

git tag v0.2.0b1
git push origin v0.2.0b1