agently-migration

Agently 迁移

仅当源框架系统已存在时，才使用此技能。不要逐一照搬类名。梳理源系统可观察到的语义，为每项语义指定一个 Agently 归属方，并通过具有代表性的迁移前后证据保留这些语义。

阅读特定源框架的映射

• LangChain 的 agents、models、prompts、structured output、tools、retrieval 或 short-term memory：langchain-to-agently.md。
• LangGraph 的 graphs、state、checkpoints、interrupts、streams 或 subgraphs：langgraph-to-triggerflow.md。
• LlamaIndex 的 agents、loaders、indexes、retrievers、query engines、memory 或 Workflows：llamaindex-to-agently.md。
• CrewAI 的 Agents、Tasks、Crews、Processes、Flows、tools、memory 或 knowledge：crewai-to-agently.md。

Agently 归属方映射

源行为	Agently 归属方
单次模型调用、提示词契约、结构化结果或响应流	agently-request / ModelRequest
可由模型调用的工具、MCP 服务、沙箱、浏览器、数据库或实时客户端	agently-runtime / ActionRuntime + ExecutionResource
对话连续性	Session / SessionMemory
持久化记录、链接、检索、检查点或快照	RecordStore
跨源任务证据和有界读取	TaskContext + ContextSource + ContextReader
稳定的多阶段拓扑、分支、汇合、循环、等待、恢复或运行时事件	agently-triggerflow / TriggerFlow
由模型负责的有界规划、证据收集、验证和重新规划	AgentExecution 中的 AgentTask

不要在单次请求或 Action 外添加 TriggerFlow。不要将真正的工作流压缩成一个提示词。源系统中的“agent”不一定对应 Agently 的 AgentTask，名义上的源“workflow”也不一定是编排；应根据其行为进行分类。

迁移方法

1. 记录源系统的输入/输出、模型调用、工具调用及副作用、状态键及其生命周期、拓扑、并发、重试/错误行为、流事件、检查点/恢复行为、记忆、检索和授权。
2. 将语义工作与确定性工作分开。由模型负责意图判断、相关性判断、规划和综合，并使用 ModelRequest 输出控制；宿主代码负责类型、算术、所提供键的成员资格、授权和副作用。
3. 在选择文件之前，先绘制目标归属方、节点和边的台账。保留外部使用的事件和结果契约，或在边界处引入明确的适配器。
4. 迁移一个有代表性的垂直切片。在大范围替换之前，比较源系统与目标系统的跟踪记录、最终产物、状态转换、中断/恢复行为和失败语义。
5. 在源框架兼容层的最后一个实际使用方完成迁移后，将其移除。仅当兼容适配器负责已发布的外部契约时，才保留它。

必要注意事项

• 明确保留检查点、中断、幂等性、流式处理和子流程语义；节点名称相同并不能证明行为等效。
• 不要将实时资源和机密信息放入序列化的执行状态中。持久化描述符，并通过宿主负责的提供方重建资源。
• 身份关联应由宿主负责。向模型提供一个可选的选择键，并在验证后重新关联规范记录。
• 不要用关键词、正则表达式、快照或硬编码的业务映射，替代源系统的语义路由或评估。
• 如果 Agently 缺少保留源系统某项必要行为所需的协议接缝，应报告能力缺口。不要用提示词或确定性替代方案掩盖它。