Agent Runtime Lab

A public, experimental laboratory for designing production-grade agent runtimes.

This repository focuses on the parts of agent systems that are usually missing from demos:

• deterministic execution loops
• tool isolation
• memory boundaries
• retries and failure handling
• observability and tracing

Agents plan. Tools execute. Memory stores state. The runtime enforces the loop.

Why This Exists

Most agent frameworks emphasize prompts and model outputs. In real systems, failures happen around the model:

• tools fail
• networks time out
• state becomes inconsistent
• retries need control
• offline execution must still work

This project demonstrates how to structure agents as systems, not scripts.

Agent Execution Model

All agents follow the same runtime-enforced loop:

Observe → Plan → Select Tool → Execute → Update State → Repeat / Exit

• Agents decide what to do
• Tools perform side effects
• Memory stores durable state
• The runtime controls retries, errors, and termination

See ARCHITECTURE.md for detailed design documentation.

Who This Is For

• Engineers building agentic systems beyond demos
• Teams integrating LLMs into production workflows
• Developers who care about reliability, retries, and observability
• Anyone looking for a reference implementation of agent runtimes

Quick Start

# Clone and install
git clone https://github.com/itpixelz/agent-runtime-lab.git
cd agent-runtime-lab
pip install -e .

# Run the offline counter agent (no LLM, no network)
python examples/counter_agent.py

# Run the news agent (no LLM required)
python examples/run_news_agent.py --no-llm

Examples

The counter agent demonstrates the runtime loop without any LLM or network dependency.

Example	Description	Dependencies
counter_agent.py	Minimal runtime loop demo	None (offline)
custom_tool.py	How to create custom tools	None (offline)
custom_agent.py	How to create custom agents	None (offline)
with_memory.py	Using the memory store for persistence	None (offline)
run_news_agent.py	Full news aggregation pipeline	Network (RSS feeds)

# Minimal offline example
python examples/counter_agent.py

# Learn to create custom tools
python examples/custom_tool.py

# Learn to create custom agents
python examples/custom_agent.py --items "task1,task2,task3"

# Using persistent storage
python examples/with_memory.py

# Full news agent (requires network)
python examples/run_news_agent.py --no-llm

Project Structure

agent-runtime-lab/
├── runtime/          # Execution loop, retries, tracing, tool registry
├── agents/           # Agent definitions (planner, decision-making)
├── tools/            # Stateless tool implementations
├── memory/           # Storage abstraction (SQLite default, Postgres optional)
├── interfaces/       # CLI entry point
├── packages/         # Reusable domain packages (news_pipeline)
├── config/           # Default settings and example feeds
├── examples/         # Runnable demos
└── tests/            # Test suite

Configuration

Copy .env.example to .env and adjust as needed:

cp .env.example .env

Variable	Default	Description
SUMMARIZER_BACKEND	stub	Use llm for Ollama, stub for deterministic
OLLAMA_MODEL	llama3.2	Model for LLM summarization
OLLAMA_HOST	http://localhost:11434	Ollama server URL
DATABASE_URL	(SQLite)	Set to postgresql://... for Postgres
SQLITE_PATH	agent_runtime.db	SQLite database file path

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Safety scan (required before commits)
./scripts/safety_scan.sh

Contributing

See CONTRIBUTING.md for guidelines.

Please note that this project has a Code of Conduct.

Security

To report security vulnerabilities, see SECURITY.md.

License

MIT License. See LICENSE.