{
  "agent_card": {
    "name": "financial-analyzer",
    "description": "分析财务报表并生成洞察",
    "capabilities": ["financial_analysis", "risk_assessment"],
    "input_schema": {
      "type": "object",
      "properties": {
        "report_url": {"type": "string"},
        "analysis_depth": {"enum": ["quick", "standard", "deep"]}
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"},
        "risk_score": {"type": "number"},
        "recommendations": {"type": "array"}
      }
    }
  }
}

# agent-blackboard 实现示例
from agent_blackboard import Blackboard, KnowledgeSource, Controller

class BlackboardSystem:
    def __init__(self):
        self.blackboard = Blackboard(levels=[
            "raw_data",       # 原始数据层
            "features",       # 特征提取层
            "hypotheses",     # 假设生成层
            "decisions",      # 决策层
            "actions"         # 行动层
        ])
        self.controller = Controller(self.blackboard)

    def register_agents(self):
        # 每个Agent声明自己读哪些层、写哪些层
        self.controller.register(
            KnowledgeSource(
                name="data_collector",
                reads=[], writes=["raw_data"],
                trigger=lambda bb: bb.is_empty("raw_data")
            )
        )
        self.controller.register(
            KnowledgeSource(
                name="feature_extractor",
                reads=["raw_data"], writes=["features"],
                trigger=lambda bb: bb.has_data("raw_data") and bb.is_empty("features")
            )
        )
        self.controller.register(
            KnowledgeSource(
                name="hypothesis_generator",
                reads=["features"], writes=["hypotheses"],
                trigger=lambda bb: bb.has_data("features")
            )
        )

# OpenAI Agents SDK Handoff 示例
from agents import Agent, handoff, RunContextWrapper

# 创建专家Agent
billing_agent = Agent(
    name="billing_specialist",
    instructions="你是账单专家，处理所有与费用、发票、退款相关的问题。",
    tools=[lookup_invoice, process_refund]
)

technical_agent = Agent(
    name="technical_specialist", 
    instructions="你是技术支持专家，处理产品使用问题和故障排查。",
    tools=[search_knowledge_base, create_ticket]
)

# Supervisor持有全局上下文，通过Handoff分配任务
supervisor = Agent(
    name="customer_service_supervisor",
    instructions="""你是客户服务主管。根据用户问题类型，将对话移交给合适的专家。
    交接时你必须总结当前对话上下文，让专家能无缝接手。""",
    handoffs=[
        handoff(agent=billing_agent, 
                tool_name_description="移交账单问题"),
        handoff(agent=technical_agent,
                tool_name_description="移交技术支持问题")
    ]
)

async def summarize_before_handoff(ctx: RunContextWrapper):
    """在交接前压缩上下文"""
    conversation = ctx.conversation
    summary = await compress(conversation, max_tokens=500)
    ctx.set_handoff_context(summary)

handoff(
    agent=technical_agent,
    on_handoff=summarize_before_handoff
)

# 事件驱动的多Agent协作示例
from dataclasses import dataclass
from datetime import datetime
from typing import List

@dataclass
class AgentEvent:
    event_type: str
    agent_id: str
    timestamp: datetime
    payload: dict
    correlation_id: str  # 追踪同一任务流

class EventLog:
    def __init__(self):
        self.events: List[AgentEvent] = []

    def append(self, event: AgentEvent):
        self.events.append(event)
        self._notify_subscribers(event)

    def replay(self, correlation_id: str) -> dict:
        """重放某任务流的全部事件，重建当前状态"""
        state = {}
        for event in self.events:
            if event.correlation_id == correlation_id:
                state = apply_event(state, event)
        return state

# Agent通过消费事件获取上下文
class ResearchAgent:
    def on_event(self, event: AgentEvent):
        if event.event_type == "query_received":
            self.start_research(event.payload)
        elif event.event_type == "data_collected":
            self.analyze_data(event.payload)

    def emit(self, event_type: str, payload: dict):
        event = AgentEvent(
            event_type=event_type,
            agent_id=self.id,
            timestamp=datetime.now(),
            payload=payload,
            correlation_id=self.current_task_id
        )
        self.event_log.append(event)

# 概念性元组空间实现
class AgentTupleSpace:
    def __init__(self):
        self.space = []

    def write(self, pattern: str, data: dict, ttl: int = 3600):
        """写入一个元组"""
        entry = {
            "pattern": pattern,
            "data": data,
            "expires_at": time.time() + ttl,
            "written_by": current_agent_id
        }
        self.space.append(entry)

    def read(self, pattern: str) -> Optional[dict]:
        """非阻塞读取（不删除）匹配的元组"""
        return self._match(pattern, remove=False)

    def take(self, pattern: str) -> Optional[dict]:
        """原子性地读取并删除匹配的元组"""
        return self._match(pattern, remove=True)

    def _match(self, pattern: str, remove: bool):
        for i, entry in enumerate(self.space):
            if self._matches(entry["pattern"], pattern):
                if remove:
                    return self.space.pop(i)
                return entry["data"]
        return None

# Agent协作示例：研究任务分解
researcher.write("task_available", {
    "type": "literature_review",
    "topic": "multi-agent systems",
    "priority": "high"
})

# 另一个Agent按需取走任务
writer.take("task_available:type=literature_review")

flowchart TD
    A[多Agent知识共享选型] --> B{Agent是否跨服务/跨组织?}
    B -->|是| C{需要审计追踪吗?}
    B -->|否| D{Agent职责是否明确?}

    C -->|是| E[事件溯源日志]
    C -->|否| F[A2A直接消息传递]

    D -->|是| G{需要多少层级?}
    D -->|否| H{协作模式是否动态?}

    G -->|1-2层| I[层级上下文级联<br/>OpenAI Handoff]
    G -->|3+层| J[层级级联 + 上下文摘要]

    H -->|是| K[共享黑板 Blackboard]
    H -->|不确定| L[分布式元组空间<br/>早期探索]

    E --> M[实现栈: Temporal + Agent Framework]
    F --> N[实现栈: A2A Protocol + Agent Registry]
    I --> O[实现栈: OpenAI Agents SDK / AutoGen]
    J --> P[实现栈: LangGraph State + Checkpoint]
    K --> Q[实现栈: agent-blackboard + Redis]
    L --> R[实现栈: Apache Ignite / 自建]

graph TB
    subgraph 混合知识共享架构
        S[Supervisor Agent<br/>持有全局上下文] -->|Handoff + 上下文传递| A1[Research Agent]
        S -->|Handoff + 上下文传递| A2[Analysis Agent]
        S -->|Handoff + 上下文传递| A3[Writing Agent]

        BB[共享黑板<br/>中间结果层]
        A1 -->|写入研究发现| BB
        A2 -->|写入分析结论| BB
        BB -->|读取研究数据| A2
        BB -->|读取研究+分析| A3

        EL[事件日志<br/>审计追踪]
        A1 -.->|记录状态变更| EL
        A2 -.->|记录状态变更| EL
        A3 -.->|记录状态变更| EL
        S -.->|记录决策| EL
    end

graph LR
    subgraph 2026协议栈演进
        direction TB
        L1[A2UI - 用户交互层<br/>Agent与人类的接口]
        L2[A2A - Agent协作层<br/>Agent间的发现与协商]
        L3[MCP - 工具连接层<br/>Agent与外部工具的接口]
        L4[AKIF - 知识交换层<br/>Agent间结构化知识共享<br/>2026H2 预计出现]
    end

    L1 --> L2 --> L3
    L2 -.-> L4
    L3 -.-> L4