Agent-to-Agent Protocol SDK Patterns
Purpose: Provide installation, configuration, and usage patterns for A2A Protocol SDKs across multiple programming languages.
Activation Triggers:
-
SDK installation requests
-
Language-specific A2A setup
-
Authentication configuration
-
Package dependency issues
-
SDK version compatibility
-
Import/setup errors
Supported Languages:
-
Python (3.8+)
-
TypeScript/JavaScript (Node 18+)
-
Java (11+)
-
C# (.NET 6+)
-
Go (1.20+)
Quick Start by Language
Python
Install SDK
./scripts/install-python.sh
Verify installation
./scripts/validate-python.sh
TypeScript
Install SDK
./scripts/install-typescript.sh
Verify installation
./scripts/validate-typescript.sh
Java
Install SDK
./scripts/install-java.sh
Verify installation
./scripts/validate-java.sh
C#
Install SDK
./scripts/install-csharp.sh
Verify installation
./scripts/validate-csharp.sh
Go
Install SDK
./scripts/install-go.sh
Verify installation
./scripts/validate-go.sh
Installation Scripts
All installation scripts are in scripts/ directory:
-
install-python.sh
-
Install Python SDK via pip
-
install-typescript.sh
-
Install TypeScript SDK via npm/yarn
-
install-java.sh
-
Install Java SDK via Maven/Gradle
-
install-csharp.sh
-
Install C# SDK via NuGet
-
install-go.sh
-
Install Go SDK via go get
Validation scripts verify installation and dependencies:
-
validate-python.sh
-
Check Python SDK installation
-
validate-typescript.sh
-
Check TypeScript SDK installation
-
validate-java.sh
-
Check Java SDK installation
-
validate-csharp.sh
-
Check C# SDK installation
-
validate-go.sh
-
Check Go SDK installation
Configuration Templates
Templates are in templates/ directory:
Environment Setup:
-
env-template.txt
-
Environment variable template (all languages)
-
python-config.py
-
Python configuration example
-
typescript-config.ts
-
TypeScript configuration example
-
java-config.xml
-
Java Maven configuration
-
csharp-config.csproj
-
C# project configuration
-
go-mod.txt
-
Go module configuration
Authentication:
-
auth-api-key-template.txt
-
API key authentication
-
auth-oauth-template.txt
-
OAuth authentication
-
auth-jwt-template.txt
-
JWT authentication
Common Setup Patterns
Environment Variables
All SDKs use environment variables for configuration:
Required
A2A_API_KEY=your_api_key_here A2A_BASE_URL=https://api.a2a.example.com
Optional
A2A_TIMEOUT=30 A2A_RETRY_ATTEMPTS=3 A2A_LOG_LEVEL=info
CRITICAL: Always use placeholders in committed files. Create .env.example with placeholder values only.
Authentication Setup
All SDKs support three authentication methods:
-
API Key - Simplest, for server-to-server
-
OAuth 2.0 - For user-delegated access
-
JWT - For service-to-service with custom claims
See templates/auth-*-template.txt for implementation patterns.
Error Handling
All SDKs provide consistent error handling:
-
A2AConnectionError
-
Network/connectivity issues
-
A2AAuthenticationError
-
Invalid credentials
-
A2ARateLimitError
-
Rate limit exceeded
-
A2AValidationError
-
Invalid request data
See examples/error-handling-*.md for language-specific patterns.
Language-Specific Considerations
Python
-
Requires Python 3.8+
-
Install via pip: pip install a2a-protocol
-
Async support via asyncio
-
Type hints available
-
See examples/python-basic.py
TypeScript
-
Requires Node 18+
-
Install via npm: npm install @a2a/protocol
-
Full TypeScript definitions included
-
Promise-based async/await
-
See examples/typescript-basic.ts
Java
-
Requires Java 11+
-
Maven: Add to pom.xml
-
Gradle: Add to build.gradle
-
Thread-safe client
-
See examples/java-basic.java
C#
-
Requires .NET 6+
-
NuGet: dotnet add package A2A.Protocol
-
Async/await support
-
Dependency injection ready
-
See examples/csharp-basic.cs
Go
-
Requires Go 1.20+
-
Install: go get github.com/a2a/protocol-go
-
Context-aware operations
-
Goroutine-safe
-
See examples/go-basic.go
Troubleshooting
Installation Issues
Package not found:
Python
pip install --upgrade pip pip install a2a-protocol
TypeScript
npm cache clean --force npm install @a2a/protocol
Java
mvn clean install -U
C#
dotnet restore --force
Go
go clean -modcache go get -u github.com/a2a/protocol-go
Version conflicts: Run the appropriate validation script to check dependencies:
./scripts/validate-<language>.sh
Authentication Errors
-
Check environment variables are set
-
Verify API key format (no extra spaces/newlines)
-
Ensure base URL is correct
-
Check API key permissions
Connection Issues
-
Verify network connectivity
-
Check firewall/proxy settings
-
Validate base URL is accessible
-
Review timeout settings
Security Best Practices
Environment Variables:
-
NEVER commit actual API keys
-
Use .env files (add to .gitignore )
-
Create .env.example with placeholders
-
Use secret management in production (Vault, AWS Secrets Manager, etc.)
API Keys:
-
Rotate keys regularly
-
Use different keys for dev/staging/prod
-
Implement key expiration
-
Monitor key usage
Network Security:
-
Always use HTTPS
-
Validate SSL certificates
-
Implement request signing for sensitive operations
-
Use VPN/private networks for production
Examples
Complete examples for each language:
-
examples/python-basic.py
-
Basic Python usage
-
examples/python-async.py
-
Async Python usage
-
examples/typescript-basic.ts
-
Basic TypeScript usage
-
examples/java-basic.java
-
Basic Java usage
-
examples/csharp-basic.cs
-
Basic C# usage
-
examples/go-basic.go
-
Basic Go usage
-
examples/error-handling-python.md
-
Python error handling
-
examples/error-handling-typescript.md
-
TypeScript error handling
-
examples/error-handling-java.md
-
Java error handling
Resources
Official Documentation:
-
Python SDK: https://docs.a2a-protocol.org/python
-
TypeScript SDK: https://docs.a2a-protocol.org/typescript
-
Java SDK: https://docs.a2a-protocol.org/java
-
Go SDK: https://docs.a2a-protocol.org/go
GitHub Repositories:
-
TypeScript: https://github.com/a2a/protocol-ts
Version: 1.0.0 Protocol Compatibility: A2A Protocol 1.0+