Harnessed

A Python agent SDK built from reversible plugins. Harnessed owns the loop, tool policies and append-only session log; optional provider integrations use PydanticAI's Direct API. Python 3.12-3.14, Pydantic v2 and modern generics.

Harnessed 0.x is alpha software. APIs and persisted session formats may change in minor releases before 1.0. See the release notes and compatibility policy.

Core SDK

uv add "harnessed[openai]"

import asyncio
from harnessed import Agent, Plugin, tool


class Calculator(Plugin):
    @tool(readonly=True)
    async def add(self, a: int, b: int) -> int:
        """Add two integers."""
        return a + b


agent = Agent(
    model="deepseek:deepseek-chat",  # DEEPSEEK_API_KEY
    system_prompt="Keep answers concise.",
    plugins=[Calculator()],
)


async def main():
    async with agent.session() as session:
        result = await session.run("What is 19 + 23?")
        print(result.text)


asyncio.run(main())

Agent composes model, system_prompt and plugins; plugin_validation controls how missing services are reported at startup. It is reusable; each session owns its runtime and plugin lifetimes.

• Composition: tools, policies and capabilities are plugins. Slots replace defaults, and agent.plugins shows the resolved composition.
• Ownership: removing a plugin removes its registrations and effects. Explicit needs=(...) requirements suspend and rebuild mounts as services change. Inject[T] binds values; provides=True publishes the mounted plugin.
• Context: explicitly ordered system sections are fixed per session; named context values and steering supply changes during a run.
• History: immutable events are the source of truth. Persistence, replay, forks and control outcomes use the same append-only log.

Test without credentials

from harnessed.testing import ScriptedModel, assert_tool_called, call, reply

model = ScriptedModel([call(Calculator.add, a=19, b=23), reply("42")])
agent = Agent(model=model, plugins=[Calculator()])

# Inside an async function:
# result = await agent.run("Add 19 and 23")
# assert_tool_called(result, "add", a=19, b=23)

Read by topic

Start with the documentation index or the SDK reference.

• Models and provider settings
• Tools, hooks and cancellation
• Plugin composition and lifecycle
• MCP server tools over stdio and HTTP
• Docker and Bubblewrap sandboxes
• Instructions and changing context
• Sessions, controls, persistence and forks
• Typed events and custom extensions
• Approvals and headless operation
• Offline testing
• OpenTelemetry tracing with Phoenix and Langfuse
• Executable examples
• Development and CI
• Changelog and breaking changes

The standalone harnessed.kernel uses only the standard library. Optional features live under harnessed.plugins; providers live under harnessed.models.

Inspired by DeepSeek Harness and Cordis.

Released under the MIT License.