PhyAgentOS Agent Architecture

Track A 的消息驱动 Agent:上下文在文件、会话历史与运行时状态之间汇聚;模型通过结构化 Tool Call 形成闭环;长期任务通过 Runtime Session 下沉到 Track B。

代码基线:AgentLoop / ContextBuilder / ToolRegistry图示范围:主 Agent、并行服务、Runtime 边界
上下文与消息 推理闭环 运行时协议 后台服务 状态裁决

1 · Ingress / Egress

所有入口统一进入 MessageBus 或 process_direct

Channels & Triggers

CLI · Telegram · Feishu · Slack · Cron · Heartbeat

MessageBus

解耦 channel I/O 与 Agent 处理;OutboundMessage 返回目标通道。

AgentLoop

按 session key 串联消息处理、上下文构建、模型调用、工具执行与结果持久化。

2 · Core Agent Loop

Context → LLM → Tool → Context,最多 maxToolIterations

ContextBuilder

Identity / BootstrapAGENTS.md · SOUL.md · USER.md · TOOLS.md · SKILLS.md
Embodied / Runtime StateEMBODIED.md · ENVIRONMENT.md · TASK.md · RUNTIME.md · TARGETS.md · SESSIONS.md
Conversation HistorySessionManager JSONL:历史 user / assistant / tool messages
Memory & SkillsMEMORY.md · HISTORY.md · 按需加载的 SKILL.md
Current Requestchannel、chat、runtime metadata、文本与 base64 图片
[ system_prompt, history..., user(runtime_metadata + current_input) ]

AgentLoop._run_agent_loop()

LLM Provideriteration 1…N
chat_with_retry()messages + tool schemas + model;Provider 统一 LiteLLM、OpenAI-compatible 与 OAuth 路由。
LLMResponsecontent · reasoning · tool_calls · finish_reason · usage
Assistant Tool Call将 tool_call 写回 messages,保留调用 ID 和结构化 arguments。
Tool Result顺序执行工具,将结果作为 role=tool 消息追加到同一上下文。
↺ 有 tool_calls:携带新增消息继续推理 | 无 tool_calls:产出 final content

ToolRegistry

Filesystemread / write / edit / list
Execshell command boundary
Websearch / fetch
Messagecross-channel delivery
Spawnbackground subagent
Cronscheduled task
Scene GraphENVIRONMENT query
verify_sessionapply waiting / review terminal
Mode / ImageProvidersManager only
MCPdynamic external tools
schema → cast params → validate → execute → string result

3 · Agent-Owned Services

与主对话循环并列,共享 provider 或 workspace

SessionManager

按 channel:chat 保存 JSONL 对话;为 ContextBuilder 提供短期历史和 consolidation offset。

MemoryConsolidator

上下文接近窗口上限时,调用模型压缩历史并写入 MEMORY.md / HISTORY.md。

SubagentManager

为独立任务创建受限工具集的后台 Agent,完成后通过 MessageBus 报告主 Agent。

SessionVerifier

消费 runtime 完成证据,进行语义验收、replan、lesson 与 RGB retention;同时被 verify_session Tool 复用。

4 · Track A / Track B Boundary

文件协议是规划与执行之间的稳定接口
Track A · Agent Control Plane ↑  Track B · Execution Plane ↓
Planning Contract

TARGETS.md + SKILLRUNTIME.md 描述可用 target、policy、adapter 与能力约束。

Session Queue / State

Agent 向 SESSIONS.md 插入 pending session;Watchdog 原子 claim、执行并回写结果与状态。

Evidence & Feedback

LOG.md · LESSONS.md · ENVIRONMENT.md · artifacts/runtime/*

5 · One Turn, End to End

主数据流
1Receive

Channel 或 direct request 进入 Agent。

2Load Context

组合 system、history、runtime state 与当前输入。

3Reason

Provider 返回文本或结构化 tool_calls。

4Act

ToolRegistry 校验并执行;结果返回上下文。

5Persist

保存 turn;必要时 consolidation 或创建 runtime session。

6Deliver

最终 content 通过 MessageBus 回到目标 channel。