agent-runtime

Model-agnostic Execution Runtime for LLM-based Agents

Provides a standardized execution loop, tool integration, and traceable/debuggable agent runtime that can work with any LLM or model backend.

---

Features

• Model-Agnostic: Plug in OpenAI, Claude, local LLMs, or future models.
• Standard Agent Loop: Think → Act → Observe → Update.
• Tool Integration: Easy to define and call tools with structured input/output.
• Traceability & Replay: Full step-by-step trace for debugging and replay.
• Extensible: Add adapters, tools, and policies with minimal effort.

---

Architecture

┌──────────────┐
│   Prompt     │
└─────┬────────┘
      │
      ▼
┌──────────────┐
│   Agent Core │
│ (State + Mem)│
└─────┬────────┘
      │
┌─────┴─────────┐
▼               ▼
┌─────────────┐ ┌───────────────┐
│ LLM Adapter │ │ Tool Executor │
│ generate()  │ │ call(tool)    │
└─────┬───────┘ └─────┬─────────┘
      │               │
      ▼               ▼
   LLM Response   Tool Output
      │               │
      └──────┬────────┘
             ▼
      ┌──────────────┐
      │ TraceManager │
      │ record(step) │
      └─────┬────────┘
            ▼
   Replay / Debug Interface

Components:

1. Agent Core - Maintains agent state, memory, and execution loop.
2. LLM Adapter - Abstract interface for any LLM backend.
3. Tool Executor - Standardized tool invocation with input/output schema.
4. Trace Manager - Records every step for replay/debug.
5. Replay / Debug Interface - CLI or Web UI to replay agent actions for validation.

---

Quick Start

# clone repo
git clone https://github.com/lewiscutey/agent-runtime.git
cd agent-runtime

# install dependencies
npm install

# set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# run demo
npm run demo

---

Example Usage

import { Agent, OpenAIAdapter, Tool } from './src'

// Define a simple LLM adapter
const llm = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4'
})

// Define a sample tool
const calculatorTool = new Tool({
  name: 'calculator',
  description: 'Evaluates mathematical expressions',
  schema: {
    expression: 'string'
  },
  func: input => {
    try {
      return { result: eval(input.expression) }
    } catch (error) {
      return { error: error.message }
    }
  }
})

// Initialize agent
const agent = new Agent({
  llm,
  tools: [calculatorTool]
})

// Run agent loop
await agent.run({
  prompt: 'Calculate 2 + 2 and then multiply the result by 5',
  maxSteps: 5
})

// Replay / debug
agent.replay()

---

API Overview

Component	Main Methods / Interfaces	Description
Agent	run(prompt, maxSteps)	Executes the agent loop
	replay()	Replay the full execution trace
	addTool(tool)	Add additional tool to agent
LLMAdapter	generate(prompt, context)	Returns model response
Tool	call(input)	Executes tool function with input/output schema
TraceManager	record(step)	Records agent execution step
	getTrace()	Returns full trace for replay/debug

---

Project Structure

agent-runtime/
├── src/
│   ├── core/
│   │   ├── Agent.ts          # Main agent implementation
│   │   ├── Tool.ts           # Tool interface and base class
│   │   └── TraceManager.ts   # Execution trace recording
│   ├── adapters/
│   │   ├── LLMAdapter.ts     # Base LLM adapter interface
│   │   ├── OpenAIAdapter.ts  # OpenAI implementation
│   │   └── ClaudeAdapter.ts  # Anthropic Claude implementation
│   ├── tools/
│   │   ├── calculator.ts     # Example calculator tool
│   │   └── weather.ts        # Example weather tool
│   └── index.ts              # Main exports
├── examples/
│   ├── demo-agent.ts         # Basic demo
│   └── advanced-agent.ts     # Advanced usage
├── tests/
│   └── agent.test.ts
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

---

Contributing

• Add new LLM adapters in src/adapters/
• Add tools in src/tools/
• Add examples in examples/

---

License

MIT