or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-agent-protocol

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/agent-protocol@1.0.x

To install, run

npx @tessl/cli install tessl/npm-agent-protocol@1.0.0

index.mddocs/

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.