@runtypelabs/a2a-aisdk-example 0.0.1 → 0.2.3

package/dist/index.d.ts

@@ -0,0 +1,333 @@
+import { Application } from 'express';
+
+/**
+ * A2A Protocol Types
+ *
+ * Based on A2A Protocol v0.3
+ * https://a2aproject.github.io/A2A/specification/
+ */
+interface AgentCard {
+    name: string;
+    description: string;
+    url: string;
+    version: string;
+    protocolVersion: string;
+    defaultInputModes: Array<'text' | 'file' | 'data'>;
+    defaultOutputModes: Array<'text' | 'file' | 'data'>;
+    iconUrl?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        statefulness: 'none' | 'session' | 'task';
+    };
+    skills: Skill[];
+    authentication?: {
+        type: 'none' | 'bearer' | 'api_key';
+        bearerAuth?: {
+            scopes: string[];
+        };
+        apiKeyAuth?: {
+            headerName: string;
+        };
+    };
+}
+interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    inputModes: Array<'text' | 'file' | 'data'>;
+    outputModes: Array<'text' | 'file' | 'data'>;
+    tags: string[];
+    inputSchema?: Record<string, unknown>;
+}
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id?: string | number;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+declare const JSON_RPC_ERRORS: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly TASK_NOT_FOUND: -32001;
+    readonly SKILL_NOT_FOUND: -32002;
+    readonly UNAUTHORIZED: -32003;
+    readonly RATE_LIMITED: -32004;
+    readonly TASK_CANCELED: -32005;
+};
+interface MessagePart {
+    type: 'text' | 'file' | 'data';
+    text?: string;
+    data?: unknown;
+    mimeType?: string;
+    uri?: string;
+}
+interface A2AMessage {
+    role: 'user' | 'agent';
+    parts: MessagePart[];
+}
+type TaskStatus = 'submitted' | 'working' | 'completed' | 'failed' | 'canceled';
+interface Task {
+    id: string;
+    contextId?: string;
+    status: TaskStatus;
+    artifacts?: Artifact[];
+    error?: {
+        message: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface Artifact {
+    name: string;
+    parts: MessagePart[];
+    index?: number;
+    append?: boolean;
+    lastChunk?: boolean;
+}
+interface TaskHistoryEntry {
+    status: TaskStatus;
+    message: string;
+    timestamp: string;
+}
+interface TasksSendParams {
+    skill: string;
+    message: A2AMessage;
+    contextId?: string;
+    pushNotification?: {
+        url: string;
+        authentication?: {
+            type: 'bearer' | 'api_key';
+            token?: string;
+            headerName?: string;
+        };
+    };
+    metadata?: Record<string, unknown>;
+}
+interface TasksGetParams {
+    taskId: string;
+    includeHistory?: boolean;
+}
+interface TasksCancelParams {
+    taskId: string;
+    reason?: string;
+}
+interface TaskStatusEvent {
+    taskId: string;
+    contextId?: string;
+    status: TaskStatus;
+    message?: string;
+    final?: boolean;
+}
+interface TaskArtifactEvent {
+    taskId: string;
+    artifact: Artifact;
+}
+interface TaskErrorEvent {
+    taskId: string;
+    error: {
+        code: number;
+        message: string;
+    };
+}
+interface AgentConfig {
+    name: string;
+    description?: string;
+    version?: string;
+    port?: number;
+    host?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    skills?: SkillConfig[];
+    defaultInputModes?: Array<'text' | 'file' | 'data'>;
+    defaultOutputModes?: Array<'text' | 'file' | 'data'>;
+    llm?: LLMConfig;
+}
+interface SkillConfig {
+    id: string;
+    name: string;
+    description: string;
+    systemPrompt?: string;
+    inputSchema?: Record<string, unknown>;
+    tags?: string[];
+}
+interface LLMConfig {
+    provider: 'openai' | 'anthropic';
+    model: string;
+    /** Gateway model string (e.g. openai/gpt-5-nano) when using Vercel AI Gateway */
+    gatewayModel?: string;
+    apiKey?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+}
+interface ExecutorContext {
+    taskId: string;
+    contextId?: string;
+    skill: SkillConfig;
+    message: A2AMessage;
+    metadata?: Record<string, unknown>;
+}
+interface ExecutorResult {
+    text: string;
+    artifacts?: Artifact[];
+}
+interface StreamCallbacks {
+    onChunk: (text: string) => Promise<void>;
+    onComplete: () => Promise<void>;
+    onError: (error: Error) => Promise<void>;
+}
+
+/**
+ * A2A Protocol Server
+ *
+ * Express server implementing the A2A (Agent-to-Agent) protocol.
+ * Provides agent card discovery and JSON-RPC task execution endpoints.
+ */
+
+interface A2AServerOptions {
+    config: AgentConfig;
+    llmConfig?: LLMConfig;
+    echoMode?: boolean;
+}
+interface A2AServer {
+    app: Application;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+}
+declare function createA2AServer(options: A2AServerOptions): A2AServer;
+
+/**
+ * A2A Client
+ *
+ * Client for testing A2A protocol endpoints, including Runtype's A2A surfaces.
+ */
+
+interface A2AClientOptions {
+    /** Base URL of the A2A endpoint (with or without /a2a suffix) */
+    baseUrl: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+}
+declare class A2AClient {
+    private baseUrl;
+    private rpcUrl;
+    private agentCardUrl;
+    private apiKey?;
+    private headers;
+    constructor(options: A2AClientOptions);
+    /**
+     * Get the agent card for discovery
+     */
+    getAgentCard(): Promise<AgentCard>;
+    /**
+     * Send a task and wait for completion (synchronous)
+     */
+    sendTask(params: TasksSendParams): Promise<Task>;
+    /**
+     * Send a task with streaming (SSE)
+     */
+    sendTaskStreaming(params: TasksSendParams, callbacks: {
+        onStatus?: (status: string, data: TaskStatusEvent) => void;
+        onArtifact?: (artifact: Artifact) => void;
+        onError?: (error: JsonRpcError) => void;
+        onChunk?: (text: string) => void;
+    }): Promise<void>;
+    /**
+     * Get task status
+     */
+    getTask(taskId: string, includeHistory?: boolean): Promise<Task>;
+    /**
+     * Cancel a task
+     */
+    cancelTask(taskId: string, reason?: string): Promise<Task>;
+    /**
+     * Send a JSON-RPC request
+     */
+    private sendJsonRpc;
+    /**
+     * Get headers for requests
+     */
+    private getHeaders;
+}
+/**
+ * Create a client for testing a Runtype A2A surface
+ */
+declare function createRuntypeA2AClient(options: {
+    productId: string;
+    surfaceId: string;
+    apiKey: string;
+    environment?: 'production' | 'staging' | 'local';
+}): A2AClient;
+
+/**
+ * Agent Executor
+ *
+ * Executes tasks using the Vercel AI SDK for LLM integration.
+ * Supports both streaming and non-streaming responses.
+ */
+
+/**
+ * Execute a task without streaming
+ */
+declare function executeTask(context: ExecutorContext, llmConfig: LLMConfig, skillsCatalog?: SkillConfig[]): Promise<ExecutorResult>;
+/**
+ * Execute a task with streaming
+ */
+declare function executeTaskStreaming(context: ExecutorContext, llmConfig: LLMConfig, callbacks: StreamCallbacks, skillsCatalog?: SkillConfig[]): Promise<void>;
+/**
+ * Simple executor for testing (no LLM, just echoes)
+ */
+declare function executeEcho(context: ExecutorContext): Promise<ExecutorResult>;
+/**
+ * Simple streaming executor for testing
+ */
+declare function executeEchoStreaming(context: ExecutorContext, callbacks: StreamCallbacks): Promise<void>;
+
+/**
+ * Deterministic Time Executor
+ *
+ * Computes temporal data using date-fns and the system clock.
+ * No LLM generation — all results are deterministic.
+ */
+
+declare function executeTimeSkill(context: ExecutorContext): Promise<ExecutorResult>;
+
+/**
+ * Default Skills Configuration
+ *
+ * Shared skill definitions for A2A agents. Import these in your agent
+ * configuration to avoid duplication across different deployment targets.
+ */
+
+/**
+ * Default skills available to A2A agents.
+ * Includes deterministic time tools and LLM-powered skills.
+ */
+declare const DEFAULT_SKILLS: SkillConfig[];
+/**
+ * Default LLM configuration for A2A agents.
+ */
+declare const DEFAULT_LLM_CONFIG: LLMConfig;
+
+export { A2AClient, type A2AClientOptions, type A2AMessage, type A2AServer, type A2AServerOptions, type AgentCard, type AgentConfig, type Artifact, DEFAULT_LLM_CONFIG, DEFAULT_SKILLS, type ExecutorContext, type ExecutorResult, JSON_RPC_ERRORS, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LLMConfig, type MessagePart, type Skill, type SkillConfig, type StreamCallbacks, type Task, type TaskArtifactEvent, type TaskErrorEvent, type TaskHistoryEntry, type TaskStatus, type TaskStatusEvent, type TasksCancelParams, type TasksGetParams, type TasksSendParams, createA2AServer, createRuntypeA2AClient, executeEcho, executeEchoStreaming, executeTask, executeTaskStreaming, executeTimeSkill };

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import {
+  A2AClient,
+  DEFAULT_LLM_CONFIG,
+  DEFAULT_SKILLS,
+  JSON_RPC_ERRORS,
+  createA2AServer,
+  createRuntypeA2AClient,
+  executeEcho,
+  executeEchoStreaming,
+  executeTask,
+  executeTaskStreaming,
+  executeTimeSkill
+} from "./chunk-OLB7ZZNY.js";
+export {
+  A2AClient,
+  DEFAULT_LLM_CONFIG,
+  DEFAULT_SKILLS,
+  JSON_RPC_ERRORS,
+  createA2AServer,
+  createRuntypeA2AClient,
+  executeEcho,
+  executeEchoStreaming,
+  executeTask,
+  executeTaskStreaming,
+  executeTimeSkill
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/vercel/index.d.ts

@@ -0,0 +1,145 @@
+interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    inputModes: Array<'text' | 'file' | 'data'>;
+    outputModes: Array<'text' | 'file' | 'data'>;
+    tags: string[];
+    inputSchema?: Record<string, unknown>;
+}
+interface SkillConfig {
+    id: string;
+    name: string;
+    description: string;
+    systemPrompt?: string;
+    inputSchema?: Record<string, unknown>;
+    tags?: string[];
+}
+interface LLMConfig {
+    provider: 'openai' | 'anthropic';
+    model: string;
+    /** Gateway model string (e.g. openai/gpt-5-nano) when using Vercel AI Gateway */
+    gatewayModel?: string;
+    apiKey?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+}
+
+/**
+ * Default Skills Configuration
+ *
+ * Shared skill definitions for A2A agents. Import these in your agent
+ * configuration to avoid duplication across different deployment targets.
+ */
+
+/**
+ * Default skills available to A2A agents.
+ * Includes deterministic time tools and LLM-powered skills.
+ */
+declare const DEFAULT_SKILLS: SkillConfig[];
+/**
+ * Default LLM configuration for A2A agents.
+ */
+declare const DEFAULT_LLM_CONFIG: LLMConfig;
+
+/**
+ * Vercel A2A Configuration
+ *
+ * Configuration types and helpers for deploying A2A agents to Vercel.
+ */
+
+interface VercelA2AConfig {
+    /** Agent name displayed in the agent card */
+    name: string;
+    /** Agent description */
+    description?: string;
+    /** Agent version (default: "1.0.0") */
+    version?: string;
+    /** Custom skills (defaults to time/*, chat, echo, analyze) */
+    skills?: SkillConfig[];
+    /** Provider information */
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    /** URL where the agent is deployed (for agent card) */
+    agentUrl?: string;
+    /** Default input modes for agent card */
+    defaultInputModes?: Array<'text' | 'file' | 'data'>;
+    /** Default output modes for agent card */
+    defaultOutputModes?: Array<'text' | 'file' | 'data'>;
+    /** Run in echo mode (no LLM, for testing) */
+    echoMode?: boolean;
+    /** LLM configuration (required unless echoMode is true) */
+    llmConfig?: LLMConfig;
+}
+/**
+ * Resolve configuration with defaults
+ */
+declare function resolveConfig(config: VercelA2AConfig): Required<Pick<VercelA2AConfig, 'name' | 'description' | 'version' | 'skills' | 'echoMode' | 'defaultInputModes' | 'defaultOutputModes'>> & {
+    provider: {
+        organization: string;
+        url?: string;
+    };
+    llmConfig: LLMConfig;
+    agentUrl?: string;
+};
+/**
+ * Convert SkillConfig to A2A Skill format for agent card
+ */
+declare function toAgentCardSkills(skills: SkillConfig[]): Skill[];
+
+/**
+ * Vercel A2A Request Handlers
+ *
+ * Stateless request handlers for Vercel serverless/edge functions.
+ * These handlers implement the A2A protocol using Web standard Request/Response APIs.
+ */
+
+/**
+ * Create a handler for the agent card endpoint (GET /.well-known/agent.json)
+ *
+ * @example
+ * ```typescript
+ * // app/.well-known/agent.json/route.ts (Next.js App Router)
+ * import { createAgentCardHandler } from '@runtypelabs/a2a-agent-example/vercel'
+ *
+ * export const GET = createAgentCardHandler({
+ *   name: 'My Agent',
+ *   echoMode: true,
+ * })
+ * ```
+ */
+declare function createAgentCardHandler(config: VercelA2AConfig): (_request: Request) => Promise<Response>;
+/**
+ * Create a handler for the A2A JSON-RPC endpoint (POST /api/a2a)
+ *
+ * @example
+ * ```typescript
+ * // app/api/a2a/route.ts (Next.js App Router)
+ * import { createA2AHandler } from '@runtypelabs/a2a-agent-example/vercel'
+ *
+ * export const POST = createA2AHandler({
+ *   name: 'My Agent',
+ *   llmConfig: { provider: 'openai', model: 'gpt-4o-mini' },
+ * })
+ * ```
+ */
+declare function createA2AHandler(config: VercelA2AConfig): (request: Request) => Promise<Response>;
+/**
+ * Create both handlers with shared configuration
+ *
+ * @example
+ * ```typescript
+ * const { agentCardHandler, a2aHandler } = createHandlers({
+ *   name: 'My Agent',
+ *   echoMode: true,
+ * })
+ * ```
+ */
+declare function createHandlers(config: VercelA2AConfig): {
+    agentCardHandler: (_request: Request) => Promise<Response>;
+    a2aHandler: (request: Request) => Promise<Response>;
+};
+
+export { DEFAULT_LLM_CONFIG, DEFAULT_SKILLS, type VercelA2AConfig, createA2AHandler, createAgentCardHandler, createHandlers, resolveConfig, toAgentCardSkills };