AI AgentAgent 框架后端【免费下载链接】julepJulep — durable, composable AI agents. Flows that crash and resume, retry safely, and explain every step.项目地址https://gitcode.com/gh_mirrors/ju/julep点击查看免费下载Julep 的 dotctxdirectory-of-context机制把一次模型调用完整封装进一个目录系统提示词、回复 Schema 与模型参数各自独立成文件再由框架统一加载并降级为可执行的 IR 形态。本文以仓库自带的examples/dotctx/ticket_triage/为样本逐文件讲解如何编写一个只输出 JSON 的结构化工单分类器并深入julep/dotctx.py源码说明其底层加载与降级原理。读完本文你将掌握 dotctx 的目录约定、系统提示词与 JSON Schema 的配合写法以及如何用load_dotctxreasoner_to_flow把它跑成 Pipeline、Feedback 或 Agent 三种执行形态。dotctx 是什么一个目录描述一次模型调用在 Julep 中dotctx是一个描述单次模型调用的目录通常包含三部分一份settings.yaml模型、温度、轮次上限、授予的工具、一份系统提示词文件、以及一份可选的回复 Schema。julep/dotctx.py 的模块 docstring 给出了精确定义Adotctxis a directory describing one model call: asettings.yaml(model, temperature, round bound, granted tools), a system prompt, and an optional reply schema.load_dotctx(dir)会把该目录读成一个按name注册的Reasoner然后框架把 reasoner 的轮次策略round policy降级成对应的执行形态无max_rounds且非 agent → 单次thinkPipeline 形态max_rounds: NN ≥ 1→ 有界iter_up_toFeedback 形态agent: true→ 开放式appAgent 形态。这个目录 → Reasoner → IR 形态的链路正是 dotctx 机制的核心而 ticket_triage 是其中最精简、最容易上手的落地样例。示例包全景三个文件各司其职examples/dotctx/ticket_triage/目录结构如下examples/dotctx/ticket_triage/ ├── settings.yaml # 模型、温度、文件引用、轮次策略 ├── schema.json # 回复 JSON Schema分类结果契约 └── system.md # 系统提示词行为指令这种布局刻意强调上下文永远挂在叶子节点上而不是散落在环境中context lives on the leaf, never ambient系统提示词与回复 Schema 都是本目录下的文件由settings.yaml按文件名引用而非内联在配置里。下面逐一拆解。system.md把行为约束写进一句话任务system.md 全文如下You are a support ticket triage assistant. Read the customers ticket and classify it. Reply with a single JSON object that matches the required schema and nothing else: - category: the single best-fitting category. - priority: how urgently a human should act. - summary: a one-sentence restatement of the customers problem. Do not add any prose outside the JSON object.这份提示词虽短却包含了结构化输出的全部关键设计角色定义首行声明You are a support ticket triage assistant把模型限定在工单分类场景单一任务Read the customers ticket and classify it明确输入是客户工单、输出是分类结论输出契约要求只回复一个符合 Schema 的 JSON 对象别无其他并逐字段给出语义category最匹配的单一分类priority人工介入的紧急程度summary把客户问题复述成一句话格式强约束末尾用Do not add any prose outside the JSON object再次封死任何非 JSON 的输出空间。这份 system.md 与 schema.json 是行为指令 结构约束的分工提示词负责告诉模型做什么Schema 负责告诉模型长什么样两者共同把模型输出收敛到一个可被下游程序直接消费的 JSON。schema.json用枚举把自由文本变成可枚举分类schema.json 定义了回复的 JSON Schema{ type: object, properties: { category: { type: string, enum: [billing, bug, feature_request, account, other] }, priority: { type: string, enum: [low, medium, high, urgent] }, summary: { type: string } }, required: [category, priority, summary] }要点category用enum限制为billing / bug / feature_request / account / other五选一保证下游路由逻辑只会遇到可枚举的分支priority用enum限制为low / medium / high / urgent四级为后续 SLA 或人工队列排序提供离散输入summary是自由文本承载需要保留的人话描述required列出全部三个字段模型必须完整给出缺一即视为 Schema 校验失败。这份 Schema 会在运行时被LlmCaller当作回复校验依据reasoner 携带自己的系统提示词与回复 Schema一次调用就能返回结构化的分类结果结构化输出的语义见 dotctx_triage.py 的模块 docstring。settings.yaml模型、温度与文件引用settings.yaml 是 dotctx 的装配说明name: ticket_triage model: anthropic:claude-haiku-4-5-20251001 temperature: 0.0 system_file: system.md schema_file: schema.json # max_rounds: 3 # uncomment - Feedback shape (bounded refinement loop) # agent: true # uncomment - Agent shape (open-ended controller loop)逐项解读name: ticket_triagereasoner 在注册表中的名字也是load_dotctx之后按名引用的句柄默认会回退为目录名此处显式声明更清晰model: anthropic:claude-haiku-4-5-20251001provider:model格式provider:前缀选择任意支持 any-llm 的厂商。注释里给出了可替换项openai:gpt-4o-mini、groq:llama-3.3-70b-versatile、gemini:gemini-2.5-flash等不带前缀的裸模型名则回退到默认 provideranthropictemperature: 0.0分类任务要求确定性输出温度归零是最佳实践——同样的工单应当得到同样的分类结论system_file: system.md/schema_file: schema.json上下文以文件形式挂载在叶子节点由settings.yaml按名引用注释中的两行开关# max_rounds: 3取消注释会把执行形态从 Pipeline 切换成 Feedback有界精化循环# agent: true取消注释则切换成 Agent开放式控制器循环——同一份目录、同一次模型调用仅通过一行配置就能改变框架为其构建的执行形状。注释原文警告切换形态会在示例输出中看到形状变化。作为对照仓库里另一个更复杂的 issue_dedup settings.yaml 展示了工具型 dotctx 的扩展写法output_retries: 1、max_rounds: 4、require_tool_call: true印证了 ticket_triage 是最小可运行基线。把它跑起来dotctx_triage.py 的完整调用链仓库在 examples/dotctx_triage.py 提供了配套驱动脚本完整演示目录 → Reasoner → 执行形态 → 真实调用的全过程。核心调用链只有几步reasoner load_dotctx(DOTCTX_DIR) # 目录 - Reasoner flow reasoner_to_flow(reasoner) # 轮次策略 - IR 形态 caller make_llm_caller() # any-llm 驱动的 LlmCaller reply await caller(reasoner, TICKET) # 一次调用返回结构化回复脚本内置的测试工单是一封典型的重复扣费 无法登录投诉TICKET ( I was charged twice for my subscription this month and now I cant log in. Please refund the duplicate charge and restore my access. )运行前置条件与命令pip install julep[providers] any-llm-sdk[anthropic] export ANTHROPIC_API_KEYsk-ant-... # 或 settings.yaml 中 model: 所指 provider 的密钥 python examples/dotctx_triage.py脚本的两个值得注意的行为无密钥时是干净的 no-op_key_env从model的provider:前缀推导环境变量名如ANTHROPIC_API_KEY、OPENAI_API_KEY未设置时会打印已加载的 reasoner 与降级后的形状然后跳过真实调用——因此它不会在缺配置时报错方便先看结构再配密钥形状标注逻辑与reasoner_to_flow严格对应_shape_label按sub_contract→is_agent / max_rounds0→max_rounds1→ 默认 的顺序返回Staged / Agent / Feedback / Pipeline与 julep/dotctx.py 中reasoner_to_flow的降级顺序一一镜像。以当前 settings.yaml无max_rounds、无agent: true、无工具运行会看到shape: Pipeline [opthink]、reply keys: [category, priority, summary]取消注释max_rounds: 3则输出变为Feedback [opiter_up_to]。源码级原理load_dotctx 与四种降级形态理解 ticket_triage 的底层机制需要读 julep/dotctx.py 的两个关键函数。load_dotctx目录怎么变成 Reasonerload_dotctxjulep/dotctx.py#L565按以下顺序解析路径文件路径必须.ctx结尾交给dotctx_rich.load_single_file_dotctxmem-mcp 单文件格式需要[dotctx]extra目录中存在 rich 布局标记prompt.j2、messages、schema.pyi、tools.pyi之一见_RICH_MARKERS则交给dotctx_rich.load_rich_dotctx否则读取dir/settings.yaml或settings.yml支持 YAML 里的!? $env.get(...)表达式由julep.dotctx_yglu求值只针对显式传入的env绝不读取进程环境变量最后调用reasoner_from_settings。而reasoner_from_settingsjulep/dotctx.py#L475负责真正装配 reasoner它依据base_dir解析system_file/schema_file的相对路径并读取文件内容、用_model_and_effort规范化模型名normalize_model_slug支持后缀的 reasoning effort、用_as_float/_as_int做带类型校验的数值转换环境变量注入的数字字符串会被强制转换布尔值会被拒绝最终构造并注册Reasoner。这也解释了为什么 system.md 和 schema.json 可以按文件名引用——它们在这条装配链中被完整读入 reasoner 的system与reply_schema字段。Reasoner的字段julep/dotctx.py#L184完整承载了本次模型调用的全部信息model、system、reply_schema、tools、temperature、max_rounds、is_agent、sub_contract以及output_retries、require_tool_call、response_format、prompt_cache、skills等扩展字段。对 ticket_triage 而言最终生效的是system来自 system.md与reply_schema来自 schema.json——LlmCaller运行时直接从 reasoner 读取这两者因此一次调用返回结构化分类。reasoner_to_flow轮次策略如何变成执行形状reasoner_to_flowjulep/dotctx.py#L647是dotctx 的决定性一步——把 reasoner 的轮次策略降级为 IR 节点优先级从高到低子工作流存在sub_contract→sub(...)Staged 形态Temporal 子工作流工具型 reasoner声明了tools→ 始终降到app(...)原生工具循环有界max_rounds优先、否则落到agent_round_cap默认 32的安全上限同时把require_tool_call、output_schema、output_retries带入 app 节点——ticket_triage 没有工具不走此分支开放式 Agentis_agent: true或max_rounds 0→app(...)无界控制器循环有界 Feedbackmax_rounds 1→iter_up_to(max_rounds, think(...))默认 Pipeline其余情况 → 单个think(...)叶子。ticket_triage 的当前配置落在第 5 种单次模型调用即可完成分类。这也正是temperature: 0.0与确定性输出如此契合的原因——没有精化循环时一次调用就必须可靠。值得注意的是注释里预留的# max_rounds: 3正是第 4 种形态的入口取消注释后reasoner 变成有界精化循环分类失败或 Schema 校验不通过时模型最多再被追问两轮总轮次 3适合对输出稳定性要求更高的场景而# agent: true则把同一目录变成一个开放式 Agent 控制器循环模型可以自主多轮迭代代价是更高的执行成本——settings.yaml 的注释原话称其为 the costly, continuation-owning shape, used deliberately见 julep/dotctx.py 模块 docstring即刻意为之的高成本形态。扩展思路从分类器到真实路由基于这份最小示例可以按三条路线扩展接入工具把schema_file换成 rich 布局tools.pyi声明工具reasoner 会自动降到app形态并支持require_tool_call: true参考 issue_dedup settings.yaml有界 4 轮原生工具循环 结构化回复重试 1 次换 provider只改model:一行即可在 anthropic / openai / groq / gemini 之间切换配合_key_env设置对应环境变量默认 provider 为 anthropic对应 julep/execution/llm.py 的DEFAULT_PROVIDER升级执行形态取消注释max_rounds或agent让同一份提示词与 Schema 适配需要多轮精化或自主决策的业务流。无论走哪条路线system.md的编写原则都不变角色 单一任务 字段语义 只输出 JSON的强约束让人写的提示词与程序要的 JSON之间不需要任何翻译层。小结ticket_triage 用 30 行不到的三个文件演示了 Julep dotctx 最核心的工程模式系统提示词system.md定义行为、JSON Schemaschema.json定义结构、settings.yaml 定义模型与执行策略三者分离后由load_dotctx统一装配、reasoner_to_flow按轮次策略自动选择 Pipeline / Feedback / Agent 执行形态。这套一目录一调用的约定让结构化 LLM 任务分类、抽取、路由的提示词与 Schema 可以像代码一样版本化、复用和被下游程序直接消费。赞分享AI AgentAgent 框架后端【免费下载链接】julepJulep — durable, composable AI agents. Flows that crash and resume, retry safely, and explain every step.项目地址https://gitcode.com/gh_mirrors/ju/julep点击查看免费下载相关推荐使用 shadcn-vue 构建响应式数据分析仪表盘Dashboard 示例完整拆解使用 shadcn vue 构建响应式数据分析仪表盘Dashboard 示例完整拆解 本篇技术指南以 shadcn vue 仓库中 deprecated/wwUI组件前端用 JupyterLab 前端包构建单 Notebook 应用examples/notebook 示例逐层拆解用 JupyterLab 前端包构建单 Notebook 应用examples/notebook 示例逐层拆解 本指南以 JupyterLab 仓库中的 ex前端后端数据科学开发工具Keystone 6 Singleton 详解用 isSingleton 构建单实例配置列表附完整实战示例Keystone 6 Singleton 详解用 isSingleton 构建单实例配置列表附完整实战示例 本指南以仓库中的 singleton 示例 h后端上一篇Egg 与 Koa从 async/await 异步模型到洋葱圈中间件的企业级框架演进下一篇Laravel Onboard性能优化高效管理大量用户引导数据的3个策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考