106 篇文档带有标签（标签：concept）

讲解 AgentSession 长程运行态容器：sessionId、独立 memory、event log、snapshot/restore 与 AgentSessionStore，以及它与 memory/compact、Coding Agent/CLI 的边界和生产实现建议。

按系统结构帮你选抽象层：ReAct 是默认起点，CodeAct 换中间表示，Workflow 加显式节点，SubAgent 做受控委派，Teams 引入协作模型；附决策表与常见误判。

ai4j Agent Teams 是带控制面的团队运行时：planner 拆任务、task board 维护依赖与状态、成员注入 team_* 工具协作、synthesizer 汇总最终答案。

AgentPermissionPolicy 在工具执行前做权限判断：ALLOW / DENY / REQUIRE_APPROVAL，可被普通 Agent、Blueprint、CLI 审批界面与后续 Sandbox SPI 复用。

ai4j-agent 总览：它在 Core SDK 之上提供多步推理、工具闭环、memory、workflow、trace 与多 Agent 协作，何时该用 Agent、最小心智模型、runtime 选型与模块边界。

拆解 ai4j-agent 的 Builder、Runtime、ModelClient 三层边界，工具声明与执行双面，memory 作为状态源，以及事件流与 trace 的架构定位。

ai4j 全部 agent 核心概念的导航地图：20 个概念分 7 个能力簇——能力三角(Function Call/MCP/Skill)、记忆与上下文链、执行核心层级、安全边界、可观测性、对外协议、工程化——每簇标出概念间关系，每条一句话定位 + 深链到详细页。

讲清 Flowgram 当前已内置的能力接法（LLM/TOOL/KNOWLEDGE）与只能扩展的能力（Agent/MCP 无内置专属节点），给出 Tool 节点复用工具总线、KNOWLEDGE 复用 RAG 抽象的真实链路。

AI4J 是面向 Java 8+ 的 AI SDK 入口：按需取用的模型调用、工具、RAG、MCP、Spring Boot、Agent、Coding Agent 与 FlowGram building blocks 的总览、推荐起点与仓库模块地图。

介绍 AI4J 音频 service 面：TTS、转录、翻译的统一入口、OpenAI 实现、请求对象校验以及资源与失败语义等接入要点。

从输入心智、provider 覆盖、工具集成、流式语义和多模态投影等维度对比 Chat 与 Responses 两条主线，帮你完成选型。

解析 AI4J Chat 主线的请求对象、自动 tool loop、passThroughToolCalls、SseListener 流式聚合和多模态接入等运行时行为。

深入 ChatMemory 契约：ChatMemoryItem 承载多模态与工具事实、InMemory 与 Jdbc 两种存储、窗口与摘要策略、快照恢复，及投影到 Chat 与 Responses 的共享基座。

讲清 code 与 tui 两种入口如何共用同一套 coding runtime、在哪里分叉（JLINE/legacy/TUI runtime），以及 slash command、/stream、session store 等宿主层行为的真实边界。

CodeActRuntime 用 code/final JSON 协议替代 native tool-calling，把模型生成的可执行代码纳入主循环，由 CodeExecutor 桥接工具并决定收口路径。

讲清 CodeAct 的代码执行边界与 CodeExecutor 扩展点：何时替换默认执行器、如何处理工具桥接，以及生产环境必须补齐的隔离与安全约束。

AI4J Coding Agent 的模块分工、三种宿主入口(CLI/TUI/ACP)与核心概念总览，帮你判断本地代码仓任务是否适合使用 Coding Agent 运行时。

从执行主链拆解 Coding Agent 的分层架构：CodingAgentBuilder 装配点、WorkspaceContext 边界、CodingSession 容器、delegation runtime、审批 decorator 与 host runtime 的职责划分。

讲清 ai4j-coding 的 compact/checkpoint 管线：tool-result microcompact、checkpoint 总结、aggressive compact、fallback 与 auto-compact circuit breaker 的职责划分和调优入口。

总览 ai4j 基座能力线：模型访问、Tool、Skill、MCP、Memory、RAG 与扩展，帮你选择第一条主线并理解与上层模块的关系。

组合流式输出、公网搜索与私域 RAG 的回答链方案，讲解职责分层、引用证据策略与升级判断。

建立 AI4J 扩展面心智：provider/service 走 PlatformType+AiService+Registry 代码主链，HTTP 并发与连接治理走底层 SPI，第三方插件包走 ai4j-extension-api+ServiceLoader+ExtensionRegistry，扩展面并不对称。

