API ReferenceCore Package

Core Package

The @dexwox-labs/a2a-core package provides the foundational types, utilities, and protocol definitions for the A2A Node SDK.

Overview

The core package includes essential components for A2A protocol implementation:

  • Protocol Types - Core interfaces and types for A2A communication
  • Error Classes - Specialized error types for A2A operations
  • Validation - Zod schemas for runtime validation
  • Utilities - Helper functions for working with A2A data

Installation

npm install @dexwox-labs/a2a-core
# or
npm install @dexwox-labs/a2a-node  # includes all packages

Core Types

AgentCard

AgentCard - Describes an agent’s metadata and capabilities.

interface AgentCard {
  id: string;                    // Unique agent identifier
  name: string;                  // Human-readable name
  description?: string;          // Agent description
  version: string;               // Agent version
  capabilities: string[];        // List of capabilities
  endpoint: string;              // Agent endpoint URL
  metadata?: Record<string, any>; // Additional metadata
}

Task

Task - Represents a unit of work for agents to process.

interface Task {
  id: string;                    // Unique task identifier
  name: string;                  // Task name/type
  description?: string;          // Task description
  status: TaskStatus;            // Current status
  input?: any;                   // Task input data
  result?: any;                  // Task result (when completed)
  error?: string;                // Error message (when failed)
  artifacts?: Artifact[];        // Generated artifacts
  createdAt: string;             // ISO 8601 timestamp
  updatedAt: string;             // ISO 8601 timestamp
  transitions?: TaskTransition[]; // Status history
}
 
type TaskStatus = 'submitted' | 'working' | 'completed' | 'failed' | 'canceled';

Message

Message - Represents communication between agents.

interface Message {
  id: string;                    // Unique message identifier
  conversationId?: string;       // Conversation grouping
  senderId: string;              // Sender agent ID
  recipientId: string;           // Recipient agent ID
  parts: MessagePart[];          // Message content parts
  timestamp: string;             // ISO 8601 timestamp
  metadata?: Record<string, any>; // Additional metadata
}

TaskTransition

TaskTransition - Records task state changes.

interface TaskTransition {
  status: TaskStatus;            // New status
  description?: string;          // Transition description
  timestamp: string;             // ISO 8601 timestamp
  metadata?: Record<string, any>; // Additional metadata
}

Error Classes

The core package provides specialized error classes for different A2A operations:

A2AError

A2AError - Base error class for all A2A-related errors.

class A2AError extends Error {
  constructor(
    public code: string,
    message: string,
    public details?: any
  ) {
    super(message);
    this.name = 'A2AError';
  }
}

Task Errors

Usage Example

import { 
  A2AError, 
  TaskNotFoundError, 
  TaskFailedError 
} from '@dexwox-labs/a2a-core';
 
try {
  await processTask(taskId);
} catch (error) {
  if (error instanceof TaskNotFoundError) {
    console.log('Task not found:', error.taskId);
  } else if (error instanceof TaskFailedError) {
    console.log('Task failed:', error.message);
  } else if (error instanceof A2AError) {
    console.log('A2A Error:', error.code, error.message);
  } else {
    console.log('Unexpected error:', error);
  }
}

Error Codes

Task Error Codes

TaskErrorCode - Enumeration of task-related error codes.

enum TaskErrorCode {
  TASK_NOT_FOUND = 'TASK_NOT_FOUND',
  TASK_ALREADY_COMPLETED = 'TASK_ALREADY_COMPLETED',
  TASK_ALREADY_CANCELED = 'TASK_ALREADY_CANCELED',
  INVALID_TASK_STATE = 'INVALID_TASK_STATE',
  TASK_TIMEOUT = 'TASK_TIMEOUT',
  TASK_EXECUTION_FAILED = 'TASK_EXECUTION_FAILED'
}

Message Error Codes

MessageErrorCode - Enumeration of message-related error codes.

enum MessageErrorCode {
  AGENT_NOT_FOUND = 'AGENT_NOT_FOUND',
  INVALID_MESSAGE_FORMAT = 'INVALID_MESSAGE_FORMAT',
  MESSAGE_TOO_LARGE = 'MESSAGE_TOO_LARGE',
  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED'
}

Artifact Error Codes

ArtifactErrorCode - Enumeration of artifact-related error codes.

enum ArtifactErrorCode {
  ARTIFACT_NOT_FOUND = 'ARTIFACT_NOT_FOUND',
  ARTIFACT_TOO_LARGE = 'ARTIFACT_TOO_LARGE',
  INVALID_ARTIFACT_TYPE = 'INVALID_ARTIFACT_TYPE',
  ARTIFACT_PROCESSING_FAILED = 'ARTIFACT_PROCESSING_FAILED'
}

Validation

The core package uses Zod for runtime validation of A2A protocol data.

Schema Validation

import { z } from 'zod';
 
// Agent Card validation
const AgentCardSchema = z.object({
  id: z.string().min(1),
  name: z.string().min(1),
  description: z.string().optional(),
  version: z.string().min(1),
  capabilities: z.array(z.string()),
  endpoint: z.string().url(),
  metadata: z.record(z.any()).optional()
});
 
