Transports

Transports are the communication protocols that enable agents to connect and exchange messages within OpenAgents networks. Different transports offer various trade-offs between performance, compatibility, and features.

Transport Overview

OpenAgents supports multiple transport protocols that can be used simultaneously within a single network:

network:
  transports:
    - type: "http"
      config:
        port: 8700
    - type: "grpc"  
      config:
        port: 8600
        max_message_size: 52428800  # 50MB
        compression: "gzip"
    - type: "a2a"
      config:
        enabled: true

Agents automatically negotiate the best available transport based on network configuration and capabilities.

HTTP Transport

Overview

HTTP transport provides REST-based communication that's simple to implement and debug:

transports:
  - type: "http"
    config:
      port: 8700
      host: "0.0.0.0"          # Bind address
      max_request_size: 10485760  # 10MB
      timeout: 30              # Request timeout in seconds
      cors_enabled: true       # Enable CORS for web clients
      tls_enabled: false       # Use HTTPS (requires cert/key)

Characteristics

Advantages:

Simple to implement and debug
Wide compatibility with web technologies
Easy to inspect with standard HTTP tools
Built-in support for file uploads
Compatible with web browsers and curl

Limitations:

Higher overhead compared to binary protocols
Less efficient for high-frequency communication
Limited to request-response patterns
No built-in streaming support

Use Cases

Web Integration: Connecting web applications and browsers
Development: Easy debugging and testing
REST APIs: Building HTTP-based agent interfaces
File Sharing: Uploading and downloading files
Studio Interface: OpenAgents Studio web interface

Configuration Options

transports:
  - type: "http"
    config:
      port: 8700
      host: "localhost"        # Listen address
      max_request_size: 52428800  # Maximum request size (50MB)
      timeout: 60              # Request timeout
      
      # Security settings
      cors_enabled: true
      cors_origins: ["*"]      # Allowed CORS origins
      
      # TLS/HTTPS settings
      tls_enabled: true
      tls_cert_path: "/path/to/cert.pem"
      tls_key_path: "/path/to/key.pem"
      
      # Performance tuning
      keep_alive: true
      max_connections: 1000

gRPC Transport

Overview

gRPC provides high-performance binary communication with advanced features:

transports:
  - type: "grpc"
    config:
      port: 8600
      max_message_size: 104857600  # 100MB
      compression: "gzip"
      keep_alive_time: 60
      keep_alive_timeout: 5

Characteristics

Advantages:

High performance binary protocol
Built-in compression and streaming
Strong typing with Protocol Buffers
Efficient connection multiplexing
Low latency for high-frequency communication

Limitations:

More complex to debug than HTTP
Limited browser support without proxies
Requires understanding of Protocol Buffers
Firewall/proxy compatibility issues

Use Cases

Production Networks: High-performance agent communication
Real-time Systems: Low-latency message exchange
Large Data Transfer: Efficient streaming of large datasets
Resource-Constrained Environments: Lower CPU and bandwidth usage

Configuration Options

transports:
  - type: "grpc"
    config:
      port: 8600
      host: "0.0.0.0"
      
      # Message settings
      max_message_size: 104857600  # 100MB max message
      max_receive_message_size: 104857600
      max_send_message_size: 104857600
      
      # Compression
      compression: "gzip"        # gzip, deflate, or none
      compression_level: 6       # 1-9 for gzip
      
      # Connection management  
      keep_alive_time: 60        # Send keepalive every 60s
      keep_alive_timeout: 5      # Wait 5s for keepalive response
      keep_alive_without_calls: true
      max_connection_idle: 300   # Close idle connections after 5m
      max_connection_age: 1800   # Close connections after 30m
      
      # Security
      tls_enabled: true
      tls_cert_path: "/path/to/cert.pem"
      tls_key_path: "/path/to/key.pem"
      mutual_tls: false          # Require client certificates
      
      # Performance tuning
      max_concurrent_streams: 100
      window_size: 65536         # Flow control window

Agent-to-Agent (A2A) Transport

Overview

A2A transport enables direct peer-to-peer communication between agents, bypassing the network coordinator:

transports:
  - type: "a2a"
    config:
      enabled: true
      port_range: "9000-9100"   # Port range for A2A connections
      max_connections: 50       # Max simultaneous A2A connections
      discovery_method: "coordinator"  # How to discover peer addresses

Characteristics

Advantages:

Direct communication reduces latency
Bypasses coordinator bottlenecks
Scales with number of agents
Reduced network coordinator load

Limitations:

More complex network topology
Requires firewall configuration
NAT traversal challenges
Increased connection management complexity

Use Cases

High-Frequency Trading: Ultra-low latency communication
Distributed Computing: Direct data exchange between workers
Peer Networks: Decentralized agent collaboration
Large Networks: Scaling beyond coordinator limits

Configuration Options

transports:
  - type: "a2a"
    config:
      enabled: true
      
      # Port management
      port_range: "9000-9100"   # Available ports for A2A
      bind_address: "0.0.0.0"   # Listen address
      
      # Connection limits
      max_connections: 100      # Max concurrent A2A connections
      connection_timeout: 30    # Connection establishment timeout
      
      # Discovery
      discovery_method: "coordinator"  # coordinator, mdns, or manual
      discovery_interval: 60    # How often to refresh peer info
      
      # Security
      encryption_enabled: true
      authentication_required: true
      
      # Performance
      buffer_size: 65536        # Send/receive buffer size
      no_delay: true           # Disable Nagle's algorithm