按任务目标给出 Flowgram 的五条进入路径，并对比何时选 Flowgram、Agent、Coding Agent 或 MCP，附推荐演进顺序、常见误判与按角色的最短阅读路径。

AI4J FlowGram 是围绕 FlowGram.ai 画布的 Java 后端执行层，把前端画出的工作流图转换成可验证、可运行、可取消、可观测的异步 task。

拆解 Flowgram 前端画布加 AI4J 后端执行层的四层架构：画布、适配、Spring Boot 平台接入与执行引擎，讲清编辑态与执行态 schema 的差异和默认安全姿态。

Flowgram 存在的价值：补上 Agent 给不了的平台化后端结构——工作流契约、任务生命周期、节点执行边界与面向平台的读侧输出，同时讲清当前边界与适用场景。

Flowgram 后端执行真相：FlowGramRuntimeService 把 workflow schema 变成异步任务，节点图变成有状态执行链，节点输出变成 report/result/trace 读侧结构。

McpGateway 作为多服务 MCP 运行时的真实职责：key 规则多租户隔离、tool registry 映射、配置源热更新与动态增删的重建式目录更新策略。

厘清 Coding Agent 里 MCP（把外部能力接进模型工具面）与 ACP（把 coding session 协议化暴露给宿主）两条完全不同的边界，说明它们如何在同一会话里同时生效。

对比 STDIO、SSE、Streamable HTTP 三种 MCP transport 的适用场景、优缺点与默认连接行为，讲清 TransportConfig 统一配置平面与选型责任归属。

按"要解决的问题"把 MCP 拆成三条路线：接一个现成 MCP、治理多个 MCP、把自己的 Java 能力发布成 MCP，给出每条路线的关键对象与阅读顺序。

AI4J 把 MCP 做成覆盖 client、transport、gateway、server 四个平面的能力连接子系统，而不是单一工具接入选项。本页给出整体地图与推荐阅读顺序。

总览 AI4J Core SDK 会话事实层：ChatMemory 记录多轮对话与工具结果，存储与裁剪策略分离，可同时投影为 Chat 与 Responses 输入，支持快照恢复与摘要压缩。

讲解 IMessagesService 原生 Anthropic 协议主线：原生 in/out 零转换、coding-plan 接入、thinking 映射、鉴权与异常处理。

总览模型请求在 AI4J 基座里如何被建模、投影、发送、流式消费和回读，厘清 Chat、Responses、Messages 三条主线的边界。

拆解送进模型的 5 类 prompt 来源（base system prompt、workspace prompt、instructions、session memory、当前 turn）与独立的 tool schemas，帮你定位行为偏差时该按什么顺序排查。

说明 provider profile 作为可切换、可回退的 provider runtime binding 的真实语义，覆盖 activeProfile/effectiveProfile 解析、/provider 与 /model 命令及 session runtime 重绑行为。

讲清 AI4J provider extension：新增模型平台是显式工厂分发扩展，必须同时触碰 PlatformType、Configuration、AiService、DefaultAiServiceRegistry 与 Spring Boot starter，provider 支持矩阵显式维护而非自动发现。

AI4J 的标准 RAG 工程基线方案，串联文档入库、embedding、向量存储与检索链，不绑定特定向量库品牌。

讲清 AI4J 两套评估器的边界：离线 RagEvaluator 用人工标注的相关 id 算 precision/recall/F1/MRR/NDCG 衡量检索质量，在线 RagOnlineEvaluator 在生成回答后用 judge 模型打 faithfulness 分，两者不混用、不替代。

讲解 IRealtimeService 长连接能力面：当前仅支持 OpenAI，统一入口、默认鉴权头、WebSocket 建连主线及回调注意事项。

解析 AI4J Responses 主线的 ResponseRequest 语义、工具解析基座、payload 构建、流式事件聚合与 runtime 友好的运行模型。

拆解 Coding Agent runtime 的 5 层装配链（factory、builder、session、host、MCP runtime），说明每层持有什么状态、决定什么行为以及与相邻层的边界。

建立 AI4J Search & RAG 的源码心智：离线私域路线 IngestionPipeline→VectorStore→Retriever→Reranker→ContextAssembler 与在线公网路线 ChatWithWebSearchEnhance 两条并行边界，以及默认骨架与可选增强的区别。

详解 Skills 发现与加载：扫描工作区与全局根目录、识别 SKILL.md、提取名称描述、按名去重，以及 allowedReadRoots 如何把 skill 目录联动进宿主只读安全边界。

