orcakit-harness-agent 1.0.12

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, aappend_messages, 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.
• Recall is frozen once per user turn and appended to the model-facing user message, keeping the system prompt stable. Checkpoints preserve recall snapshots for exact replay while chat history and capture retain the original user text. See recall and prompt caching.

Tools & skills

• Built-in tools: browser (harness-browser), web search, files, ask_user_question for respond-only human decisions, optional Seedream/Seedance media generation, sub-agents, and MCP tools. Set ask_user_enabled=False for unattended agents.
• Skills come from the Deep Agents skills middleware; manage them per agent via the CLI.
• Optional system_files_path (e.g. .octop) keeps skills, sessions, .env, and sqlite under a workspace subdir while persona markdown stays at the root.

Enable provider-neutral generate_image and generate_video tools with Volcengine Ark:

from harness_agent import HarnessAgentConfig, MediaGenerationConfig

config = HarnessAgentConfig(
    # ...providers/default_model...
    media_generation=MediaGenerationConfig(api_key_env="ARK_API_KEY"),
)

Generated files are stored under generated/images/ and generated/videos/ in the agent workspace. The tools are deferred by default and become visible through the configured tool-search strategy only when needed. Expected provider failures return a structured, model-visible error envelope with retry guidance instead of terminating the agent stream.

Multi-agent & collaboration

• Multiple isolated agents per process via AgentManager + registry.
• Teams peer inbox for agent-to-agent messaging. peer_invoke_mode selects the ask_agent surface (sync / async / both); request-scoped overrides may tighten it but cannot add background dispatch.
• 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="")

Progressive tool loading

Large, low-frequency tool sets can be hidden until the model needs them. The default client mode registers an ordinary tool_search function, so it works with any Chat Completions-compatible model that supports function calling. A deferred tool remains visible by its real name and short description, while its parameter schema is replaced by a lightweight reference. A search result is appended to the conversation, the matched full schemas replace their references on the next model step, and the loaded set persists for the thread. The selected tool is still called by its real name through the normal DeepAgents ToolNode, security guard, and interrupt policy.

from harness_agent import HarnessAgentConfig, ProviderConfig

provider = ProviderConfig(
    id="openai",
    base_url="https://openai-compatible.example/v1",
    api_key="sk-...",
    protocol="openai",
)

config = HarnessAgentConfig(
    providers=[provider],
    default_model="openai/your-function-calling-model",
    tools=[generate_image, generate_video, generate_3d_asset],
    deferred_tools=frozenset(
        {"generate_image", "generate_video", "generate_3d_asset"},
    ),
    defer_mcp_tools=True,
    tool_search_mode="client",  # default; no Responses API required
)

Set tool_search_mode="native" to use OpenAI Responses hosted tool_search or Anthropic hosted defer_loading / tool_reference. Native mode additionally requires ModelConfig.native_tool_search=True; unsupported routed models use the configured tool_search_fallback. Set the mode to eager to disable progressive loading.

📑 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 against main

Module boundaries and coding conventions: AGENTS.md.

See CONTRIBUTING.md for branching, PR, and release details (release/* → main auto-publishes to PyPI).

🔗 Related projects

📄 License

This project is licensed under the MIT License.