CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-agent-protocol

JavaScript/TypeScript SDK implementing the Agent Communication Protocol for wrapping agents in webservers with task handlers.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Agent Protocol

Agent Protocol is a JavaScript/TypeScript SDK that implements the Agent Communication Protocol, enabling developers to easily wrap their agents in a webserver compatible with the protocol by defining only an agent task handler. It provides a standardized interface for communicating with different AI agents and solves the challenge of varying interfaces across the agent ecosystem.

Package Information

  • Package Name: agent-protocol
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install agent-protocol

Core Imports

import Agent, {
  type TaskHandler,
  type StepHandler,
  type TaskInput,
  type StepInput,
  type StepResult,
  StepResult as StepResultClass, // Class with default values
  type Task,
  type Step,
  type Artifact,
  type StepOutput,
  type TaskRequestBody,
  type StepRequestBody,
  createAgentTask,
  listAgentTasks,
  getAgentTask,
  listAgentTaskSteps,
  executeAgentTaskStep,
  getAgentTaskStep,
  v4
} from "agent-protocol";

// Advanced/internal functions (not commonly needed)
import {
  getArtifacts,
  createArtifact,
  getTaskArtifact,
  getArtifactPath,
  createApi,
  type ApiConfig,
  type RouteContext,
  type RouteRegisterFn
} from "agent-protocol";

// Note: StepStatus and AdditionalInput are used internally but not exported
// Express and Router types are available when using build() method or createApi
import type { Express, Router } from "express";

For CommonJS:

const Agent = require("agent-protocol");
const { createAgentTask, listAgentTasks } = require("agent-protocol");

Basic Usage

import Agent, {
  type StepHandler,
  type StepInput,
  type StepResult,
  type TaskInput,
} from "agent-protocol";

// Define a task handler that returns a step handler
async function taskHandler(taskInput: TaskInput | null): Promise<StepHandler> {
  console.log(`Task: ${taskInput}`);

  // Return a step handler function
  async function stepHandler(stepInput: StepInput | null): Promise<StepResult> {
    console.log(`Step: ${stepInput}`);
    
    return {
      output: stepInput,
    };
  }

  return stepHandler;
}

// Create and start the agent server
Agent.handleTask(taskHandler, { port: 8000 }).start();

Architecture

Agent Protocol is built around several key components:

  • Agent Class: Main orchestrator that creates HTTP servers and manages task execution
  • Task Management: Functions for creating, listing, and retrieving tasks and their metadata
  • Step Execution: Handles individual step processing within tasks through user-defined handlers
  • Artifact System: Manages file uploads/downloads associated with tasks and steps
  • Protocol Compliance: Built-in OpenAPI validation ensuring adherence to the Agent Communication Protocol
  • Express Integration: Uses Express.js for HTTP server functionality with middleware support

Capabilities

Agent Management

Core functionality for creating and managing agent servers that implement the Agent Communication Protocol.

class Agent {
  constructor(taskHandler: TaskHandler, config: AgentConfig);
  
  static handleTask(
    taskHandler: TaskHandler, 
    config: Partial<AgentConfig>
  ): Agent;
  
  build(port?: number): Express;
  start(port?: number): void;
}

interface AgentConfig {
  port: number;
  workspace: string;
}

const defaultAgentConfig: AgentConfig;

Task Operations

Functions for managing tasks in the agent system, including creation, retrieval, and listing.

function createAgentTask(body: TaskRequestBody | null): Promise<Task>;
function listAgentTasks(): Promise<Task[]>;
function getAgentTask(taskId: string): Promise<Task>;

// Note: listAgentTasks() when called via HTTP API returns TaskListResponse with pagination
interface TaskListResponse {
  tasks: Task[];
  pagination: Pagination;
}

Step Operations

Functions for managing individual steps within tasks, including execution and retrieval.

function listAgentTaskSteps(taskId: string): Promise<string[]>;
function executeAgentTaskStep(
  taskId: string, 
  body: StepRequestBody | null
): Promise<Step>;
function getAgentTaskStep(taskId: string, stepId: string): Promise<Step>;

