nova-agent-runtime 0.0.0a1
Python framework for building AI agents with tool integration, multi-agent workflows, and evaluation loops
Requires Python: >=3.13

# 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](docs/guides/USER_GUIDE.md) • 🛠️ [Developer Guide](docs/guides/DEVELOPER_GUIDE.md) • 📚 [Examples](docs/guides/EXAMPLES.md)

---

## 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

```bash
pip install nova-agent-runtime
```

### Environment Variables

Set your LLM provider API key:

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

### Your First Agent

```python
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:**

```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](docs/guides/USER_GUIDE.md) - Complete guide to building agents
- [Patterns](docs/guides/PATTERNS.md) - Common patterns and best practices
- [Examples](docs/guides/EXAMPLES.md) - 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 →](docs/guides/EXAMPLES.md#basic-examples)

### Evaluation & Quality

Built-in evaluation loops with DeepEval integration for automatic quality assessment and retry on failure. [Learn more →](docs/guides/AGENT.md)

---

## Model Context Protocol (MCP) Integration

Agent Runtime provides native support for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling agents to automatically discover and use tools from MCP servers.

### Quick Start

```python
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:

```python
# 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:

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

Or in Python code:

```python
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](docs/guides/EXAMPLES.md) for more examples including GitHub integration and tool discovery.

---

## Documentation

### Guides

| Document | Purpose | Audience |
| -------- | ------- | -------- |
| **[User Guide](docs/guides/USER_GUIDE.md)** | Complete guide to building with Agent Runtime | All users |
| **[Developer Guide](docs/guides/DEVELOPER_GUIDE.md)** | Architecture, testing, and extending Agent Runtime | Contributors |
| **[Patterns](docs/guides/PATTERNS.md)** | Common patterns with complete examples | Intermediate users |
| **[Troubleshooting](docs/guides/TROUBLESHOOTING.md)** | Error resolution and debugging | All users |

### Reference

| Document | Purpose | Audience |
| -------- | ------- | -------- |
| **[Examples](docs/guides/EXAMPLES.md)** | Code examples and use cases | Users building with Agent Runtime |
| **[Agent Guide](docs/guides/AGENT.md)** | Agent layer and MCP integration | Developers |
| **[Context Compaction](docs/guides/CONTEXT_COMPACTION.md)** | Managing long conversations | Advanced users |

---

## Development

### Requirements

- Python 3.13+
- `uv` package manager

### Installation

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

### Examples Directory

```text
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

```bash
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](docs/guides/AGENT.md) 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](docs/guides/EXAMPLES.md) 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](CONTRIBUTING.md) for more details.

## License

MIT License - see [LICENSE](LICENSE) for details.