// Task validation
const TaskSchema = z.object({
  id: z.string().min(1),
  name: z.string().min(1),
  description: z.string().optional(),
  status: z.enum(['submitted', 'working', 'completed', 'failed', 'canceled']),
  input: z.any().optional(),
  result: z.any().optional(),
  error: z.string().optional(),
  artifacts: z.array(ArtifactSchema).optional(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
  transitions: z.array(TaskTransitionSchema).optional()
});
 
// Message validation
const MessageSchema = z.object({
  id: z.string().min(1),
  conversationId: z.string().optional(),
  senderId: z.string().min(1),
  recipientId: z.string().min(1),
  parts: z.array(MessagePartSchema),
  timestamp: z.string().datetime(),
  metadata: z.record(z.any()).optional()
});

Validation Usage

import { AgentCardSchema, TaskSchema, MessageSchema } from '@dexwox-labs/a2a-core';
 
// Validate agent card
try {
  const validAgentCard = AgentCardSchema.parse(agentCardData);
  console.log('Valid agent card:', validAgentCard);
} catch (error) {
  console.error('Invalid agent card:', error.errors);
}
 
// Validate task
try {
  const validTask = TaskSchema.parse(taskData);
  console.log('Valid task:', validTask);
} catch (error) {
  console.error('Invalid task:', error.errors);
}
 
// Validate message
try {
  const validMessage = MessageSchema.parse(messageData);
  console.log('Valid message:', validMessage);
} catch (error) {
  console.error('Invalid message:', error.errors);
}

Utilities

Message Utilities

import { createTextMessage, createFileMessage, createDataMessage } from '@dexwox-labs/a2a-core';
 
// Create different types of message parts
const textPart = createTextMessage('Hello, world!');
const filePart = createFileMessage(fileBuffer, 'image/png', 'screenshot.png');
const dataPart = createDataMessage({ temperature: 72, humidity: 45 });
 
// Combine into a message
const messageParts = [textPart, filePart, dataPart];

Task Utilities

import { createTask, updateTaskStatus, isTaskComplete } from '@dexwox-labs/a2a-core';
 
// Create a new task
const task = createTask({
  name: 'process-data',
  description: 'Process the uploaded data file',
  input: { fileId: 'file-123' }
});
 
// Update task status
const updatedTask = updateTaskStatus(task, 'working');
 
// Check if task is complete
if (isTaskComplete(task)) {
  console.log('Task completed with result:', task.result);
}

Validation Utilities

import { validateAgentCard, validateTask, validateMessage } from '@dexwox-labs/a2a-core';
 
// Validate data with utility functions
const isValidAgent = validateAgentCard(agentData);
const isValidTask = validateTask(taskData);
const isValidMessage = validateMessage(messageData);
 
// These functions return boolean values for quick validation
if (!isValidAgent) {
  throw new Error('Invalid agent card format');
}

Type Guards

import { 
  isAgentCard, 
  isTask, 
  isMessage, 
  isTaskComplete,
  isTaskFailed 
} from '@dexwox-labs/a2a-core';
 
// Type guards for runtime type checking
function processData(data: unknown) {
  if (isAgentCard(data)) {
    // TypeScript knows data is AgentCard
    console.log('Agent:', data.name);
  } else if (isTask(data)) {
    // TypeScript knows data is Task
    console.log('Task:', data.name, data.status);
    
    if (isTaskComplete(data)) {
      console.log('Result:', data.result);
    } else if (isTaskFailed(data)) {
      console.log('Error:', data.error);
    }
  } else if (isMessage(data)) {
    // TypeScript knows data is Message
    console.log('Message from:', data.senderId);
  }
}

Constants

import { 
  DEFAULT_TASK_TIMEOUT,
  MAX_MESSAGE_SIZE,
  SUPPORTED_ARTIFACT_TYPES,
  PROTOCOL_VERSION 
} from '@dexwox-labs/a2a-core';
 
// Use predefined constants
const taskConfig = {
  timeout: DEFAULT_TASK_TIMEOUT, // 300000 (5 minutes)
  maxRetries: 3
};
 
const messageConfig = {
  maxSize: MAX_MESSAGE_SIZE, // 10MB
  supportedTypes: SUPPORTED_ARTIFACT_TYPES
};
 
console.log('A2A Protocol Version:', PROTOCOL_VERSION); // "1.0"

Advanced Usage

Custom Error Classes

import { A2AError } from '@dexwox-labs/a2a-core';
 
class CustomAgentError extends A2AError {
  constructor(message: string, public agentId: string) {
    super('CUSTOM_AGENT_ERROR', message, { agentId });
    this.name = 'CustomAgentError';
  }
}
 
// Usage
throw new CustomAgentError('Agent configuration invalid', 'agent-123');

Schema Extensions

import { z } from 'zod';
import { AgentCardSchema } from '@dexwox-labs/a2a-core';
 
// Extend base schemas for custom requirements
const ExtendedAgentCardSchema = AgentCardSchema.extend({
  customField: z.string().optional(),
  priority: z.number().min(1).max(10).default(5)
});
 
// Use extended schema
const customAgentCard = ExtendedAgentCardSchema.parse(agentData);

Next Steps

OverviewClient Package