Metadata-Version: 2.4
Name: orcakit-harness-agent
Version: 0.7.0
Summary: Production-grade Harness Agent built on top of LangChain Deep Agents.
Project-URL: Homepage, https://github.com/orcakit/harness-agent
Project-URL: Repository, https://github.com/orcakit/harness-agent
Project-URL: Issues, https://github.com/orcakit/harness-agent/issues
Project-URL: Changelog, https://github.com/orcakit/harness-agent/blob/main/CHANGELOG.md
Author: orcakit
License-Expression: MIT
License-File: LICENSE
Keywords: agent,deep-agents,harness,langchain,langgraph,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: deepagents<1.0,>=0.6
Requires-Dist: harness-browser>=0.1.1
Requires-Dist: harness-memory>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-anthropic<2.0,>=1.4
Requires-Dist: langchain-core<2.0,>=1.4
Requires-Dist: langchain-mcp-adapters>=0.3.0
Requires-Dist: langchain-openai>=0.3
Requires-Dist: langchain<2.0,>=1.3
Requires-Dist: langgraph-checkpoint-sqlite>=2.0
Requires-Dist: langgraph<2.0,>=1.0
Requires-Dist: markdownify>=0.13
Requires-Dist: mcp>=1.27.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: acp
Requires-Dist: agent-client-protocol>=0.9.0; extra == 'acp'
Requires-Dist: psutil>=5.9; extra == 'acp'
Provides-Extra: bedrock
Requires-Dist: langchain-aws>=0.2; extra == 'bedrock'
Provides-Extra: brave
Requires-Dist: langchain-community>=0.3; extra == 'brave'
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == 'cli'
Requires-Dist: prompt-toolkit>=3.0; extra == 'cli'
Requires-Dist: python-dotenv>=1.0; extra == 'cli'
Requires-Dist: rich>=13.0; extra == 'cli'
Provides-Extra: cos
Requires-Dist: cos-python-sdk-v5>=1.9; extra == 'cos'
Provides-Extra: desktop
Requires-Dist: mss>=9.0; extra == 'desktop'
Provides-Extra: google-search
Requires-Dist: google-api-python-client>=2.0; extra == 'google-search'
Requires-Dist: langchain-community>=0.3; extra == 'google-search'
Provides-Extra: observability
Requires-Dist: langfuse>=4.9.0; extra == 'observability'
Provides-Extra: remote-backends
Requires-Dist: deepagents-backends>=0.2; (python_version >= '3.12') and extra == 'remote-backends'
Provides-Extra: tavily
Requires-Dist: langchain-tavily>=0.1; extra == 'tavily'
Provides-Extra: web-search-all
Requires-Dist: google-api-python-client>=2.0; extra == 'web-search-all'
Requires-Dist: langchain-community>=0.3; extra == 'web-search-all'
Requires-Dist: langchain-tavily>=0.1; extra == 'web-search-all'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/images/banner.jpeg" alt="Harness Agent Banner" width="100%" />
</p>

<h1 align="center">Harness Agent</h1>

<p align="center">
  <strong>Production-grade AI agent platform built on LangChain Deep Agents.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/orcakit-harness-agent/"><img src="https://img.shields.io/pypi/v/orcakit-harness-agent" alt="PyPI" /></a>
  <a href="https://github.com/orcakit/harness-agent/actions/workflows/ci.yml"><img src="https://github.com/orcakit/harness-agent/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
</p>

<p align="center">
  <b>English</b> · <a href="README_CN.md">中文</a>
</p>

---

## 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](https://github.com/orcakit/harness-memory), browser automation via [harness-browser](https://github.com/orcakit/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](https://github.com/langchain-ai/langgraph) + [Deep Agents](https://pypi.org/project/deepagents/) | Stateful graph execution with hierarchical agent routing |
| Model Providers | LangChain model integrations | Unified interface for OpenAI, Anthropic, Bedrock, and custom endpoints |
| Memory | [harness-memory](https://github.com/orcakit/harness-memory) | Hierarchical recall with FTS search and pluggable backends |
| Browser | [harness-browser](https://github.com/orcakit/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

```bash
# 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

```python
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

```python
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](https://docs.astral.sh/uv/)

```bash
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](CONTRIBUTING.md) and run `make all` before opening a PR.

Security issues: see [SECURITY.md](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 |
|---------|-------------|
| [orca (Octop)](https://github.com/orcakit/orca) | Self-hosted multi-user AI control plane |
| [harness-memory](https://github.com/orcakit/harness-memory) | Pluggable memory system with hierarchical recall and FTS |
| [harness-browser](https://github.com/orcakit/harness-browser) | AI-friendly browser automation via CDP |
| [harness-gateway](https://github.com/orcakit/harness-gateway) | Multi-platform IM channel bridge for AI agents |

---

## License

[MIT](LICENSE)
