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
    instructions="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 has three configuration inputs: model, instructions, and plugins. 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. Class Inject[T] dependencies suspend and rebuild mounts as services change; provides=True publishes the mounted plugin as a service.
• Context: instructions and plugin guidance 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
• Instructions and changing context
• Sessions, controls, persistence and forks
• Typed events and custom extensions
• Approvals and headless operation
• Offline testing
• 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.