// Note: listAgentTaskSteps() when called via HTTP API returns TaskStepsListResponse with pagination
interface TaskStepsListResponse {
  steps: Step[];
  pagination: Pagination;
}

Handler Types

Type definitions for user-defined functions that handle task and step processing.

type TaskHandler = (
  input: TaskInput | null
) => Promise<StepHandler>;

type StepHandler = (input: StepInput | null) => Promise<StepResult>;

// StepResult interface (return type for StepHandler)
interface StepResult {
  name?: string;
  output?: StepOutput;
  artifacts?: Artifact[];
  is_last?: boolean;
}

// StepResult class (exported as "StepResult", provides default values for convenience)
// This class implements the StepResult interface with default values
class StepResultWithDefaults implements StepResult {
  output?: StepOutput = null;
  artifacts?: Artifact[] = [];
  is_last?: boolean = false;
}

Request/Response Types

Core data structures used for task and step operations.

interface Task {
  input?: TaskInput;
  additional_input?: AdditionalInput;
  task_id: string;
  artifacts?: Artifact[];
}

interface TaskRequestBody {
  input?: TaskInput;
  additional_input?: AdditionalInput;
}

interface Step {
  name?: string;
  output?: StepOutput;
  artifacts?: Artifact[];
  is_last?: boolean;
  input?: StepInput;
  task_id: string;
  step_id: string;
  status: StepStatus;
}

interface StepRequestBody {
  input?: StepInput;
}

Artifact Management

Functions and types for handling file artifacts associated with tasks and steps.

function getArtifacts(taskId: string): Promise<Artifact[] | undefined>;
function createArtifact(
  workspace: string, 
  task: Task, 
  file: any, 
  relativePath?: string
): Promise<Artifact>;
function getTaskArtifact(taskId: string, artifactId: string): Promise<Artifact>;
function getArtifactPath(
  taskId: string, 
  workspace: string, 
  artifact: Artifact
): string;

interface Artifact {
  artifact_id: string;
  agent_created: boolean;
  file_name: string;
  relative_path: string | null;
  created_at: string; // Timestamp as string (Date.now().toString())
}

// Note: getArtifacts() when called via HTTP API returns TaskArtifactsListResponse with pagination
interface TaskArtifactsListResponse {
  artifacts: Artifact[];
  pagination: Pagination;
}

interface Pagination {
  total_items: number;
  total_pages: number;
  current_page: number;
  page_size: number;
}

Type Definitions

Core type aliases used throughout the API (exported).

type TaskInput = any;
type StepInput = any;
type StepOutput = any;

Internal types (not exported but used in interfaces):

type AdditionalInput = any;

enum StepStatus {
  CREATED = 'created',
  RUNNING = 'running',
  COMPLETED = 'completed'
}

API Configuration

Low-level API configuration types and functions for advanced usage.

function createApi(config: ApiConfig, start?: boolean): Express;

interface ApiConfig {
  context: RouteContext;
  port: number;
  callback?: () => void;
  routes: RouteRegisterFn[];
}

interface RouteContext {
  workspace: string;
}

type RouteRegisterFn = (app: Router, context: RouteContext) => void;
// Router is from Express.js: import { Router } from "express"

Utilities

Additional utilities re-exported for convenience.

// UUID v4 generator function from the uuid package
const v4: () => string;

Configuration

The Agent class accepts configuration options for customizing server behavior:

// Default configuration
const defaultConfig = {
  port: 8000,
  workspace: './workspace'
};

// Custom configuration
Agent.handleTask(taskHandler, {
  port: 3000,
  workspace: '/path/to/workspace'
}).start();

Error Handling

The SDK handles common error scenarios:

  • Task Not Found: Thrown when referencing non-existent task IDs
  • Step Not Found: Thrown when referencing non-existent step IDs
  • Handler Not Defined: Thrown when attempting operations without a task handler
  • Validation Errors: OpenAPI validation failures for malformed requests

Error responses follow standard HTTP status codes with JSON error objects containing descriptive messages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/agent-protocol@1.0.x
Publish Source
CLI
Badge
tessl/npm-agent-protocol badge