AI Network Agent Development Kit (AIN-ADK)

A TypeScript library for building AI agents with multi-protocol support including MCP (Model Context Protocol) and A2A (Agent-to-Agent) communication.

NOTE

IMPORTANT: This project is currently under active development. Features may be incomplete, and there might be significant changes in future updates. Please be aware that some functionalities may not work as expected or might change without prior notice.

Features

• Multi-Protocol Support: Integrate with MCP servers and A2A agents
• Modular Architecture: Flexible module system for models, memory, MCP, and A2A
• Multiple AI Models: Support for OpenAI and Gemini with easy extensibility
• Thread Management: Built-in memory module for conversation history
• Intent System: Single/multi-intent triggering with intelligent response aggregation
• Workflow Management: Built-in workflow storage and execution with display query support
• Document System: First-class, mutable documents with slot-filling, faceted labels, and AI-generated advice
• Dual Build System: Supports both ESM and CJS formats for maximum compatibility
• Structured Logging: Winston-based logging system with service-specific loggers
• TypeScript First: Built with strict TypeScript configuration

Installation

npm

npm install @ainetwork/adk

yarn

yarn add @ainetwork/adk

Requirements

• Node.js >= 20
• TypeScript >= 5.8

Getting Start

To see how to use this package in your project, check out our comprehensive examples:

👉 View Examples

Architecture

Core Components

• AINAgent (src/index.ts): Main Express.js server class that orchestrates all modules
• DI Container (src/container/): Dependency injection container for services and controllers
• ModelModule (src/modules/models/): Manages AI model integrations with streaming support
• MCPModule (src/modules/mcp/): Handles Model Context Protocol connections
• A2AModule (src/modules/a2a/): Manages agent-to-agent communication
• MemoryModule (src/modules/memory/): Provides threads, intents, and conversation history

Runtime Scope

AIN-ADK currently assumes a single agent runtime per Node.js process. Create one AINAgent instance per process; running multiple AINAgent instances concurrently in the same process is not currently supported.

Module System

The library uses a flexible module architecture:

interface AINAgentModules {
  authModule: AuthModule;      // Required - authentication handling
  modelModule: ModelModule;    // Required - AI model integrations
  memoryModule: MemoryModule;  // Required - thread/intent/workflow storage
  a2aModule?: A2AModule;       // Optional - agent-to-agent communication
  mcpModule?: MCPModule;       // Optional - MCP server connections
}

Each module can be independently configured and passed to the agent constructor.

The MemoryModule exposes an optional IDocumentMemory (getDocumentMemory()). When the underlying memory implementation provides it, document storage and the /api/document endpoints are enabled; older implementations that omit it remain fully backward compatible.

Intent System

The library supports flexible intent triggering modes:

• Multi-Intent Mode (Default): Decomposes complex queries into multiple subqueries and maps each to an intent
• Single-Intent Mode: Identifies a single intent without query decomposition (set DISABLE_MULTI_INTENTS=true)
• Intelligent Aggregation: LLM-based aggregation determines if multiple intent responses need unification
• Streaming Support: Real-time response streaming with thinking_process events for progress visibility

Workflow System

Built-in workflow management capabilities:

• Workflow Storage: Save, retrieve, list, and delete workflows via MemoryModule
• Display Query Support: Separate display query for workflow execution visualization
• Structured Execution: Define workflows with tasks and response blocks
• RESTful API: Complete workflow management through /api/workflow-template and /api/user-workflow endpoints

Document System

Documents are first-class, mutable entities that hold the canonical result of a workflow or query as markdown. They are referenced from threads (via a document message part) rather than embedded, so manual edits are always reflected wherever the document is rendered. The system is enabled whenever the memory implementation provides an IDocumentMemory (getDocumentMemory()); it is optional and fully backward compatible.

• Document Storage: CRUD via IDocumentMemory — getDocument, createDocument, updateDocument, deleteDocument, listDocuments(userId?, filter?). Documents are versioned (version increments on every update) and track editedManually.
• Slots: A document body may contain {{slot:slotId}} tokens backed by DocumentSlot entries. Each slot has a lifecycle status (empty → running → resolved/failed) and an optional binding to a workflow (with executionVariables) or a query. Slots are filled on demand and the resolved DocumentFragment (markdown + structured render blocks) is substituted at render time.
• Rendering: renderDocument(document) (src/utils/document-render.ts) produces final markdown by substituting each slot token with its resolved fragment, falling back to a status placeholder for unresolved slots. Tokens with no matching slot are left untouched.
• Faceted Labels: labels (e.g. { category: "logbook", workplaceId: "123", month: "2026-06" }) provide schema-free grouping. The nesting/hierarchy order is chosen at query or render time, so any number of grouping levels is supported without schema changes. Listing supports subset-match filtering by labels, plus workflowId/threadId/source.
• Workflow Promotion: When document memory is available, a user-workflow execution promotes its result into a first-class document and references it from the thread (instead of embedding the markdown inline).
• Rich Messages: Thread message content supports type: "rich" with MessagePart[] mixing TextPart and DocumentPart (a documentId reference resolved client-side), alongside the legacy text form.

