@stackone/agent-harness

Composable agent runtime for building and testing StackOne integrations, powered by the Claude Agent SDK.

Overview

Agent Harness is a TypeScript library that orchestrates LLM-based agents to build, test, and manage API connectors. It wraps the official Claude Agent SDK with StackOne integrations including billing, telemetry, and bundled skills.

Installation

npm install @stackone/agent-harness

Quick Start

import { executeAgent } from "@stackone/agent-harness";

// Execute an agent with streaming messages
for await (const message of executeAgent({
  prompt: "Research the Datadog API and list available endpoints",
  mode: "research",
})) {
  switch (message.type) {
    case "text":
      console.log("Agent:", message.content);
      break;
    case "tool_call":
      console.log(`Tool: ${message.toolName}`);
      break;
    case "done":
      console.log("Completed!", message.metadata);
      break;
  }
}

Authentication

Agent Harness requires a StackOne Agent token for API access and telemetry:

# Set your StackOne token
export STACKONE_AGENT_TOKEN="your-token"

# Or run setup via CLI
stackone agent setup

Documentation

| Guide | Description | | --------------------------------------------------- | ------------------------------------------------------ | | Getting Started | Installation, usage, orchestrator, performance options | | Architecture | SDK integration, proxy routing, security | | Adding Skills | Create custom skills for the agent | | Concepts | Deep dive into components, tools, modes | | Connector Building | Orchestrated build workflow and phase configuration | | Performance | MCP caching, context preservation, model routing | | Feature Reference | Comprehensive API and configuration reference | | Benchmark PR Check | Label-gated PR check that benchmarks skill changes against main and posts a comparison comment (cost, per-prompt scores, min/max across runs) |

Features

• Claude Agent SDK Integration - Native SDK with StackOne Agent tools preset
• Build Orchestrator - Programmatic phase sequencing with parallel execution, dependency management, and build resumption
• Progressive Skill Loading - Skills loaded on-demand (~100 tokens until used)
• MCP Response Cache - In-memory caching of MCP tool results with TTL expiration
• Context Preservation - Saves key findings to disk before context compaction to avoid re-fetching
• Configurable Model Routing - Override the model per phase or per agent session
• Telemetry - Built-in LangSmith integration via StackOne proxy
• Multiple Modes - build, test, and research modes with specialized prompts
• MCP Support - Connect external tools via Model Context Protocol
• Subagents - Define custom agents for specialized tasks

Agent Modes

// Build mode - create connector configurations
executeAgent({ prompt: "...", mode: "build" });

// Test mode - test and validate connectors
executeAgent({ prompt: "...", mode: "test" });

// Research mode - explore APIs and documentation
executeAgent({ prompt: "...", mode: "research" });

Orchestrated Builds

For connector builds, the BuildOrchestrator runs phases programmatically instead of relying on LLM-driven ordering. Research and action discovery run in parallel, with dependent phases waiting automatically.

import { BuildOrchestrator } from "@stackone/agent-harness";

const orchestrator = new BuildOrchestrator({
  provider: "bamboohr",
  category: "hris",
  baseOptions: { mode: "build", apiKey: process.env.STACKONE_AGENT_TOKEN },
  workDir: "/tmp/build",
  enableResumption: true, // Resume interrupted builds
});

for await (const event of orchestrator.run()) {
  switch (event.type) {
    case "phase_start":
      console.log(`Starting: ${event.phase}`);
      break;
    case "phase_complete":
      console.log(`Completed: ${event.phase} (${event.result.durationMs}ms)`);
      break;
    case "phase_skipped":
      console.log(`Skipped: ${event.phase} — ${event.reason}`);
      break;
    case "build_resuming":
      console.log("Resuming from prior build...");
      break;
  }
}

Default phases: research + discover-actions (parallel) → build-and-validate (sequential).

Bundled Skills

The package includes skills that Claude automatically invokes when relevant:

| Skill | Mode | Purpose | | ---------------------- | --------------- | -------------------------- | | research-provider | build, research | Research API documentation | | discover-actions | build, research | Discover API endpoints | | version-validation | build | Validate API versions | | build-connector | build | Generate connector YAML | | validate-config | build | Validate configurations | | test-connector | test | Run connector tests | | test-mcp-connector | test | Test MCP connectors | | scramble-credentials | test | Scramble test credentials | | connector-onboarding | build | Onboarding flows | | improve-descriptions | build | Enhance descriptions |

See Adding Skills for creating custom skills.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test
npm test

# Lint
npm run lint

License

UNLICENSED