OpsMate

Stateful Agent Runtime and Orchestration System

OpsMate is an execution-centric agent runtime designed to enable reliable multi-step, context-aware interactions beyond stateless prompt-response systems. It introduces structured state, controlled execution flow, and modular tool orchestration for real-world AI system deployment.

---

Overview

Traditional LLM applications operate as stateless interfaces, making them unreliable for multi-step workflows, tool usage, and persistent interactions.

OpsMate addresses this by providing a runtime layer that:

• maintains session-aware state across interactions
• enforces controlled execution of agent decisions
• enables consistent and modular tool integration
• supports persistent memory and retrieval

---

System Architecture

OpsMate is structured as a runtime system composed of:

• Runtime Manager Coordinates system components and lifecycle.

• Agent Executor Handles decision execution, including LLM interaction and tool routing.

• LLM Provider Abstract interface for model inference (e.g. OpenAI).

• Tool Registry (MCP Integration) Manages available tools and external capabilities.

• Memory Layer (Chroma) Provides vector-based contextual retrieval.

• Persistence Layer (SQLModel + SQLite) Stores sessions and interaction history.

---

Execution Flow

User Request
   ↓
FastAPI API Layer
   ↓
Runtime Manager
   ↓
Agent Executor
   ↓
LLM Decision
   ↓
Tool Execution (optional via MCP)
   ↓
Response
   ↓
Persistence + Memory Update

---

Features

• Stateful multi-step agent execution
• Session-aware memory and retrieval
• MCP-based tool orchestration
• Streaming responses
• Authentication and session management
• Persistent storage for interactions
• Containerized deployment

---

Deployment

OpsMate is packaged as a containerized FastAPI backend with:

• explicit environment configuration
• reproducible dependency management
• modular package structure
• Chrome extension interface for real-time interaction

---

Getting Started

1. Clone the repository

git clone <repo-url>
cd opsmate

---

2. Set environment variables

Create a .env file in the project root:

OPENAI_API_KEY=your_key_here
JWT_SECRET_KEY=your_secret_here

---

3. Run locally

cd apps/api
uv run uvicorn opsmate_api.main:app --reload --app-dir src

---

4. Run with Docker

docker compose up --build

---

5. Access API

• API: http://localhost:8000
• Docs: http://localhost:8000/docs

---

Chrome Extension

OpsMate includes a Chrome extension for real-time interaction with the runtime:

• streaming responses
• session continuity
• authenticated requests

Load the extension from:

apps/extension/

via Chrome Developer Mode.

---

Design Principles

OpsMate is built around:

• Execution over prompting Decisions are executed within a controlled runtime.

• State over statelessness Sessions maintain continuity across interactions.

• Separation of concerns Decision-making, execution, memory, and tooling are modular.

• Reproducibility Environment and dependencies are explicitly defined.

---

Roadmap

• Execution-aware policy optimisation (Agent Learning integration)
• Enhanced tool reasoning strategies
• Distributed runtime support
• Advanced evaluation and tracing

---

License

MIT License