Transport Selection

Automatic Negotiation

Agents automatically select the best transport based on:

Availability: Which transports are enabled in the network
Capabilities: Agent transport support
Performance Requirements: Latency and throughput needs
Security Requirements: Encryption and authentication needs

# Agent automatically negotiates best transport
agent = MyAgent()
agent.start(
    network_host="example.com",
    network_port=8700,
    preferred_transport="grpc"  # Preference, but will fall back
)

Manual Transport Selection

Force a specific transport for testing or requirements:

# Force HTTP transport
agent.start(
    network_host="example.com", 
    network_port=8700,
    transport="http"
)
 
# Force gRPC transport  
agent.start(
    network_host="example.com",
    network_port=8600,
    transport="grpc"
)

Transport Recommendations

The network can specify recommended transports:

network:
  # Transport for manifest and discovery
  manifest_transport: "http"
  
  # Recommended transport for agents
  recommended_transport: "grpc"
  
  # Fallback transport
  fallback_transport: "http"

Performance Characteristics

Latency Comparison

Typical latency characteristics for different transports:

| Transport | Latency | Throughput | CPU Usage | Memory | |-----------|---------|------------|-----------|---------| | HTTP | ~5-10ms | Medium | Medium | Medium | | gRPC | ~1-3ms | High | Low | Low | | A2A | ~0.5-1ms| Very High | Very Low | Low |

Throughput Benchmarks

Performance varies based on message size and frequency:

# Benchmark different transports
class BenchmarkAgent(WorkerAgent):
    async def benchmark_transports(self):
        # Test message sending performance
        start_time = time.time()
        
        for i in range(1000):
            await self.send_test_message(f"Message {i}")
        
        duration = time.time() - start_time
        throughput = 1000 / duration
        
        self.logger.info(f"Throughput: {throughput:.2f} messages/second")

Security Considerations

Transport Security

Enable encryption for sensitive communications:

# HTTP with TLS
transports:
  - type: "http"
    config:
      port: 8443
      tls_enabled: true
      tls_cert_path: "/etc/ssl/certs/server.crt"
      tls_key_path: "/etc/ssl/private/server.key"
 
# gRPC with TLS
transports:
  - type: "grpc"
    config:
      port: 8600
      tls_enabled: true
      tls_cert_path: "/etc/ssl/certs/server.crt" 
      tls_key_path: "/etc/ssl/private/server.key"
      mutual_tls: true  # Require client certificates

Authentication

Secure transport endpoints with authentication:

# Network-level authentication
authentication:
  type: "token"
  required_for_transports: ["http", "grpc"]
  token_validation_endpoint: "https://auth.example.com/validate"
 
# Transport-specific authentication
transports:
  - type: "grpc"
    config:
      port: 8600
      authentication:
        method: "jwt"
        jwt_secret: "${JWT_SECRET}"
        jwt_algorithm: "HS256"

Monitoring and Debugging

Transport Metrics

Monitor transport performance and health:

# Get transport statistics
stats = await network.get_transport_stats()
print(f"HTTP connections: {stats['http']['active_connections']}")
print(f"gRPC messages/sec: {stats['grpc']['messages_per_second']}")
print(f"A2A latency avg: {stats['a2a']['average_latency_ms']}ms")

Debug Tools

Use built-in tools to debug transport issues:

# Test HTTP transport
curl -X POST http://localhost:8700/manifest
 
# Test gRPC transport with grpcurl
grpcurl -plaintext localhost:8600 openagents.NetworkService/GetManifest
 
# Monitor transport logs
openagents network logs MyNetwork --transport=grpc --follow

Connection Troubleshooting

Common transport issues and solutions:

Connection Refused: Check if transport is enabled and port is open
Timeout Errors: Adjust timeout settings or check network latency
Certificate Errors: Verify TLS certificate configuration
Firewall Issues: Ensure required ports are open
NAT Problems: Configure port forwarding for A2A transport

Best Practices

Transport Configuration

Use gRPC for Production: Better performance for agent-to-agent communication
Keep HTTP for Web Integration: Essential for Studio and web clients
Enable Compression: Reduces bandwidth usage, especially for gRPC
Configure Timeouts: Set appropriate timeouts for your use case
Monitor Performance: Track transport metrics and optimize

Security Best Practices

Always Use TLS in Production: Encrypt all network communication
Implement Authentication: Require authentication for all transports
Use Strong Certificates: Proper certificate management and rotation
Limit Access: Use firewalls to restrict transport access
Monitor Security Events: Log and monitor authentication failures

Performance Optimization

Tune Message Sizes: Optimize max message size for your workload
Connection Pooling: Reuse connections efficiently
Compression Settings: Balance CPU usage vs bandwidth
Keep-Alive Configuration: Optimize connection persistence
Load Testing: Test transport performance under load

Next Steps

Network Mods - Learn about extensible functionality
Agent Connection - Understand agent connectivity
Network Configuration - Complete transport configuration
Python Interface - Connect agents programmatically