AI Document Advice

The library can generate a short, operational AI advice from a document's rendered content:

• Streaming generation: DocumentAdviceService.generateAdviceStream runs a single-turn streaming completion over the rendered document and emits text_chunk events over SSE.
• Caching: On completion the advice is cached on document.advice ({ content, generatedAt }). The cache write persists only the advice metadata and does not bump the document version, avoiding lost updates against concurrent edits. Nothing is persisted on error or empty output.
• Prompt resolution: A per-call advicePrompt (request body) takes precedence, then the agent-memory hook getDocumentAdvicePrompt(), then a built-in Korean default prompt.

Dependency Injection

The library uses a DI Container pattern for managing services and controllers:

src/
├── config/              # Global configuration
│   ├── agent.ts         # Agent instance access
│   ├── modules.ts       # Module registry (ModelModule, MemoryModule, etc.)
│   ├── options.ts       # Options registry (onIntentFallback, etc.)
│   └── manifest.ts      # Agent manifest
├── container/           # DI Container
│   ├── index.ts         # Main container with convenience methods
│   ├── services.ts      # Service factory (QueryService, ThreadService, etc.)
│   └── controllers.ts   # Controller factory (QueryController, etc.)

Benefits:

• Centralized dependency management
• Singleton instances for memory efficiency
• Easy testing with mock injection
• Clean separation between configuration and runtime objects

Protocol Support

MCP (Model Context Protocol)

• Connects to external MCP servers via stdio
• Automatic tool discovery and execution
• Supports multiple concurrent MCP servers
• Protocol-specific tool wrapping as IMCPTool
• Per-connector requestTimeoutMs override (in MCPConfig) for long-running tools; overrides the SDK's default 60s per-request timeout and uses resetTimeoutOnProgress so tools that stream progress notifications stay alive past the base timeout

A2A (Agent-to-Agent)

• RESTful API for inter-agent communication
• Streaming response support via SSE
• Agent discovery via well-known endpoints (.well-known/agent-card.json)
• Task delegation with thread context passing
• Protocol version 0.3.0 support

Key Features

• Unified Tool Interface: Protocol-agnostic ConnectorTool and IAgentConnector interfaces
• Streaming Support: Dual implementation for streaming and non-streaming queries
• Intent System: Single/multi-intent triggering with intelligent response aggregation
• Workflow Management: Built-in workflow storage and execution with display query support
• Document System: Mutable documents with on-demand slot-filling, faceted labels, and cached AI advice
• Service Layer: Clean separation with controllers and services
• Type Safety: Comprehensive TypeScript types with strict mode
• Error Handling: Global error middleware with structured logging
• Authentication: Required auth middleware via AuthModule interface
• Graceful Shutdown: Proper cleanup of modules and connections

Development

Scripts

# Build commands
yarn build          # Build both ESM and CJS distributions

# Development
yarn dev            # Run TypeScript directly with tsx

# Code quality
yarn biome          # Check code with Biome
yarn biome:write    # Check and auto-fix with Biome

# Testing
yarn test           # Run Jest tests

# Clean
yarn clean          # Remove build artifacts

Logging System

The library uses Winston for structured logging with service-specific loggers:

import { getLogger } from '@ainetwork/adk/utils/logger';

// Get service-specific loggers
const agentLogger = getLogger('agent');
const mcpLogger = getLogger('mcp');
const a2aLogger = getLogger('a2a');
const modelLogger = getLogger('model');

// Usage examples
agentLogger.info('AINAgent started');
mcpLogger.debug('Connected to MCP server');
a2aLogger.warn('A2A connection timeout');
modelLogger.error('Model API error');

Available Loggers

• agent: Main agent operations (AINAgent)
• intent: Non-streaming query processing and intent analysis (Intent)
• intentStream: Streaming query processing (IntentStream)
• mcp: MCP server connections and tool execution (MCPModule)
• a2a: Agent-to-agent communication (A2AModule)
• model: AI model interactions (Model)
• server: A2A server operations (A2AServer)

Log Levels

• error: Error conditions
• warn: Warning conditions
• info: Informational messages (default)
• debug: Debug-level messages

API Endpoints

Standard Endpoints

• GET / - Welcome message and health check
• POST /query - Process queries (non-streaming)
  • Request: { message: string, threadId?: string, type?: string, workflowId?: string, title?: string, displayMessage?: string }
  • Response: { content: string, threadId: string }