讲清 Skill 正文进入上下文的三条路径（模型自选 read_file、宿主 selectedSkills、宿主 providedContents）、受限执行器的安全模型，以及为什么 AI4J 不提供专用 activate_skill 工具。

用定义、对比表与源码入口区分 AI4J 三大基座概念：Skill 管方法论上下文、Tool 管宿主内执行、MCP 管外部协议接入，澄清投影与归属的常见混淆。

讲清 Skill 在 Coding Agent 里作为文件化工作流知识的真实位置：发现链路、扫描与去重规则、SKILL.md 字段解析，以及 skill 如何同时影响 prompt 与只读路径边界。

总览 AI4J Skills 方法论与上下文治理层：发现 SKILL.md、生成技能目录、按需懒加载正文并将 skill roots 纳入只读边界，厘清 Skill 与 Tool、MCP 的职责分工。

AI4J 场景组合入口总览，按常见业务问题给出方案选型路线、模块组合与回到主线的判断。

讲清 AI4J HTTP stack SPI：通过 ServiceLoader 把 Dispatcher 与 ConnectionPool 注入 starter 构造的统一 OkHttpClient，默认实现靠 META-INF/services 注册，丢失会导致启动失败，仅 starter 装配链自动生效。

剖析 SubAgent 如何把另一个 Agent 包装成受治理工具：StaticSubAgentRegistry 暴露 schema、SubAgentToolExecutor 拦截 handoff，以及 HandoffPolicy 的深度、超时、deny/fallback 与 session 模式语义。

讲清 MCP 工具暴露的安全边界：getAllTools 显式白名单与 getLocalMcpTools 本地枚举是两套语义，调用优先级与暴露面也是两套逻辑，附代码审查清单。

拆解 Coding Agent 的八个内置工具(bash/read_file/write_file/apply_patch/glob/grep/edit/update_agents_md)装配与执行器路由、审批 decorator 拦截位置，以及审批与 workspace 边界为何必须分开理解。

解析 AI4J 工具子系统四层结构：工具声明、请求级白名单、provider schema 投影与本地执行回流，阐明 ToolUtil 作为调度中心的完整执行链与能力边界。

讲解 ai4j-agent 的 trace 与可观测性：traceExporter 才是开关、默认全记录需脱敏截断、事件如何折叠成 span、各 exporter 适用边界，以及与 OTel/Langfuse/FlowGram 的真实关系。

讲清 TUI 的四层定制（config、theme、renderer、runtime）：主题查找顺序、tui.json 的文件级 override 语义、--theme 与 /theme 的区别，以及 useAlternateScreen 对 runtime backend 的影响。

讲解 ai4j-agent 的 Workflow 与 StateGraph：编排层而非 runtime、节点默认只传 outputText、WorkflowContext 是 side channel、StateGraph 边解析优先级与 maxSteps 保险丝语义。

讲清 ai4j 的上下文窗口管理机制：ContextBudget 设预算（maxItems/maxApproxChars/pinnedPrefixItems），DefaultContextProjector 按"保留头部 + 尾部"策略投影，ContextReport 报告丢弃诊断。这是 Compaction 之前的第一道闸，负责"选哪些进窗口"，而 Compaction 负责"怎么压缩"。

回答在 Java 项目里为什么可以考虑 AI4J：面向 Java 8+ 的渐进式 AI SDK 取舍、可按阶段取用的模块分层，以及与 Spring AI、LangChain4j 的差异和适合场景。

回答 ai4j 为什么要单独的 Agent 层：多步执行迟早会逼出 runtime、状态源与工具治理，Agent 把主循环、状态语义、治理边界和可观测性统一下来，而不是平行再造框架。

解释 Coding Agent 在通用 Agent 之上叠加的 5 层本地交付语义（workspace、coding tools、多回合 loop、session/compact/restore、CLI/TUI/ACP 宿主），界定它和普通 Agent 的真实边界。

从能力统一、边界清晰、provider 非对称、向上演进路径等维度说明 AI4J 作为 Java AI 基座的差异点与适用场景。

说明 Coding Agent session runtime 如何把一次本地代码任务做成可持续、可中断、可恢复的工作会话：CodingSession、outer loop、事件账本、进程面与 headless 事件流。

按目标选择进入 AI4J 的主线：默认阅读顺序，以及快速发起模型请求、Spring Boot 接入、Tool/MCP/Agent/Coding Agent/FlowGram 各自的推荐起点与切深时机。

