ai4j 基础 Agent 机理（ai4j-agent · run 循环）

ai4j 基础 Agent 机理（ai4j-agent · run 循环） 由 Archify 生成的架构图。 调用方宿主 · CLI · Spring · 任意宿主 · 架构组件 调用方宿主 CLI · Spring · 任意宿主 AgentBuilder / Agents · 装配 · 策略 · 默认值 · ai4j 进程（Java 8 · 无外部框架依赖） · agent AgentBuilder / Agents 装配 · 策略 · 默认值 agent AgentSession · context · memory · run 入口 · ai4j 进程（Java 8 · 无外部框架依赖） · agent AgentSession context · memory · run 入口 agent AgentRuntime · BaseAgentRuntime · ReAct 循环 · ai4j 进程（Java 8 · 无外部框架依赖） · runtime AgentRuntime BaseAgentRuntime · ReAct 循环 runtime AgentModelClient · Chat / Responses 适配 · ai4j 进程（Java 8 · 无外部框架依赖） · model AgentModelClient Chat / Responses 适配 model LLM 提供方 · OpenAI · Doubao · 任意 provider · 架构组件 LLM 提供方 OpenAI · Doubao · 任意 provider ToolExecutor · Registry · 校验 · 并/串行执行 · ai4j 进程（Java 8 · 无外部框架依赖） · tool ToolExecutor · Registry 校验 · 并/串行执行 tool 宿主工具面 · 函数 · MCP · SubAgent · A2A · 架构组件 宿主工具面 函数 · MCP · SubAgent · A2A AgentMemory · 输入/输出/工具结果 · compact · ai4j 进程（Java 8 · 无外部框架依赖） › 状态与记忆（memory 为唯一事实源） · state AgentMemory 输入/输出/工具结果 · compact state AgentEventPublisher · 12 类事件 · AgentListener · ai4j 进程（Java 8 · 无外部框架依赖） · event AgentEventPublisher 12 类事件 · AgentListener event 观测方 · 监听器 · traceExporter · UI · 架构组件 观测方 监听器 · traceExporter · UI SessionStore · EventLog · InMemory / File / JDBC · 链式校验 · ai4j 进程（Java 8 · 无外部框架依赖） › 状态与记忆（memory 为唯一事实源） · state SessionStore · EventLog InMemory / File / JDBC · 链式校验 state Agents.react().build() newSession() run / runStreamResult ① buildPrompt → executeModel ② chat / responses ③ text + tool_calls ④ TOOL_CALL→execute ⑤ 函数 / MCP / subagent ⑦ addInput / outputItems / toolOutput ⑧ STEP/TOOL/HANDOFF 事件 订阅 + traceExporter snapshot / 持久化 ai4j 进程（Java 8 · 无外部框架依赖） 状态与记忆（memory 为唯一事实源）

ReAct 步循环

  • • while step < maxSteps：compact → prompt → model → 有 tool_calls 执行、无则 FINAL_OUTPUT 退出（BaseAgentRuntime.java:194-324）
  • • 步数耗尽返回 CONTINUATION_REQUIRED；工具返回 waitId/operationId 时返回 WAITING 可续跑（:294-323）

工具执行与配对

  • • AgentToolCallSanitizer 先校验；parallelToolCalls=true 且 >1 个调用时并行（并发度受 maxParallelToolCalls 封顶，toolCallTimeoutMillis 超时结果化），否则串行（:243-271）
  • • 每个 tool_use 必须配对 tool_result——宿主中断（AgentControlFlowException）也会补齐占位结果（:272-280）

事件与可观测

  • • 12 类事件：STEP_*、MODEL_*、TOOL_*、HANDOFF_*、TEAM_*、MEMORY_COMPRESS、FINAL_OUTPUT
  • • AgentListener 订阅 + traceExporter 全量 span（RUN/STEP/MODEL/TOOL）