核心类型

AgentConfig

interface CreateAgentOptions {
  agentId: string           // 唯一标识
  name: string              // 显示名称
  version: string           // 版本号
  description: string       // 能力描述
  address: string           // 监听地址（a2a:// 或 a2as://）
  skills: SkillDefinition[] // 技能列表
  defaultSkill: string      // 默认技能
  tls?: TLSConfig           // TLS 配置（a2as:// 时必填）
}

TLSConfig

interface TLSConfig {
  cert: string   // 证书文件路径（PEM 格式）
  key: string    // 私钥文件路径（PEM 格式）
  ca?: string    // CA 证书文件路径（可选，用于客户端证书验证）
}

地址协议说明：

• a2a://host:port - 不加密（开发环境）
• a2as://host:port - TLS 加密（生产环境，需配置 tls）

ClientConfig

interface ClientConfig {
  agentId: string
  host: string
  port: number
  namespace?: string
}

CallOptions

interface CallOptions {
  metadata?: Record<string, string>
  signal?: AbortSignal
}

SkillDefinition

interface SkillDefinition {
  name: string
  handler: SkillHandler
  description?: string
  inputSchema?: JsonSchema
}

type SkillHandler<TParams, TResult> =
  (params: TParams, ctx: Context) => Promise<TResult>

BidirectionalStream

interface BidirectionalStream {
  send: (message: Message) => void
  cancel: (reason?: string) => void
  end: () => void
  on?: (type: string, handler: (msg: Message) => void) => this
  [Symbol.asyncIterator]: () => AsyncIterator<Message>
}

ServerPlugin / ClientPlugin

interface ServerPlugin {
  hooks: ServerHooks
}

interface ClientPlugin {
  hooks: ClientHooks
}

HookResult

type HookResult = 'handled' | 'pass' | 'exit' | void

// 'handled' - 跳过默认处理
// 'pass'    - 继续默认处理（默认）
// 'exit'    - 退出消息循环

TracingProvider

interface TracingProvider {
  reportTrace: (record: TraceRecord) => Promise<void>
}

interface TraceRecord {
  traceId: string
  spanId: string
  parentSpanId?: string
  agentId: string
  skill: string
  startedAt: string
  duration: number
}

IOMetricsProvider

interface IOMetricsProvider {
  verifyIntegrity: (params: {
    agentId: string
    sdkHash: string
  }) => Promise<{ valid: boolean; signingKey?: string }>

  reportMetrics: (metrics: VerifiedIOMetrics) => Promise<void>

  preCallCheck?: (params: {
    userId: string
    agentId: string
  }) => Promise<{ allowed: boolean }>
}

interface VerifiedIOMetrics {
  metricsId: string
  traceId: string
  spanId: string
  agentId: string
  skill: string
  inputCommitment: IOCommitment
  outputCommitment: IOCommitment
  duration: number
  userId?: string
}

MCPServerConfig

interface MCPServerConfig {
  name: string
  transport: 'stdio' | 'http'
  command?: string
  args?: string[]
  url?: string
  env?: Record<string, string>
}