@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, basic usage, and examples | | Architecture | How the SDK integration and proxy work | | Adding Skills | Create custom skills for the agent | | Concepts | Deep dive into agent harness concepts | | Falcon Builder | Specialized prompt for connector building | | Benefits | Why use a centralized agent harness | | Features | Comprehensive feature reference | | Documentation | What Agent Harness does and why | | Slide Deck | Presentation outline for stakeholders |

Features

• Claude Agent SDK Integration - Native SDK with StackOne Agent tools preset
• Progressive Skill Loading - Skills loaded on-demand (~100 tokens until used)
• 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' });

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 | | build-connector | build | Generate connector YAML | | test-connector | test | Run connector tests | | validate-config | build | Validate configurations |

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