区分 Flowgram runtime 内核节点（START/END/LLM/CONDITION/LOOP）与 starter 注册的 executor 节点（HTTP/VARIABLE/CODE/TOOL/KNOWLEDGE），讲清共享值解析模型与各节点输入输出。

剖析最小但完整的 ReAct Agent 运行闭环：AgentBuilder 默认装配、ReActRuntime 与 BaseAgentRuntime 的关系、工具声明与执行边界，以及空工具 Agent 何时成立。

讲清 AI4J 基座层 Function Calling 执行链：用注解声明工具、ToolUtil 按白名单生成 provider tool schema、请求挂载与 tool call 回流，及其与 MCP、Agent 的边界。

讲清 AI4J 默认 RecursiveTextChunker 的真实行为与边界：它只填充 documentId/content/chunkIndex，不自动生成 chunkId、页码或章节元数据，以及 chunk 边界稳定性如何决定后续检索去重与引用质量。

把一条 workflow 从编辑态到执行态的完整管线拆成六个 stage：JSON 导出、归一化、runtime plugin 调用编排、controller/facade/runtime 分层执行与读侧投影。

Flowgram.ai 画布与 AI4J Java 后端执行层对齐的三个契约：workflow schema、task lifecycle、report/result/trace 读侧，讲清 schema 归一化、轮询与权限接入点。

用包簇心智模型梳理 ai4j 模块源码分层，指明主能力面与支撑层包的职责，并给出读源码的推荐顺序。

讲清 AI4J MCP 协议面：服务端支持 tools/resources/prompts 三类 capability 与 list_changed 通知，legacy profile 需 initialize 握手而现代 Streamable HTTP 无状态，transport 会影响 capability 边界。

讲清 AI4J VectorStore 统一契约如何收口 Pinecone/Qdrant/Milvus/PgVector/Redis 五个后端：dataset 是硬边界，capabilities() 显式暴露 returnStoredVector/metadataLookup 差异，统一调用但不抹平存储现实。

说明图文输入如何作为会话事实经 ChatMemoryItem 投影到 Chat 与 Responses 两条主线，区分模型原生输入与外部视觉工具。

AI4J 安全边界由密钥、网络、Tool、MCP、RAG、Agent、Coding Agent 和 FlowGram 多层组成。接入前明确：哪些能力能被模型看见、调用、回写到用户或日志。密钥不入仓、Tool 最小暴露、本地边界约束。

AI4J 与 Spring AI、LangChain4j、AgentScope Java、Pi Agent 等方案的定位对比。不做拉踩，而是讲清 AI4J 专注 Java 8+ 多模块 SDK、渐进接入能力和更轻的按需取用路径，帮你判断何时选 AI4J。

讲清 AI4J embedding 层的薄接口与强约束：它统一 provider 调用但只支持 OPENAI/OLLAMA，ingest 与 query 必须使用同一模型，混用不会被框架自动阻止，是索引级协议的一部分。

拆解 ai4j-agent 工具体系：AgentToolRegistry 只管暴露面、ToolExecutor 管执行与权限边界，runtime 如何归一化、校验、执行工具并把结果回灌 memory，以及审批拦截该放哪层。

拆解 AI4J 工具执行模型四段链：发现注册、请求级白名单、provider 返回 tool call、本地调用路由与执行，讲清 built-in/Function/MCP 优先级与结果文本化回流。

讲清 AI4J 工具安全两层防线：请求级 functions/mcpServices 白名单与 BuiltInToolContext 工作区读写边界，剖析 bash 等高风险 built-in 与待补的审批沙箱治理。

区分 AI4J 的 citation 与 trace 两条链：citation 由 DefaultRagContextAssembler 基于最终命中生成，trace 记录检索与 rerank 中间状态，generation usage 与 judge 分数需上层显式回填。

把 ai4j 让 agent 与 SDK 做更多的四条扩展线收进一个入口：插件包贡献合约（discover/enable/allow/expose）、按需加载的 Skill 方法论、插件 Prompt 资源、新增 LLM 后端的 provider/model/service 扩展，标清各自入口与安全边界。

讲清 AI4J plugin package：第三方 jar + ServiceLoader 发现 + ExtensionRegistry 三段式门禁 discover/enable/exposeTool，区分 tool/command/Skill/Prompt/Guardrail 资源进入方式，默认不自动暴露工具给模型。

讲清 AI4J IngestionPipeline 这条 RAG 入库编排层：source 加载、文本清洗、chunk、metadata 富化、批量 embedding 与 vector upsert 如何串成统一流水线，以及 documentId/contentHash 稳定性与可插拔扩展位点。

