协议设计¶

命令 (Commands)¶

命令定义在 src/by_framework/core/protocol/commands.py：

AskAgentCommand¶

任务指令，用于向 Agent 发送请求：

from by_framework.core.protocol.commands import AskAgentCommand
from by_framework.core.protocol.message_header import MessageHeader

command = AskAgentCommand(
    header=MessageHeader(
        message_id="msg_123",
        session_id="sess_456",
        target_agent_type="weather_agent"
    ),
    content="查询北京天气",
    extra_payload={
        "location": "北京"
    }
)

CancelTaskCommand¶

取消任务指令：

CancelTaskCommand(
    header=header,
    reason="用户主动取消"
)

ResumeCommand¶

恢复被挂起的任务（人机交互场景）：

ResumeCommand(
    header=header,
    content="用户输入的内容"
)

事件 (Events)¶

事件定义在 src/by_framework/core/protocol/events.py：

StreamChunkEvent¶

流式文本片段：

StreamChunkEvent(
    content="正在处理...",
    event_type="answerDelta"
)

StateChangeEvent¶

状态变更：

StateChangeEvent(
    state="thinking",
    event_type="stateChange"
)

ArtifactEvent¶

产物/附件：

ArtifactEvent(
    url="https://example.com/result.json",
    event_type="artifact"
)

AskUserEvent¶

向用户请求输入：

AskUserEvent(
    prompt="请确认是否继续？",
    event_type="askUser"
)

消息头 (MessageHeader)¶

from by_framework.core.protocol.message_header import MessageHeader

header = MessageHeader(
    message_id="msg_123",        # 消息唯一ID
    session_id="sess_456",       # 会话ID
    trace_id="trace_789",       # 追踪ID
    target_agent_type="weather_agent"  # 目标Agent类型
)

常用 EventType 值¶

事件类型	描述
`answerDelta`	回答内容增量
`reasoningLogDelta`	推理或中间日志输出
`appStreamResponse`	标记流结束
`taskCreate`	任务创建相关事件
`taskStop`	任务终止相关事件