@stackone/agent-harness

Composable agent runtime for building and testing StackOne integrations.

Overview

Agent Harness is a TypeScript library that orchestrates LLM-based agents to build, test, and manage API connectors. It's designed to be imported and used by:

• StackOne CLI - Command-line interface for integration engineers
• StackOne API - HTTP API for programmatic access
• MCP Servers - Agent-to-agent interaction via Model Context Protocol

Architecture

┌─────────────────────────────────────────────┐
│         @stackone/agent-harness             │
│                                             │
│  ┌─────────────┐      ┌─────────────────┐  │
│  │   Runtime   │──────│  Tool Adapters  │  │
│  └─────────────┘      └─────────────────┘  │
│         │                      │            │
│         │                      ├─ Filesystem│
│         │                      ├─ CLI       │
│         │                      └─ MCP       │
│         │                                   │
│  ┌─────────────┐      ┌─────────────────┐  │
│  │ Sub-Agents  │      │     Memory      │  │
│  └─────────────┘      └─────────────────┘  │
└─────────────────────────────────────────────┘

Features

• LLM Orchestration - Anthropic Claude integration with tool calling
• Tool Adapters - Pluggable system for filesystem, CLI, MCP tools
• Sub-Agents - Role-based agents (builder, tester, reviewer)
• Structured Outputs - Type-safe reports and artifacts
• Run Management - Lifecycle tracking and state persistence

Installation

npm install @stackone/agent-harness

Authentication

Important: Agent Harness requires a StackOne Agent token. You cannot use personal Anthropic or LangSmith API keys directly.

# Authenticate with StackOne (required)
stackone agent setup

# This will:
# 1. Authenticate you with StackOne via OAuth
# 2. Generate a STACKONE_AGENT_TOKEN
# 3. Configure access to Claude API and telemetry through StackOne's proxy

All API requests and telemetry are routed through StackOne's proxy. This ensures:

• Centralized access control and usage tracking
• Automatic telemetry integration
• No direct API key management required

Quick Start

import { AgentRuntime } from '@stackone/agent-harness';
import { builtinSkills } from '@stackone/agent-harness';

// Token obtained from: stackone agent setup
const runtime = new AgentRuntime({
  apiKey: process.env.STACKONE_AGENT_TOKEN, // Required - no fallback to personal keys
  tools: [
    builtinSkills.readFileSkill,
    builtinSkills.writeFileSkill,
  ]
});

const run = await runtime.execute({
  mode: 'build',
  goal: 'Create a Datadog connector skeleton'
});

console.log(run.status); // 'completed'
console.log(run.artifacts); // [{ type: 'file', path: '...' }]

If you haven't run stackone agent setup, you'll see:

Error: StackOne Agent token is required.

Please run: stackone agent setup

This will authenticate you with StackOne and configure your agent access.
For more information, visit: https://docs.stackone.com/agent-setup

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test
npm test

# Lint
npm run lint

License

ISC