Agent Harness — Python Production Agent Runtime

Filesystem-first agent runtime for Python. Define agents as files on disk. Run them via CLI or serve via API.

Agent Harness is a production-grade runtime that treats your agents as files on disk — not code scattered across notebooks. Define your agent's personality, tools, and memory in a structured directory, then run it from the command line or expose it as a FastAPI service. Built for developers who want full control over their agent's behavior without wrestling with framework abstractions.

---

Features

• Filesystem-first agent definitions — Agents live as structured directories on disk. Version them with git, edit them in any editor, deploy them by copying a folder.
• CLI tool — Scaffold, run, and manage agents entirely from the command line with harness init, harness run, and harness serve.
• ReAct agent loop — Implements the Reasoning + Acting pattern with configurable iteration limits, error recovery, and structured output parsing.
• Tool registry — Register Python functions as callable tools. Agents discover and invoke tools at runtime based on task requirements.
• Session memory — Maintain conversation history and context across interactions with built-in session management and optional persistence.
• Multi-provider — Switch between OpenAI, Anthropic, local models, and custom providers with a single config change. No vendor lock-in.
• FastAPI server — Serve any agent as a REST API with automatic OpenAPI docs, streaming support, and health checks.

---

Quick Start

Install

pip install agent-harness

Scaffold a new agent

harness init my-agent

This creates a ready-to-run agent directory:

my-agent/
├── agent.yaml          # Agent configuration
├── prompts/
│   └── system.md       # System prompt
└── tools/
    └── calculator.py   # Example tool

Run your agent

harness run my-agent "hello"

Serve via API

harness serve my-agent --port 8000

Then interact with it at http://localhost:8000/chat.

---

Agent Structure

Each agent is a directory with a well-defined layout:

agent/
├── agent.yaml              # Agent name, model, provider, temperature
├── prompts/
│   ├── system.md           # System prompt (supports Jinja2 templating)
│   └── examples.md         # Few-shot examples (optional)
├── tools/
│   ├── calculator.py       # Custom tool implementations
│   ├── file_read.py        # Built-in tools can be overridden
│   └── bash.py
├── skills/                 # Skill definitions loaded at runtime
│   └── coding.md
└── memory/
    └── sessions/           # Persistent session storage

agent.yaml example

name: my-agent
model: gpt-4o
provider: openai
temperature: 0.7
max_iterations: 10
tools:
  - calculator
  - file_read
  - bash
system_prompt: prompts/system.md

---

API Reference

When serving an agent via harness serve, the following endpoints are available:

Method	Endpoint	Description
POST	/chat	Send a message and get a response
POST	/chat/stream	Send a message and stream the output
GET	/health	Health check and agent status

POST /chat

{
  "message": "Calculate the square root of 144",
  "session_id": "optional-session-id",
  "context": {}
}

Response:

{
  "response": "The square root of 144 is 12.",
  "tools_used": ["calculator"],
  "iterations": 1,
  "session_id": "abc-123"
}

GET /health

{
  "status": "healthy",
  "agent": "my-agent",
  "model": "gpt-4o",
  "provider": "openai",
  "uptime": 3600
}

---

Built-in Tools

Agent Harness ships with three built-in tools that agents can use out of the box:

Tool	Description
calculator	Evaluate mathematical expressions safely
file_read	Read file contents from the local filesystem
bash	Execute shell commands with configurable permissions

Tools can be extended, replaced, or augmented by adding Python files to your agent's tools/ directory. Each tool is a Python module with a run() function that accepts a string argument and returns a string result.

---

Testing

pip install pytest && pytest tests/ -v

---

Ecosystem

Agent Harness is part of a growing ecosystem of tools for building production AI agents:

Project	Description
fastapi-ai-kit	FastAPI boilerplate for AI-powered applications
agent-memory-kit	Persistent memory and context management for agents
agent-security-kit	Input validation, output filtering, and guardrails
awesome-mcp-servers	Curated list of Model Context Protocol servers
agent-skill-kit	Define, version, and share reusable agent skills
skill-optimizer	Compress and benchmark SKILL.md files for efficiency
llm-economizer	Token cost optimization proxy for LLM APIs

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ❤️ for the AI agent community.

If you find this useful, please consider giving it a star ⭐