orcakit-harness-agent 0.8.0

Production-grade Harness Agent built on top of LangChain Deep Agents.

Harness Agent

Production-grade AI agent platform built on LangChain Deep Agents.

English · 中文

---

Highlights

• Deep Agent Architecture — Built on LangGraph with hierarchical agent routing, tool orchestration, and stateful conversation management
• Multi-Agent Management — AgentManager registry with metadata/tags, per-thread cancel, and id-based stream routing
• Multi-Model Support — OpenAI, Anthropic, AWS Bedrock, and any OpenAI-compatible endpoint out of the box; 17 provider presets in a user-editable JSON template
• Built-in Tool Ecosystem — Browser automation, desktop screenshots, web search (Tavily/Brave/Google/Kimi), and extensible skill system
• Production Ready — Checkpoint persistence, configurable backends (SQLite, S3, COS, PostgreSQL), and structured logging
• Terminal-First CLI — Rich interactive chat interface with skill management, config wizard, and workspace initialization

---

Overview

Harness Agent is an open-source AI agent framework that provides a complete runtime for building, deploying, and managing autonomous AI agents. It wraps LangChain Deep Agents with batteries-included tooling: multi-provider model routing, persistent memory via harness-memory, browser automation via harness-browser, and a terminal CLI for interactive use.

The project is a single Python package with an optional CLI extra:

Install	Description
pip install orcakit-harness-agent	Core SDK — agent runtime, model routing, tools, skills, backends
pip install orcakit-harness-agent[cli]	Adds the terminal CLI — interactive chat, config, skill management

---

Core Technology

Layer	Technology	Purpose
Agent Runtime	LangGraph + Deep Agents	Stateful graph execution with hierarchical agent routing
Model Providers	LangChain model integrations	Unified interface for OpenAI, Anthropic, Bedrock, and custom endpoints
Memory	harness-memory	Hierarchical recall with FTS search and pluggable backends
Browser	harness-browser	CDP-based browser automation with profile-persistent login
Checkpointing	LangGraph Checkpoint + SQLite/Postgres	Conversation state persistence across sessions
CLI Framework	Click + Rich + Textual	Terminal UI with streaming output and rich formatting

---

Features

Agent Runtime

• Hierarchical agent routing with configurable delegation
• AgentManager — in-memory registry for creating and managing multiple agents by agent_id
• Stateful conversation management with checkpoint persistence
• Per-thread stream cancellation via manager.cancel(agent_id, thread_id)
• Middleware pipeline for request/response interception
• Configurable system prompts and persona management

Model Routing

• OpenAI — GPT-4o, GPT-4, GPT-3.5, and any compatible endpoint
• Anthropic — Claude 4 Sonnet, Claude 4 Opus, Claude 3.5 family
• AWS Bedrock — Claude, Titan, and other Bedrock models
• Custom — Any OpenAI-compatible API via base URL configuration

Built-in Tools

• Browser Automation — Navigate, click, type, screenshot via harness-browser
• Desktop Screenshot — Full-screen capture for visual context
• Web Search — Tavily, Brave, Google, Kimi (auto-detect or explicit selection)
• Extensible Skills — Custom tool registration with typed schemas

Storage Backends

• SQLite — Zero-config local persistence (default)
• Tencent Cloud COS — Object storage for attachments and artifacts
• Remote Backends — S3, PostgreSQL, Azure, GCS, MongoDB, Redis via deepagents-backends

CLI

• Interactive streaming chat with rich markdown rendering
• Workspace initialization (harness-agent init)
• Provider configuration wizard (harness-agent config provider add)
• Skill management and discovery

---

Quick Start

# Install the CLI (includes core SDK)
pip install orcakit-harness-agent[cli]

# Initialize workspace
harness-agent init

# Configure a model provider
harness-agent config provider add

# Start chatting
harness-agent chat

Programmatic Usage

from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig, ChatRequest

config = HarnessAgentConfig(
    workspace_dir="./workspace",
    providers=[ProviderConfig(id="openai", api_key="sk-...", models=["gpt-4o"])],
)

manager = HarnessAgentManager()
entry = manager.create_agent(config)

async for chunk in manager.stream(entry.agent_id, ChatRequest(messages="Hello!")):
    print(chunk.content, end="", flush=True)

Advanced: For direct backend operations, access the cached agent via entry.agent. HarnessAgent can also be constructed directly, but AgentManager is the recommended entry point for all new code.

Multi-Agent Management

from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig

manager = HarnessAgentManager()

# Register agents with metadata and tags
entry = manager.create_agent(
    config,
    metadata={"tenant": "acme", "env": "prod"},
    tags=["fast", "gpt4o"],
)

# Query agents by metadata / tags
agents = manager.list_agents(metadata={"env": "prod"}, tags=["fast"])

# Stream by agent_id
async for chunk in manager.stream(entry.agent_id, request):
    print(chunk)

# Cancel mid-stream
manager.cancel(entry.agent_id, request.thread_id)

---

Architecture

src/harness_agent/          Core SDK — agent runtime, model routing, tools, skills, backends
src/harness_agent/cli/      Terminal CLI — thin view layer over the SDK

The CLI is a thin view layer that delegates all agent logic to the core SDK. This separation enables future UIs (web, IDE extensions) to reuse the same SDK.

---

Development

Prerequisites: Python 3.11+, uv

git clone https://github.com/orcakit/harness-agent.git
cd harness-agent
make install          # install dev dependencies
make all              # lint + typecheck + test (CI ship bar)

Command	Description
make lint	Ruff check + format check
make format	Auto-fix and format
make typecheck	mypy strict
make test	pytest with coverage
make build	Build wheel + sdist

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and run make all before opening a PR.

Security issues: see SECURITY.md.

---

Release

Tag v<version> (e.g., v0.2.0) to trigger a PyPI release via GitHub Actions with trusted publishing.

---

Related Projects

Project	Description
Octop	Self-hosted multi-user AI control plane
harness-memory	Pluggable memory system with hierarchical recall and FTS
harness-browser	AI-friendly browser automation via CDP
harness-gateway	Multi-platform IM channel bridge for AI agents

---

License

MIT