Agent Runtime

Agent Runtime is a Python framework for building AI agents with tool integration, multi-agent workflows, and evaluation loops.

Quick Links: 📖 User Guide • 🛠️ Developer Guide • 📚 Examples

---

What Makes Agent Runtime Different

• ✅ Multi-Agent Workflows - Coordinate multiple specialist agents with intelligent task delegation
• ✅ MCP Integration - Native tool discovery via Model Context Protocol
• ✅ Evaluation Loops - Built-in quality assessment with automatic retry on failure
• ✅ Context Management - Automatic context compaction for long conversations
• ✅ YAML Configuration - Declarative agent and workflow definitions

---

Quick Start

Requirements

• Python 3.13+
• OpenAI API key (or other LLM provider)

Installation

pip install nova-agent-runtime

Environment Variables

Set your LLM provider API key:

export OPENAI_API_KEY="your-api-key-here"
# OR
export ANTHROPIC_API_KEY="your-api-key-here"

Your First Agent

import asyncio
from pathlib import Path
from agent_runtime import AgentConfig, create_agent

# Load agent config from YAML file
config = AgentConfig.parse_config(Path("agent_config.yaml"))

# Create agent using factory function
agent = create_agent(config, debug=True)

# Run the agent
result = asyncio.run(agent.run("Hello!"))
print(result)

Minimal agent_config.yaml:

id: "minimal_agent"
description: "A minimal agent with no tools"
llm:
  provider: "openai"
  model: "gpt-4.1-mini"
  token_budget: 4000

For agents with tool integration, see examples/1_agent/02_agent_with_tools.py.

Next Steps:

• User Guide - Complete guide to building agents
• Patterns - Common patterns and best practices
• Examples - More code examples and use cases

Additional Environment Variables for Examples

Some examples require additional API keys:

• EXA_API_KEY - Required for examples using Exa web search:
  • examples/1_agent/02_agent_with_tools.py
  • examples/3_primitives/06_tool_discovery.py
• GITHUB_PAT - Required for GitHub MCP examples:
  • examples/1_agent/05_github_integration.py

---

Key Features

Tool Integration

Native MCP support with automatic tool discovery, plus local Python tools via @to_tool decorator. Examples →

Evaluation & Quality

Built-in evaluation loops with DeepEval integration for automatic quality assessment and retry on failure. Learn more →

---

Model Context Protocol (MCP) Integration

Agent Runtime provides native support for the Model Context Protocol, enabling agents to automatically discover and use tools from MCP servers.

Quick Start

import asyncio
from pathlib import Path
from agent_runtime import AgentConfig, create_agent

# Load agent config with MCP tools configured
config = AgentConfig.parse_config(Path("research_agent.yaml"))
agent = create_agent(config, debug=True)

# MCP tools are automatically available based on config
result = asyncio.run(agent.run("Search for the latest AI news"))

Configuration

Python Module Configuration

Define MCP servers in Python modules and reference them in agent configs:

Step 1: Create MCP configuration module:

# examples/configs/my_mcp.py
"""MCP server configuration."""

MCP_CONFIG = {
    "mcpServers": {
        "exa": {
            "command": "npx",
            "args": ["-y", "exa-mcp-server"],
            "env": {"EXA_API_KEY": "${EXA_API_KEY}"}
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
        }
    }
}

Step 2: Reference in agent YAML config:

# agent_config.yaml
tools:
  mode: "all"
  sources:
    - type: "mcp"
      mcp_servers: "examples.configs.my_mcp.MCP_CONFIG"

Or in Python code:

from agent_runtime.types.config import ToolsConfig, McpConfig

tools_config = ToolsConfig(
    mode="all",
    sources=[
        McpConfig(mcp_servers="examples.configs.my_mcp.MCP_CONFIG")
    ]
)

See also: Examples Guide for more examples including GitHub integration and tool discovery.

---

Documentation

Guides

Document	Purpose	Audience
User Guide	Complete guide to building with Agent Runtime	All users
Developer Guide	Architecture, testing, and extending Agent Runtime	Contributors
Patterns	Common patterns with complete examples	Intermediate users
Troubleshooting	Error resolution and debugging	All users

Reference

Document	Purpose	Audience
Examples	Code examples and use cases	Users building with Agent Runtime
Agent Guide	Agent layer and MCP integration	Developers
Context Compaction	Managing long conversations	Advanced users

---

Development

Requirements

• Python 3.13+
• uv package manager

Installation

git clone https://github.com/SoraNovaAI/agent-runtime.git
cd agent-runtime
make sync

Examples Directory

examples/
  1_agent/       - Production-ready agent examples
    01_basic_agent.py           - Minimal agent (no tools)
    02_agent_with_tools.py      - Agent with MCP tools + evaluation
    03_agent_with_compaction.py - Context management
    04_structured_output.py     - Pydantic output models
    05_github_integration.py    - GitHub MCP integration
  2_workflows/   - Multi-agent workflow examples
  3_primitives/  - Low-level AugmentedLLM examples
    01_basic_usage.py           - Simplest AugmentedLLM usage
    02_local_tool.py            - @to_tool decorator
    03_stateful_tools.py        - Instance methods as tools
    04_custom_processor.py      - OutputTool structured responses
    05_input_type.py            - Structured input
    06_tool_discovery.py        - MCP tool discovery
  configs/       - MCP server configurations

Commands

make sync     # Install dependencies
make format   # Format code
make check    # Lint and type check
make test     # Run test suite

---

Architecture

Agent Runtime provides a layered architecture for building AI agents:

Agent Layer - Core agent functionality:

• Agent - High-level agent with three-phase execution: PLAN → ACT → EVALUATE
  • PLAN: Planner LLM creates execution plans for complex tasks
  • ACT: Executor LLM executes steps with tool calls
  • EVALUATE: Synthesiser produces output, evaluator assesses quality
• AugmentedLLM - Low-level LLM + tool execution primitive
• RunContext - Conversation history and state management

Tool Layer - Tool integration:

• ToolClient - Multi-server tool aggregation
• @to_tool - Decorator for local Python functions
• MCP support for remote tool servers

Workflow Layer - Multi-agent coordination:

• CoordinatorWorkflowRunner - Intelligent task delegation
• SequentialWorkflowRunner - Sequential block execution

See Agent Guide for details.

---

Use Cases

• Research Workflows: Multi-agent systems for comprehensive research and analysis
• Tool-Augmented Agents: Agents with access to web search, file systems, APIs
• Quality-Assured Responses: Evaluation loops for consistent output quality
• Complex Task Decomposition: Coordinator agents delegating to specialists

See Examples for code examples.

---

Contributing

Contributions are welcome! Please ensure:

• All tests pass: make test
• Code is formatted: make format
• No linter errors: make check
• Type hints are complete

Please read our Contributing Guide for more details.

License

MIT License - see LICENSE for details.