Octop Harness

A production-grade agent runtime engineered from the Harness Engineering philosophy.

What is Octop Harness? · Why Octop Harness? · How to Use · Documentation

English · 中文

octop-harness 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 deepagents — we take the elegant create_deep_agent primitive from deepagents 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 deepagents. octop-harness stands on the shoulders of deepagents (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. deepagents gives us the agentic foundation; Harness gives it a home for production.

octop-harness is a library (not an app) that turns deepagents 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 deepagents in a few lines of code, while keeping model choice, memory, storage, and safety swappable without rewriting your agent.

• 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 octop-memory saver) for resumable chats.

• 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.

• Each turn is captured as L0 raw events, then distilled asynchronously into L2 atoms (AtomCards) and L3 entity pages.
• Powered by the octop-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.

Memory extraction can be configured independently of main chat: memory_extract_max_tokens sets the candidate/episode output budget (default 2048), while memory_aux_light_timeout_s / memory_aux_heavy_timeout_s set per-request timeouts (30–3600 seconds). memory_aux_max_retries defaults to 2 extra attempts per model and accepts 0–10; memory_aux_retry_backoff_s defaults to 1 second and doubles up to 60 seconds. Only transport/transient HTTP failures are retried. SDK retries are disabled on separate cached model instances, so main-chat retry settings are unaffected. ChatModelFactory.get_chat_model(ref, max_retries=0) exposes that isolated construction path.

memory_aux_thinking="auto" or "off" disables thinking for known Qwen3/QwQ chat-template models; unsupported models keep their defaults. "on" keeps the model default. memory_aux_extra_body can supply vendor-specific settings such as reasoning_effort; these apply only to the first selected OpenAI-compatible model, never to fallback models. Fallback options are rebuilt for each target, and output budgets respect the target model's configured output limit. Retries, model fallback, and multiple extraction stages can extend total extraction time beyond a single request timeout.

Hosts can use MemoryMiddleware.pause_background(timeout=120) as a context manager after pausing graph admission. It drains capture, extraction and maintenance workers for that middleware only, skips new background submissions while paused, and resumes admission on exit or timeout. Keep it held while closing and recreating the memory runtime; other experts remain independent.

• Built-in tools: browser (octop-browser), web search, files, ask_user_question for respond-only human decisions, optional provider-neutral image/video generation, sub-agents, and MCP tools. Set ask_user_enabled=False for unattended agents.
• Skills come from the deepagents 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 octop_harness 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.

For separate image and video routes, configure named providers. Built-in adapters cover Volcengine Ark (Seedream/Seedance), Alibaba Cloud Model Studio (Wan), and MiniMax (image-01/H3):

from octop_harness import HarnessAgentConfig, MediaGenerationConfig, MediaProviderConfig

config = HarnessAgentConfig(
    # ...providers/default_model...
    media_generation=MediaGenerationConfig(
        providers=[
            MediaProviderConfig(
                id="ark-images",
                provider="volcengine",
                api_key_env="ARK_API_KEY",
                video_enabled=False,
            ),
            MediaProviderConfig(
                id="minimax-videos",
                provider="minimax",
                api_key_env="MINIMAX_API_KEY",
                image_enabled=False,
            ),
        ],
        default_image_provider="ark-images",
        default_video_provider="minimax-videos",
    ),
)

Advanced hosts can inject a MediaManager into build_media_generation_tools and register a constrained custom adapter without adding arbitrary protocol or authentication fields to declarative configuration.

• 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.

• SecurityPolicy with tool guardrails, filesystem permissions (FilesystemPermission), and PII redaction middleware.
• PII detection covers provider API keys, mainland China mobile numbers (common 13-19 prefixes, optional +86 / 0086), and 18-character resident IDs with a known province code, 1900-2099 date, and checksum. Existing pii_strategy and pii_surfaces apply; legacy 15-digit IDs and other countries' numbers are out of scope.

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

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

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

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

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

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

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

octop-harness chat

from octop_harness 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="")

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 octop_harness 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.

For OpenAI-compatible providers, each model can set api_mode to "chat_completions" (default) or "responses". The choice is explicit for official and compatible endpoints alike. Native OpenAI tool search requires Responses. Models using Responses may also opt in to api_fallback="chat_completions". The fallback is disabled by default and is used only for clear unsupported-endpoint/model errors, before any streamed output. It does not apply to native tool search or other Responses-only request features, and never masks authentication, rate-limit, timeout, or server errors.

• What is Octop Harness?
• Why Octop Harness?
• How to Use
• Reference
  • CLI reference
  • Project layout
  • Development
• Project Info
  • Contributing
  • Related projects
  • License

src/octop_harness/
  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 (octop-memory wrapper)
  protocols/        langgraph / openai / mcp streaming
  acp/             ACP stdio server
  teams/           peer inbox
  cli/             terminal CLI

Prerequisites: Python 3.12+, uv

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

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).

This project is licensed under the MIT License.

Thanks to all contributors: