Introduction

HarnessX is a Python SDK for building agents that reason, call tools, and carry work across turns. You supply the model, tools, and policies. The harness runs the loop and exposes what happens along the way.

Start with one agent

A typed Python function can be a tool. Pass it when you construct the agent, then await a run.

import asyncio
from harnessx import Agent

def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

async def main():
    async with Agent(tools=[multiply]) as agent:
        result = await agent.run("What is 40 * 10? Use multiply.")
        if result.error:
            raise RuntimeError(result.error["message"])
        print(result.output)

asyncio.run(main())

This example makes live calls using the default Anthropic provider. Export your API key first. Custom tools inherit the default ALLOW policy; choose explicit permissions for tools with external effects.

What the harness provides

Layer	What it does	Learn more
Agent loop	Sends context to a provider, validates and dispatches tools, returns results	Agents
Capabilities	Typed functions, external MCP tools, lazy skill instructions, and OKF knowledge bundles	Tools, MCP, Skills, Knowledge
Context	Conversation history, notes, structured facts, and result spilling	Memory
Decisions	Standalone Choice routing, Score rubrics, and Noul evidence assessments	Decisions with Jev
Control	Permissions, explicit approval, budgets, and replay policies	Permissions
Execution	Direct runs or durable sessions with persisted execution boundaries	Durable agent runs (advanced)
Inspection	Typed streaming events, lifecycle hooks, traces, and incident archives	Streaming, Flight recorder

Choose the execution model

Use Agent for an in-process conversation or request. It retains history while the instance lives. Use snapshots to explicitly save and reload a conversation.

The advanced Durable agent runs guide introduces AgentRuntime for work that must pause for an approval or be recovered after a process failure. Its default SQLite backend persists execution state and events. PostgreSQL and Temporal implementations exist, with service qualification still required.

These are two entry points into the shared execution engine. Ordinary and streaming runs use the same tool and permission semantics.

Explore the city

The city map is an interactive map of the SDK: the workshops are tools, the crossing is permissions, the archive is memory, the vault is the flight recorder, and the fenced yard is the sandbox. Select a district to learn what it represents and follow its link into these docs.

The city illustrates the architecture; it is not connected to a running agent.

Know the boundaries

HarnessX does not promise universal rollback or exactly-once external writes. Recovery depends on the tool's replay policy and its adapter. Incident playback displays captured records without running models or tools; it is not a deterministic rerun of a live model.

See Implementation status for available, service-dependent, and planned capabilities.