厘清 AiService 单实例入口与 AiServiceRegistry 多实例注册表的真实职责、配置回退和扩展边界。

讲清 AI4J service extension：新增顶层能力契约会扩大整个 SDK 公共 API 面，必须同步 AiService、AiServiceRegistry 与 FreeAiService 兼容入口，AiServiceFactory 不是 service 插件总线，仅在现有契约无法承载时才值得新增。

用一张四层图建立 AI4J 的整体心智模型：入门、Core SDK 基座、上层模块（Spring Boot/Agent/Coding Agent/FlowGram）与实战方案，并厘清 Function Call、Skill、MCP 三个最易混淆的概念边界。

把 AI4J 仓库的 Maven 模块主线、依赖方向和代码定位入口落到真实工程上，帮助你在读源码或评估模块边界时找到正确落点。

讲清 AI4J RagQueryPlanner 检索前处理层：它在 Retriever 之前产出 rewrite/multi-query/HyDE/step-back 检索计划，多 variant 用 RRF 融合，rerank 与上下文组装仍回原 query，planner 异常自动回退。

对比 ChatModelClient 与 ResponsesModelClient：systemPrompt/instructions 的协议映射、顶层字段下推差异、流式信号与 memoryItems 形状，帮你为 Agent 选对模型协议路径。

讲清 AI4J model extension：在不新增 PlatformType 的前提下，把新模型能力吸收进现有 provider 与现有契约，主战场是请求对象和 provider 适配层，强调把 provider 差异收敛在 provider service 内部而非泄漏到业务层。

高证据要求法律助手的 RAG 方案，强调元数据治理、证据引用与人工复核，区别于普通聊天加长 prompt。

深入 @FunctionCall、@FunctionRequest、@FunctionParameter 三注解如何把 Java 类型绑定为 provider tool schema，详解 ToolUtil 生成链、类型映射规则与真实约束。

讲解 Chat 与 Responses 两条流式主线的聚合模型：SseListener 与 ResponseSseListener 维护的状态、tool call 聚合与终止条件差异。

讲清 AI4J HybridRetriever 的本质是多检索器结果融合器而非固定 Dense+BM25 套餐：默认 RRF 按排名融合，用稳定 key 去重，融合后 score 语义变化以及无 getHybridRagService 便利入口的设计原因。

讲清 AI4J 里“第一次工具调用”的真正含义：本地 Function Call 的最短示例，以及 Function Call、Skill、MCP 为什么必须分开理解，并给出下一步专题树。

厘清 ai4j-agent 里 systemPrompt 与 instructions 的源码语义：两者都是 AgentContext 配置、每步重复进入模型，但在 Chat 与 Responses 路径映射不同，CodeAct 下更需分层。

如何把 ai4j 嵌进你的应用：把 AiService 编程入口、ACP 宿主协议、trace/replay 可观测、CLI/TUI 嵌入与 Spring Boot 自动装配五条散落的集成主线收进一个落地页，每条给一句定位和深链。

讲清 AI4J Online Search 的真实定位：它不是统一检索框架，而是包裹 IChatService 的联网搜索增强层，用最后一条消息做 query 调 SearXNG，把结果 JSON 直接拼进用户 prompt，并会原地改写请求。

厘清 ChatMemory、Tool、MCP 三层职责边界：memory 只保存会话事实，工具审批与副作用治理归 runtime；说明为何不该把执行控制耦合进 memory 抽象。

拆解 ai4j-agent 的 AgentMemory 状态模型：用户输入、模型输出与工具输出如何统一回灌下一轮 prompt，以及 InMemoryAgentMemory、JdbcAgentMemory 的写入、压缩与 session 隔离真实语义。

介绍 ai4j-agent 的 ContextProjector 与 CompactPolicy：如何把 memory snapshot 投影成本轮 prompt、用结构化 CompactResult 压缩长程上下文，并让压缩过程可诊断、可恢复。

统一讲解请求构造与返回读取约定，区分本地注册字段与 provider payload 字段、extraBody 角色及常见接入误区。

拆解 ReActRuntime、CodeActRuntime、DeepResearchRuntime 三种 runtime：它们共享 BaseAgentRuntime 主循环，差异在于模型输出的中间表示，以及何时换中间表示、何时自定义 runtime。

讲清 AI4J rerank 层：它夹在 retrieval 与 context assembly 之间做排序修正，默认 NoopReranker 不远程重排，ModelReranker 靠 provider 返回 index 映射，finalTopK 在 rerank 之后裁剪，returnDocuments 可能改写命中内容。