传输方式

传输

传输是启用代理在 OpenAgents 网络中连接并交换消息的通信协议。不同的传输方式在性能、兼容性和功能之间提供不同的权衡。

传输概览

OpenAgents 支持多种传输协议，这些协议可以在同一网络中同时使用：

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

代理会根据网络配置和能力自动协商可用的最佳传输。

HTTP 传输

概述

HTTP 传输提供基于 REST 的通信，易于实现和调试：

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)

特性

优点:

易于实现和调试
与 Web 技术高度兼容
可使用标准 HTTP 工具轻松检查
内置对文件上传的支持
与 Web 浏览器和 curl 兼容

限制:

与二进制协议相比开销更大
对于高频通信效率较低
仅限于请求-响应模式
不具备内置的流式支持

使用场景

Web 集成: 连接 Web 应用和浏览器
开发: 便于调试和测试
REST API: 构建基于 HTTP 的代理接口
文件共享: 上传和下载文件
Studio 界面: OpenAgents Studio 的 web 界面

配置选项

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 传输

概述

gRPC 提供具有高级功能的高性能二进制通信:

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

特性

优点:

高性能二进制协议
内置压缩和流式传输
使用 Protocol Buffers 的强类型
高效的连接复用
对高频通信的低延迟

限制:

比 HTTP 更难调试
在没有代理的情况下浏览器支持有限
需要理解 Protocol Buffers
防火墙/代理兼容性问题

使用场景

生产网络: 高性能代理通信
实时系统: 低延迟消息交换
大规模数据传输: 大数据集的高效流式传输
资源受限环境: 更低的 CPU 和带宽使用

配置选项

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

传输选择

自动协商

代理会根据以下内容自动选择最佳传输：

可用性: 网络中启用了哪些传输
能力: 代理对传输的支持
性能要求: 延迟和吞吐量需求
安全要求: 加密和认证需求

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

手动传输选择

为测试或特定需求强制使用特定传输：

# 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"
)

传输建议

网络可以指定推荐的传输：

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

性能特性

延迟比较

不同传输方式的典型延迟特性：

传输方式	延迟	吞吐量	CPU 使用	内存
HTTP	~5-10ms	中等	中等	中等
gRPC	~1-3ms	高	低	低
A2A	~0.5-1ms	非常高	非常低	低

吞吐量基准测试

性能取决于消息大小和频率：

# 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")

安全注意事项

传输安全

为敏感通信启用加密：

# 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

身份验证

使用身份验证保护传输端点：

# 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"

监控与调试

传输指标

监控传输性能和健康状况：

# 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")

调试工具

使用内置工具调试传输问题：

# 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

连接故障排除

常见传输问题及解决方案：

连接被拒绝: 检查传输是否已启用并且端口是否打开
超时错误: 调整超时设置或检查网络延迟
证书错误: 验证 TLS 证书配置
防火墙问题: 确保所需端口已打开
NAT 问题: 为 A2A 传输配置端口转发

最佳实践

传输配置

在生产环境中使用 gRPC: 在 agent 到 agent 的通信中性能更好
为 Web 集成保留 HTTP: 对于 Studio 和网页客户端至关重要
启用压缩: 降低带宽使用，尤其是对于 gRPC
配置超时: 根据你的用例设置合适的超时
监控性能: 跟踪传输指标并进行优化

安全最佳实践

在生产环境中始终使用 TLS: 加密所有网络通信
实现认证: 要求所有传输进行认证
使用强证书: 适当的证书管理和轮换
限制访问: 使用防火墙限制传输访问
监控安全事件: 记录并监控认证失败

性能优化

调整消息大小: 为你的工作负载优化最大消息大小
连接池: 高效重用连接
压缩设置: 在 CPU 使用与带宽之间取得平衡
Keep-Alive 配置: 优化连接持久性
负载测试: 在负载下测试传输性能

下一步

网络扩展 - 了解可扩展功能
代理连接 - 了解代理连接性
网络配置 - 完成传输配置
Python 接口 - 以编程方式连接代理