Add TypeScript SDK Implementation to AgentConnect

[BatchLion]

Add TypeScript SDK Implementation to AgentConnect

Overview

This PR adds a comprehensive TypeScript implementation of the Agent Network Protocol (ANP) to the AgentConnect project. The TypeScript SDK provides developers with a type-safe, modern JavaScript/TypeScript interface to build intelligent agents that can authenticate, discover, and communicate in a decentralized network.

What's Being Added

📦 New Directory Structure

typescript/
├── ts_sdk/                    # TypeScript SDK implementation
│   ├── src/                   # Source code
│   │   ├── core/             # Core modules (DID, Auth, ADP, Discovery)
│   │   ├── protocol/         # Protocol layer (Meta-protocol, Message Handler)
│   │   ├── crypto/           # Cryptography module
│   │   ├── transport/        # Transport layer (HTTP client)
│   │   ├── types/            # TypeScript type definitions
│   │   └── errors/           # Error classes
│   ├── tests/                # Test suite
│   ├── examples/             # Example applications
│   ├── docs/                 # Documentation
│   ├── README.md             # SDK documentation
│   ├── CONTRIBUTING.md       # Contribution guidelines
│   ├── CHANGELOG.md          # Version history
│   ├── PUBLISHING.md         # Publishing guide
│   └── RELEASE_NOTES.md      # Release notes

Key Features

🔐 DID:WBA Identity Management

• Create and manage decentralized identities using the did:wba method
• Generate and resolve DID documents
• Sign and verify data with DID identities
• Support for multiple key types (ECDSA secp256k1, Ed25519, X25519)

🔑 HTTP Authentication

• Secure agent-to-agent authentication using DID:WBA signatures
• Access token generation and validation
• Nonce replay prevention
• Clock skew tolerance for distributed systems

📋 Agent Description Protocol (ADP)

• Create and publish agent capability descriptions
• Add information resources and interfaces
• Sign and verify agent descriptions
• Fetch and parse agent descriptions from URLs

🔍 Agent Discovery Service Protocol (ADSP)

• Active Discovery: Find agents from domain names
• Passive Discovery: Register with search services
• Search for agents by capabilities
• Automatic pagination handling

🤝 Meta-Protocol Negotiation

• Dynamic protocol negotiation between agents
• XState v5 powered state machine for robust flow control
• Code generation coordination
• Test case negotiation
• Error fixing negotiation

🔒 End-to-End Encryption

• ECDHE key exchange for secure communication
• AES-GCM encryption and decryption
• Key derivation with HKDF
• Support for encrypted agent-to-agent communication

🛠️ Developer Experience

• Full TypeScript support with comprehensive type definitions
• ESM and CommonJS module formats
• High-level API for common operations
• Low-level access for advanced use cases
• Extensive documentation and examples
• 80%+ test coverage

Technical Details

Dependencies

• XState v5: State machine management for protocol negotiation
• Canonicalize: JSON canonicalization for signatures
• Node.js >= 18.0.0: Modern JavaScript runtime support

Build System

• TypeScript 5.3+: Type-safe development
• tsup: Fast bundler for ESM and CommonJS outputs
• Vitest: Modern testing framework
• ESLint + Prettier: Code quality and formatting

Testing

• Comprehensive unit tests for all modules
• Integration tests for end-to-end flows
• 80%+ code coverage
• Automated testing in CI/CD pipeline

Documentation Updates

All documentation has been aligned with the AgentConnect project standards:

• ✅ Updated package name references to agent-connect-ts
• ✅ Updated repository links to agent-network-protocol/AgentConnect
• ✅ Added consistent contact information (Discord, email, WeChat)
• ✅ Aligned contribution guidelines with main project
• ✅ Updated all GitHub links and issue trackers
• ✅ Added project context explaining relationship to AgentConnect

Compatibility

Language Parity with Python SDK

The TypeScript SDK implements the same core features as the Python SDK:

• ✅ DID:WBA authentication
• ✅ Agent Description Protocol
• ✅ Agent Discovery Service Protocol
• ✅ Meta-protocol negotiation
• ✅ End-to-end encryption
• ✅ HTTP transport layer

Cross-Language Interoperability

• TypeScript agents can communicate with Python agents
• Shared protocol specifications ensure compatibility
• Consistent JSON-RPC message formats
• Compatible cryptographic implementations

Installation & Usage

# Install from npm (after publishing)
npm install agent-connect-ts

# Or install from source
cd typescript/ts_sdk
npm install
npm run build

Quick Example

import { ANPClient } from 'agent-connect-ts';

// Initialize the client
const client = new ANPClient({ debug: true });

// Create a DID identity
const identity = await client.did.create({
  domain: 'example.com',
  path: 'agent1'
});

// Create an agent description
const description = client.agent.createDescription({
  name: 'My Agent',
  description: 'An intelligent ANP agent',
  protocolVersion: '0.1.0'
});

// Discover other agents
const agents = await client.discovery.discoverAgents('example.com');

Testing

All tests pass successfully:

cd typescript/ts_sdk
npm test              # Run all tests
npm run test:coverage # Run with coverage report
npm run lint          # Check code quality
npm run typecheck     # Verify TypeScript types

Breaking Changes

None - this is a new addition to the project.

Migration Guide

Not applicable - this is a new SDK implementation.

Checklist

• Code follows project coding standards
• All tests pass
• Documentation is complete and accurate
• Examples are provided and tested
• CHANGELOG.md is updated
• README.md is updated
• No breaking changes to existing Python SDK
• TypeScript types are comprehensive
• Error handling is implemented
• Security best practices followed

Future Enhancements

Planned for future releases:

• WebSocket transport support
• Browser compatibility
• Plugin system for extensibility
• Enhanced monitoring and telemetry
• Multi-DID support per client
• Performance optimizations

Additional Context

This TypeScript SDK was developed in a separate repository and is now being integrated into the main AgentConnect monorepo. All documentation has been updated to reflect the new structure and maintain consistency with the Python SDK.

The SDK is production-ready with comprehensive tests, documentation, and examples. It provides TypeScript/JavaScript developers with a native way to build ANP-compliant agents without needing to use Python.

Contact & Support

• Author: Dongyang Zhao
• Email: [email protected]

---

Note: This PR significantly expands the AgentConnect ecosystem by adding first-class TypeScript support, making ANP accessible to the vast JavaScript/TypeScript developer community.

[Moshiii]

@chgaowei this is major update. Please review