Harnessed

A Python agent SDK built from reversible plugins. Harnessed owns the loop, tool policies and explicit conversation state; 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. Libraries publish defaults with Kit; slots replace them and without() excludes recipe types. agent.describe() shows the resolved order, origins and replacement history.
• 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.
• State: export an immutable SessionState and inject it into the next run. Applications own persistence; completed conversations are not archived by the agent. Compaction retains only the active summary and selected context.

Continue a conversation

from harnessed import SessionState

# Inside an async function; your application owns the repository.
payload = await repository.load(conversation_id)
state = SessionState.from_json(payload) if payload is not None else None
result = await agent.run("Continue.", state=state)
await repository.save(conversation_id, result.state.to_json())

State includes retained context and referenced image/spill contents. Export and import perform no storage I/O. See sessions for ownership, compaction, live controls and independent continuations.

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 and application-owned state
• 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.