Python Agent Runtime

A modern, lightweight Python runtime for executing AI agents cleanly and predictably.

This project is intentionally small. It is not a LangGraph, CrewAI or AutoGen replacement. The goal is a polished library that demonstrates clean architecture, type-safe APIs and practical runtime behavior.

Install

uv add python-agent-runtime

Official RAG backend:

uv add "python-rag-framework @ git+https://github.com/lelouchzr/[email protected]"

Optional OpenAI adapter:

uv add "python-agent-runtime[openai]"

Usage

from collections.abc import Sequence

from agent import Agent, CallableLLM, Message


def generate(messages: Sequence[Message]) -> str:
    return call_your_model(messages)


agent = Agent(llm=CallableLLM(generate), instructions="Answer clearly and briefly.")
response = agent.run("Explain the difference between 은/는 and 이/가.")

With tools:

def calculator(expression: str) -> str:
    """Evaluate a simple arithmetic expression."""
    return str(eval(expression, {"__builtins__": {}}, {}))


agent.add_tool(calculator)

With RAG:

from rag import RAG
from agent import Agent, CallableLLM

rag = RAG()
rag.add_text(
    "In Korean, 은/는 are topic particles. 이/가 usually mark the subject.",
    source="korean-grammar-notes",
)

agent = Agent(llm=CallableLLM(generate), rag=rag)

The runtime calls RAG.retrieve(...) and adds retrieved chunks to the agent prompt. It does not duplicate ingestion, embeddings, vector stores, reranking, citations or RAG answer generation. The runtime also works without a RAG instance.

With OpenAI:

from agent import Agent, OpenAIChatLLM

agent = Agent(llm=OpenAIChatLLM(model="gpt-4.1-mini"))
print(agent.run("Explain the difference between 은/는 and 이/가."))

Features

• Agent
• Runtime
• PromptBuilder
• ConversationHistory
• Memory abstraction
• Tool, ToolRegistry and ToolExecutor
• Callback system
• Optional integration with python-rag-framework
• Streaming responses
• Pydantic-based configuration
• Callable and OpenAI LLM adapters

Development

uv sync --extra dev --extra openai
uv run ruff check .
uv run mypy
uv run pytest
uv run mkdocs build --strict
uv build

Install the private python-rag-framework repository separately when you want to run the RAG integration example or test.

Runnable examples live in examples/.

Documentation lives in docs/ and is configured with mkdocs.yml.

Published documentation:

https://lelouchzr.github.io/python-agent-runtime/