colony-harnessProduction-grade AI Agent Runtime

From ReAct loops to quality gates — the infrastructure layer for safe, observable, evaluable AI agents.

Start Tutorial

API Reference

GitHub

ReAct Agentic Loop

Multi-turn reasoning-action-observation cycle with configurable stop conditions, tool concurrency, and fail strategies.

Three-Tier Memory

Working / Episodic / Semantic memory with auto context compression. SQLite and Redis backends included.

Full-Chain Observability

Four trace exporters — Console, File, OpenTelemetry (OpenInference-aligned), and Langfuse.

Safety Guardrails

Five built-in guards: prompt injection detection, PII redaction, token limits, sensitive words, and rate limiting.

Evaluation Suite

Seven built-in scorers plus Eval Gate — automatic quality enforcement before every release.

Multi-Provider Unification

OpenAI / Anthropic / Gemini / OpenAI-Compatible — swap providers with a single line.

pnpm add colony-harnessCopy

agent.ts

import { HarnessBuilder, PromptInjectionGuard } from 'colony-harness'
import { OpenAIProvider } from '@colony-harness/llm-openai'
import { ConsoleTraceExporter } from '@colony-harness/trace-console'
import { calculatorTool } from '@colony-harness/tools-builtin'
// Build a production-ready agent in 30 seconds
const harness = new HarnessBuilder()
  .llm(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }))
  .tool(calculatorTool)
  .trace(new ConsoleTraceExporter())
  .guard(new PromptInjectionGuard())
  .build()

Why colony-harness?

Models are powerful, but lack a reliable production runtime. We fill that gap.

◆

Production Safety

Five-layer guard pipeline covering injection detection, PII redaction, token limits, sensitive words, and rate control.

⚙

Zod Tool Validation

★

Full-Chain Tracing

Built-in Span / Event / Metrics tracing with four exporters covering terminal, file, OTel, and Langfuse.

♦

Three-Tier Memory

Working / Episodic / Semantic memory architecture with automatic context compression when tokens exceed limits.

●

Evaluation Gates

Seven scorers plus Eval Gate — automatic quality enforcement that blocks sub-threshold releases.

⬤

Multi-Provider

Unified interface across OpenAI, Anthropic, Gemini, and OpenAI-compatible endpoints. Swap with one line.

Architecture

Centralized runtime, pluggable ecosystem — assemble only what you need.

⬢LLM Providers4 packages

⋮ ⋮ ⋮

♦Memory2 adapters

⬡ColonyHarnessCore Runtime

✶Trace4 exporters

⋮ ⋮ ⋮

▸Tools8 built-in

★Evaluation7 scorers

⌖Control Plane4 packages

Package Ecosystem

18 packages, organized by function — install only what you need.

Core

colony-harnessCore runtime. HarnessBuilder, AgenticLoop, ToolRegistry, MemoryManager, TraceHub, Guardrails all in one.pnpm add colony-harness

LLM Providers

@colony-harness/llm-openaiOpenAI Chat Completions adapter. Supports tool calling and token usage tracking.pnpm add @colony-harness/llm-openai

@colony-harness/llm-anthropicAnthropic Messages API adapter. Auto-separates system messages, maps tool_use format.pnpm add @colony-harness/llm-anthropic

@colony-harness/llm-geminiGoogle Gemini generateContent adapter. Maps roles and functionDeclarations.pnpm add @colony-harness/llm-gemini

@colony-harness/llm-openai-compatibleUniversal adapter for any OpenAI-compatible endpoint. Works with domestic LLMs.pnpm add @colony-harness/llm-openai-compatible

Memory

@colony-harness/memory-sqliteSQLite persistence adapter. Supports similarity search, session cleanup, auto table creation.pnpm add @colony-harness/memory-sqlite

@colony-harness/memory-redisRedis adapter. Hash entries, sorted sets for time ordering, pipeline-optimized writes.pnpm add @colony-harness/memory-redis

Trace

@colony-harness/trace-consoleANSI-colored terminal exporter. Shows TraceID, task info, duration, and span details.pnpm add @colony-harness/trace-console

@colony-harness/trace-fileJSONL file exporter. Append-only writes with optional pretty-print JSON mode.pnpm add @colony-harness/trace-file

@colony-harness/trace-otelOpenTelemetry bridge. Aligns with OpenInference semantics (session.id, input/output.value).pnpm add @colony-harness/trace-otel

@colony-harness/trace-langfuseNative Langfuse exporter. Batch sends traces and observations with custom fetch and tags.pnpm add @colony-harness/trace-langfuse

Tools

@colony-harness/tools-builtinEight built-in tools: http_request, read_file, write_file, run_command, search_web, calculator, json_query, template_render.pnpm add @colony-harness/tools-builtin

Eval

@colony-harness/evalsEvaluation toolkit. runEvalSuite runner, seven scorers, evaluateGate quality gate.pnpm add @colony-harness/evals

Control Plane

@colony-harness/controlplane-contractUnified port contract. Defines TaskEnvelope, ControlPlanePort and related interfaces.

@colony-harness/controlplane-runtimeRuntime bridge. Connects ColonyHarness with ControlPlanePort, manages task lifecycle.

@colony-harness/controlplane-mock-adapterIn-memory mock adapter. Supports dispatchTask for direct injection in tests.

@colony-harness/controlplane-sdk-adapterQueen SDK adapter. Connects to Queen control plane via colony-bee-sdk.

Packages

LLM Providers

Built-in Tools

Eval Scorers

Choose Your Path

Whether you're just starting or going deep — there's a path for you.

⚡

Quick Start

Run a minimal example in 5 minutes. Verify the core loop works end-to-end.

~5 min

🔬

Deep Dive

Progressive 8-step tutorial from install to production. Covers memory, tracing, guards, and evals.

~75 min

🛠

Contributor

Join the development. Read architecture docs, ADRs, and understand package boundaries.

Open Source