• POST /query/stream - Process queries with streaming (SSE)
  • Request: { message: string, threadId?: string, type?: string, workflowId?: string, title?: string, displayMessage?: string }
  • Response: Server-Sent Events stream with event types:
    • text_chunk: Incremental text response
    • task_output: Workflow task output chunk
    • task_result: Workflow task completion status
    • thread_id: Thread metadata
    • document_id: Document/slot reference ({ documentId, slotId }) for slot-fill streams
    • thinking_process: Thinking/reasoning steps
    • collection_name: Collection metadata emitted by integrations
    • error: Error message

Agent Management

• GET /api/threads - List user threads (userId from auth)
• GET /api/threads/:id - Get thread details
• POST /api/threads/pin/:id - Update thread pin state
• POST /api/threads/delete/:id - Delete thread
• GET /api/model - Get model list
• GET /api/agent/a2a - Get A2A connectors
• GET /api/intent - List all intents
• POST /api/intent/save - Save intent
• POST /api/intent/delete/:id - Delete intent
• GET /api/workflow-template - List all workflow templates
• GET /api/workflow-template/:id - Get workflow template details
• POST /api/workflow-template - Create workflow template
• POST /api/workflow-template/update/:id - Update workflow template
• POST /api/workflow-template/delete/:id - Delete workflow template
• GET /api/user-workflow - List user workflows
• GET /api/user-workflow/:id - Get user workflow details
• POST /api/user-workflow - Create user workflow
• POST /api/user-workflow/:id/execute - Execute user workflow (non-streaming)
• POST /api/user-workflow/:id/execute/stream - Execute user workflow with streaming (SSE)
• POST /api/user-workflow/update/:id - Update user workflow
• POST /api/user-workflow/delete/:id - Delete user workflow

Document Endpoints (when the memory module provides IDocumentMemory)

• GET /api/document - List documents (filterable by workflowId, threadId, source, and subset-match labels[...])
• GET /api/document/:id - Get document details
• POST /api/document - Create a document (source: MANUAL)
• POST /api/document/:id/slots/:slotId/fill - Fill a slot via its bound workflow/query (non-streaming)
• POST /api/document/:id/slots/:slotId/fill/stream - Fill a slot with streaming (SSE)
  • Body: { workflowId?: string, executionVariables?: Record<string, string> }
• POST /api/document/:id/advice/stream - Generate AI advice with streaming (SSE)
  • Body: { advicePrompt?: string } (optional per-call prompt override)
• POST /api/document/update/:id - Update document (title/content/slots/labels; marks editedManually)
• POST /api/document/delete/:id - Delete document

A2A Server Endpoints (when manifest.url is configured)

• GET /.well-known/agent.json - Agent discovery endpoint (A2A ~v0.2.0)
• GET /.well-known/agent-card.json - Agent discovery endpoint (A2A v0.3.0~)
  • Returns AgentCard with capabilities and supported modes
• POST /a2a - A2A communication endpoint
  • Uses the @a2a-js/sdk JSON-RPC transport
  • Supports JSON-RPC responses and SDK-managed SSE streaming responses
  • A2A contextId is treated as the AIN-ADK thread ID

Build System

The project supports dual build output:

• ESM (dist/esm/): ES Module format with {"type": "module"}
• CJS (dist/cjs/): CommonJS format with {"type": "commonjs"}

Error Handling

The library includes comprehensive error handling:

• Global error middleware for uncaught errors
• Custom AinHttpError class for HTTP-specific errors
• Service-specific error logging with structured context
• Graceful handling of:
  • MCP server connection failures
  • A2A agent communication errors
  • Model API failures (rate limits, timeouts)
  • Tool execution errors
  • Invalid requests
  • Streaming errors with proper cleanup

All errors are logged with appropriate context for debugging.

Authentication

The library requires an authentication module:

import { AuthModule } from '@ainetwork/adk/modules';
import type { AuthResponse } from '@ainetwork/adk/types/auth';

class MyAuth extends AuthModule {
  async authenticate(req: Request, res: Response): Promise<AuthResponse> {
    // Implement your auth logic
    return { isAuthenticated: true, userId: 'user-123' };
  }
}

const agent = new AINAgent(manifest, {
  authModule: new MyAuth(),
  modelModule,
  memoryModule,
});

Contributing

1. Follow the established code conventions (tabs, double quotes)
2. Use TypeScript strict mode
3. Add appropriate service-specific logging
4. Run yarn biome:write and yarn test before submitting
5. Maintain the modular architecture
6. Update JSDoc comments when changing function signatures
7. Add streaming support when implementing new query handlers

License

MIT