AgentSpec

Overview

Connecting autonomous AI agents to enterprise APIs requires converting OpenAPI documentation into formats that large language models and cloud orchestrators accept. This transition creates three operational problems:

1. Context overhead: Standard OpenAPI 3.0, 3.1, and Swagger 2.0 documents contain documentation titles, redundant examples, XML metadata, and internal vendor extensions that increase token consumption.

2. Slow Lambda fulfillment feedback loops: AWS Bedrock Action Groups invoke Lambda functions using an envelope format (messageVersion: "1.0"). Verifying handler behavior traditionally requires deploying code to AWS and triggering calls through the AWS Management Console.

3. Runtime validation regressions: Models can pass strings where integers are expected, miss required parameters, or invent enum values. Handlers that lack strict assertion logic crash silently in production.

AgentSpec compiles OpenAPI schemas into clean Claude tools and Bedrock Action Groups, provides a local Lambda fulfillment emulator with an interactive web studio, and generates automated boundary test matrices to catch parameter validation regressions locally.

Related MCP server: HiMCP

Key capabilities

• Multi-target compilation: Generates Anthropic Claude tool definitions, OpenAI Function Calling schemas, Google Gemini Function Declarations, Model Context Protocol (MCP) tool sets, AWS Bedrock Action Group schemas, AWS CDK TypeScript constructs, Terraform HCL resource blocks, and runtime Zod validation schemas.

• Token pruning engine: Removes redundant documentation strings, examples, titles, and internal vendor extensions while preserving schema constraints, reducing prompt token footprints by 40% to 60%.

• Local Bedrock Lambda fulfillment emulator: Runs TypeScript and JavaScript Lambda handlers locally without AWS deployment. The emulator synthesizes authentic messageVersion: "1.0" event envelopes and records execution duration and console logs.

• Autonomous zero-code mock mode: Generates realistic, schema-valid synthetic mock responses directly from OpenAPI 3.0 response schemas when handler implementations are not yet written.

• Stateful multi-turn session persistence: Tracks and accumulates sessionAttributes and promptSessionAttributes across multiple tool calls within an agent conversation.

• Breaking change detector: Scans schema diffs to identify removed operations, newly introduced required parameters, altered data types, and deleted enum values before changes reach production agents.

• MCP stdio server bridge: Exposes your local Lambda fulfillment handler as a native Model Context Protocol server over standard input and output.

• Interactive browser studio: Built-in 3-column web interface running on localhost for inspecting endpoints, executing parameter payloads, and viewing real-time schema validation diagnostics.

• Automated boundary and fuzzing suite: Generates baseline happy paths, type mismatch violations, missing required parameters, and enum boundary conditions to verify that Lambda handlers return proper HTTP 4xx errors instead of unhandled exceptions.

• Project scaffolder: Bootstraps complete, production-ready TypeScript projects with pre-wired handlers, typed schemas, and configuration files via agentspec init.

Installation

Install globally via npm or run directly through npx:

npm install -g agentspec

Or run via npx:

npx agentspec --help

Quickstart

1. Inspect an OpenAPI specification

Inspect endpoint count, parameter depth, and estimated token savings:

agentspec inspect ./petstore.json

 OpenAPI Inspection: Swagger Petstore (v1.0.0)
 Sample Petstore API for AgentSpec testing

┌──────────────────────────────┬──────────────────────────────┐
│ Metric                       │ Value                        │
├──────────────────────────────┼──────────────────────────────┤
│ Total Operations             │ 4                            │
│ Total Path Routes            │ 2                            │
│ Original Token Estimate      │ 771                          │
│ Pruned Token Estimate        │ 385                          │
│ Estimated Token Savings      │ 50.1%                        │
└──────────────────────────────┴──────────────────────────────┘

2. Compile to Claude Tools and AWS Bedrock

Compile your OpenAPI specification into all supported target artifacts:

agentspec compile ./petstore.json --target all --output ./output

Generated artifacts in ./output:

• claude-tools.json: Anthropic Claude tool definitions ready for the Messages API.

• bedrock-action-group.json: AWS Bedrock Action Group configuration payload.

• bedrock-openapi.json: Compliant OpenAPI 3.0.0 schema slice for Bedrock.

• bedrock-cdk.ts: AWS CDK TypeScript construct using aws-cdk-lib/aws-bedrock.

• bedrock.tf: Terraform HCL definition using aws_bedrockagent_agent_action_group.

• types.ts and schemas.ts: TypeScript interfaces and runtime Zod schemas.

3. Run the local Bedrock Lambda emulator

Start the local fulfillment emulator pointing to your local TypeScript handler file:

agentspec simulate ./petstore.json --handler ./src/lambda.ts --port 5005

Open http://localhost:5005/_studio in your browser to access the visual testing studio. You can also trigger endpoints directly via HTTP requests:

# Direct REST invocation
curl http://localhost:5005/pets/1

# Explicit tool invocation
curl -X POST http://localhost:5005/api/invoke \
  -H "Content-Type: application/json" \
  -d '{"operationId": "getPetById", "parameters": {"petId": 1}}'

4. Run automated boundary and fuzzing tests

Verify that your Lambda handler rejects invalid requests with proper HTTP 400 responses:

