orcakit-harness-agent 0.9.17

Production-grade agent runtime built on the Harness theory — a thin, production-ready façade over Deep Agents.

Highlights · Overview · Core Technology · Features · Quick Start · Contents

English · 中文

Harness Agent is a production-grade agent runtime built on the harness engineering theory. At its core it is a thin, battle-tested encapsulation and engineering layer around Deep Agents — we take the elegant create_deep_agent primitive from Deep Agents and package it with everything you need to run agents in production: multi-provider model routing, persistent memory, browser/search tools, a multi-agent registry, pluggable storage backends, and a terminal CLI.

💜 A tribute to Deep Agents. Harness Agent stands on the shoulders of Deep Agents (by the LangChain team). Our HarnessAgent ultimately delegates to deepagents.create_deep_agent, and everything else — model routing, backends, tiered memory, the agent registry, CLI, and ACP — is the engineering we added on top. Deep Agents gives us the agentic foundation; Harness gives it a home for production.

✨ Highlights

📌 Overview

Harness Agent is a library (not an app) that turns Deep Agents into a deployable runtime. A single HarnessAgentManager owns a registry of agents; each agent wires together a model, a set of tools/skills, a memory backend, and a LangGraph checkpoint — all assembled through the harness layering discipline (L0 I/O helpers → L1 workspace facade → L2 business logic → L3 assembly).

Harness Agent's design goal: let you build a production-grade agent from Deep Agents in a few lines of code, while keeping model choice, memory, storage, and safety swappable without rewriting your agent.

🧠 Core Technology

🤔 Features

Agent runtime

• HarnessAgentManager — a registry that creates, lists, and streams many agents in one process.
• HarnessAgent — exposes call, stream, stream_events, aget_history, and cancel.
• Checkpointing via LangGraph AsyncSqliteSaver (or a harness-memory saver) for resumable chats.

Model routing & providers

• ChatModelFactory resolves a model name to the right client.
• First-class providers: OpenAI (incl. OpenAI-compatible via base_url), Anthropic, and AWS Bedrock (optional [bedrock] extra).
• 17 user-editable provider presets, including Hunyuan, Kimi, GLM, DeepSeek, MiniMax, and Moonshot.

Memory (tiered)

• Each turn is captured as L0 raw events, then distilled asynchronously into L2 atoms (AtomCards) and L3 entity pages.
• Powered by the harness-memory middleware; memory travels with the workspace.

Tools & skills

• Built-in tools: browser (harness-browser), web search, files, sub-agents, and MCP tools.
• Skills come from the Deep Agents skills middleware; manage them per agent via the CLI.

Multi-agent & collaboration

• Multiple isolated agents per process via AgentManager + registry.
• Teams peer inbox for agent-to-agent messaging.
• ACP stdio server so external IDE / terminal AIs can invoke your agent.

Safety

• SecurityPolicy with tool guardrails, filesystem permissions (FilesystemPermission), and PII redaction middleware.

CLI

harness-agent provides: init, chat, agent, config (e.g. config provider add), skill, and update.

🚀 Quick Start

Prerequisites

• Python 3.11+
• A model provider API key (OpenAI / Anthropic / Bedrock / compatible)

1. Install

# Core SDK — agent runtime, model routing, tools, skills, backends
pip install orcakit-harness-agent

# With the terminal CLI — interactive chat, config, skill management
pip install orcakit-harness-agent[cli]

# Multiple extras — comma-separated inside one pair of brackets (quote for the shell):
pip install 'orcakit-harness-agent[object-storage,desktop]'
pip install 'orcakit-harness-agent[cli,all]'

Optional dependency extras (install only what you need; missing extras fail at use-time with an install hint):

2. Initialize & configure

harness-agent init
harness-agent config provider add   # choose a provider and paste your key

3. Chat

harness-agent chat

Programmatic use

from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig, ChatRequest

manager = HarnessAgentManager()
agent: HarnessAgentConfig = manager.create_agent(
    name="assistant",
    provider=ProviderConfig(name="openai", api_key="sk-..."),
    model="gpt-4o",
)
request = ChatRequest(message="Summarize the Harness theory in one paragraph.")
async for chunk in agent.stream(request):
    print(chunk.delta, end="")

📑 Contents

• Highlights
• Overview
• Core Technology
• Features
• Quick Start
• Reference
  • CLI reference
  • Project layout
  • Development
• Project Info
  • Contributing
  • Related projects
  • License

📖 CLI reference

📁 Project layout

src/harness_agent/
  agent.py          facade over deepagents.create_deep_agent
  manager.py        AgentManager — multi-agent registry
  config/           configs, provider & model presets
  llm/factory.py    ChatModelFactory — model routing
  backends/         BackendWorkspace — local / S3 / COS / Postgres
  builtin/          tools + skills + seed files
  middleware/       model_router, skill_filter, tool_guard, memory, pii, ...
  memory/           MemoryRuntime (harness-memory wrapper)
  protocols/        langgraph / openai / mcp streaming
  acp/             ACP stdio server
  teams/           peer inbox
  cli/             terminal CLI

🛠️ Development

Prerequisites: Python 3.11+, uv

make install          # pip install -e ".[cli,dev]"
make all              # lint + typecheck + test

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run make all before submitting
4. Open a Pull Request

Module boundaries and coding conventions: AGENTS.md.

🔗 Related projects

📄 License

This project is licensed under the MIT License.