agentspec test ./petstore.json --handler ./src/lambda.ts

5. Run autonomous zero-code mock server

Simulate complete agent tool calls before writing any handler code:

agentspec mock ./petstore.json --port 5005

The mock engine returns schema-valid synthetic mock data for every operation, allowing frontend and agent developers to build against the API contract immediately.

6. Detect breaking schema changes

Audit OpenAPI schema updates for breaking changes that break agent tool calling:

agentspec diff ./baseline-spec.json ./candidate-spec.json --fail-on-breaking

Detects removed operations, newly added required parameters, altered parameter data types, and deleted enum values.

7. Run as Model Context Protocol (MCP) server

Connect your Lambda fulfillment handler directly to Claude Desktop, Cursor, or any MCP client over standard I/O:

agentspec mcp ./petstore.json --handler ./src/lambda.ts

8. Scaffold a complete project

Initialize a new project with pre-wired TypeScript handler, types, and npm scripts:

agentspec init --dir ./my-agent

Lambda fulfillment contract

AWS Bedrock sends events formatted with messageVersion: "1.0". Your handler receives the event and returns a response containing a serialized JSON string in the responseBody object.

Event envelope (BedrockLambdaEvent)

export interface BedrockLambdaEvent {
  messageVersion: '1.0';
  agent: {
    name: string;
    id: string;
    alias: string;
    version: string;
  };
  actionGroup: string;
  apiPath: string;
  httpMethod: string;
  parameters: Array<{
    name: string;
    type: string;
    value: string;
  }>;
  requestBody?: {
    content: {
      'application/json': {
        properties: Array<{
          name: string;
          type: string;
          value: unknown;
        }>;
      };
    };
  };
  sessionAttributes: Record<string, string>;
  promptSessionAttributes: Record<string, string>;
  inputText?: string;
}

Response structure (BedrockLambdaResponse)

export interface BedrockLambdaResponse {
  messageVersion: '1.0';
  response: {
    actionGroup: string;
    apiPath: string;
    httpMethod: string;
    httpStatusCode: number;
    responseBody: {
      'application/json': {
        body: string; // Must be a serialized JSON string
      };
    };
  };
  sessionAttributes?: Record<string, string>;
  promptSessionAttributes?: Record<string, string>;
}

Writing a compliant TypeScript handler

import type { BedrockLambdaEvent, BedrockLambdaResponse } from 'agentspec';

export const handler = async (event: BedrockLambdaEvent): Promise<BedrockLambdaResponse> => {
  const { apiPath, httpMethod, parameters, actionGroup } = event;

  if (apiPath === '/pets' && httpMethod === 'GET') {
    return {
      messageVersion: '1.0',
      response: {
        actionGroup,
        apiPath,
        httpMethod,
        httpStatusCode: 200,
        responseBody: {
          'application/json': {
            body: JSON.stringify([
              { id: 1, name: 'Fido', status: 'available' }
            ])
          }
        }
      }
    };
  }

  return {
    messageVersion: '1.0',
    response: {
      actionGroup,
      apiPath,
      httpMethod,
      httpStatusCode: 404,
      responseBody: {
        'application/json': {
          body: JSON.stringify({ message: 'Resource not found' })
        }
      }
    }
  };
};

CLI command reference

Programmatic API

AgentSpec can be imported as a TypeScript library:

import {
  Compiler,
  BedrockEnvelope,
  ResponseValidator,
  MockServer,
  FuzzRunner
} from 'agentspec';

// 1. Compile spec programmatically
const artifacts = Compiler.compile('./petstore.json', {
  target: 'all',
  prune: true
});

// 2. Synthesize Bedrock events
const event = BedrockEnvelope.synthesize(operation, { petId: 10 });

// 3. Validate Lambda output against OpenAPI response schema
const validation = ResponseValidator.validate(event, lambdaOutput, operation);
if (!validation.isValid) {
  console.error(validation.errors);
}

Architecture

AgentSpec operates as a modular compiler pipeline:

[ OpenAPI 3.0 / 3.1 / Swagger 2.0 ]
                 │
                 ▼
┌─────────────────────────────────┐
│       OpenAPILoader             │  Parses JSON/YAML, normalizes Swagger 2.0,
│  Dereferencer & Cycle Breaker   │  resolves $ref pointers without recursion traps.
└────────────────┬────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│        SchemaPruner             │  Strips titles, examples, and internal extensions.
│   Token Optimization Engine     │  Computes exact context reduction metrics.
└────────────────┬────────────────┘
                 │
   ┌─────────────┴─────────────┐
   ▼                           ▼
┌──────────────────┐   ┌────────────────────────┐
│  ClaudeCompiler  │   │   BedrockCompiler      │
│  Anthropic Tools │   │   Action Groups & IaC  │
└──────────────────┘   └────────────────────────┘

See docs/ARCHITECTURE.md for technical details on schema normalization, circular reference resolution, and event envelope generation.

Contributing

1. Clone the repository: git clone https://github.com/alexandrmotologa/agentspec.git

2. Install dependencies: npm install

3. Run the test suite: npm test

4. Build the project: npm run build

License

MIT License. Copyright (c) 2026 Alexandr Motologa.