@genkit-ai/middleware

中文文档
0.12.0发布于 2026/11/04Apache-2.0TypeScriptESM + CJS近 30 天下载 2.7万

Genkit 的中间软件

中文使用文档
文档目录10 节
  1. 安装
  2. 可用的中间软件
  3. 1. 中间器件 agents (中文(简体) )
  4. 2. 中相器件( artifacts (中文(简体) )
  5. 3. FileSystem Middle 软件( filesystem (中文(简体) )
  6. 4. 技能中间软件 skills (中文(简体) )
  7. 5. 工具核准中间软件 toolApproval (中文(简体) )
  8. 6. 重试中件( E) retry (中文(简体) )
  9. 7. 后退中软件( fallback (中文(简体) )
  10. 8. 背景压缩中间软件( contextCompression (中文(简体) )

Genkit 中间软件

这个软件包为Genkit JS SDK提供了一批有用的中间软件,以加强模型执行,工具使用和代理工作流程.

用编码代理? 先安装基因组JS技能.

npx skills add genkit-ai/skills --skill developing-genkit-js

它教你的代理人 现任Genkit JS APIs 和普通的gitchas. 其他语言的来源、人工安装和技能: 技能/技能。 。 。 .

安装

npm install @genkit-ai/middleware
# or
pnpm add @genkit-ai/middleware

可用的中间软件

1. 中间器件agents(中文(简体) )

启用子代理授权 。 对于每个已配置的代理,中间软件会注入一个专门的授权工具(例如:. delegate_to_researcher和附件 a <sub-agents> 块到系统时,立即列出可用的代理及其描述。 当模型调用授权工具时,中间软件从注册处解决目标代理,并通过其运行 run() 方法,并返回子剂的反应作为工具结果.

关键行为 :

  • 喷出 每个代理人一个代表团工具名称 <toolPrefix>_<agentName> (默认前缀 : delegate_to) (中文(简体) ).
  • 代理描述是从注册处自动发现的(或可以被推翻的每个代理),并被浮出系统即时.
  • 副代理中断和故障被作为工具响应还原(没有抛出),使管弦乐手能够自我修正. (交互,状态回转和被中断的子剂是未来的特点. 结束的回合没有答案(length, (中文(简体) ), blocked, (中文(简体) ), aborted)被报告为错误,命名原因和代理的最后一个消息,成功时没有最终文本表示,并命名其文物计数.
  • 副代理文物合并为母会话和(或)回回内线,由 artifactStrategy。 。 。 .
  • 与 async: true,各代表团可以按背景进行,以后再收集(见下文).
  • 向副代理人派出代表团 store 离开a taskId 后面,还有 continue_task (见下文).
  • 代表团可携带可选文件 name 标签、结果、背景任务报告和续作.

选项 :

选项类型默认说明
agents(string | { name, description? })[]——(需要)授权代理 字符串是代理名称;对象表允许您覆盖描述.
toolPrefixstring'delegate_to'生成的代表团工具名的前缀 。 设定为 '' 以使用裸体代理名称。 非空前缀也会给共享工具命名空格(continue_task 和背景任务工具),因此一个生成调用的两个实例需要不同的前缀.
maxDelegationsnumber无限制允许每个生成调用的最大副代理代表团。 防止出轨 授权循环.
historyLengthnumber0转发给子代理作为上下文的最近谈话消息(仅使用/模式)的数量 .
artifactStrategy'inline' | 'session''inline'inline: 将文物内容列入工具结果 财务报告和审定财务报表 合并为主会话. session:文物只被合并到母会话(工具结果只列出名称). 对 session 与 artifacts 中间软件.
asyncbooleanfalse启用背景代表团: 代表团工具接受 a background 立即返回任务标识的旗帜,以及 check_background_tasks, (中文(简体) ), wait_for_background_tasks,以及 abort_background_tasks 增加了工具。 需要用一个 store。 。 。 .
maxWaitSecondsnumber无约束上面绑着一个 wait_for_background_tasks 打电话,随便 timeoutSeconds ; 在绑定时, 等待返回当前状态 timedOut 设置.
import { genkit } from 'genkit';
import { agents } from '@genkit-ai/middleware';

const ai = genkit({ ... });

// Define sub-agents
const researcher = ai.defineAgent({
  name: 'researcher',
  model: 'gemini-flash-latest',
  description: 'Searches the web and summarizes findings.',
  system: 'You are a research assistant.',
  tools: [webSearchTool],
});

const coder = ai.defineAgent({
  name: 'coder',
  model: 'gemini-flash-latest',
  system: 'You are an expert programmer.',
});

// Main orchestrator agent delegates to sub-agents.
// This injects `delegate_to_researcher` and `delegate_to_coder` tools.
const orchestrator = ai.defineAgent({
  name: 'orchestrator',
  model: 'gemini-flash-latest',
  system: 'Delegate research to the researcher and coding to the coder.',
  use: [
    agents({ agents: ['researcher', 'coder'] })
  ]
});

您可以自定义工具名前缀并覆盖描述 :

use: [
  agents({
    // Tools become `ask_researcher` and `ask_coder`.
    toolPrefix: 'ask',
    agents: [
      'researcher', // description auto-discovered from the registry
      { name: 'coder', description: 'Writes TypeScript code' }, // explicit override
    ],
    maxDelegations: 5,
    historyLength: 4,
  }),
];

设定 async: true 让管弦乐手在副代理运行时继续工作 每个代表团工具都得到一个 background 返回任务ID而不是等待的旗帜, 三个共享工具给管弦乐手一个控制器, 每一件它可以做的启动的任务: check_background_tasks 无需等待即可读取状态, wait_for_background_tasks 在他们定居之前 abort_background_tasks 阻止那些不再需要结果的人。 这个 子剂 这里需要的是会话存储器:背景工作通过快照跟踪,所以一个子代理没有 store 只能同步授权.

import { InMemorySessionStore } from 'genkit/beta';

// The sub-agent needs its own store to be delegated to in the background.
const researcher = ai.defineAgent({
  name: 'researcher',
  model: googleAI.model('gemini-flash-latest'),
  description: 'Researches a topic and summarizes well-sourced findings.',
  system: 'You are a thorough research assistant.',
  store: new InMemorySessionStore(),
});

const orchestrator = ai.defineAgent({
  name: 'orchestrator',
  model: googleAI.model('gemini-flash-latest'),
  system:
    'Delegate research in the background and post an update while it runs.',
  use: [agents({ agents: ['researcher'], async: true })],
});

指挥员随即发射 { "task": "...", "background": true },在子代理运行时发布更新,然后收集结果。 任务标识( N)<agent>:<snapshotId>) 代表团工具中的骑行结果,因此它们被记录在谈话中,一个重新证实的管弦乐手可以独自从它的历史中收集. 背景任务工具和 continue_task 仅接受本次对话的代表团所携带的任务ID,并继续结果,所以到达模型的文本不能将它们指向另一个对话的任务. wait_for_background_tasks 选择 timeoutSeconds,因此缓慢的任务变成了临时的答案而不是被阻断的转弯; maxWaitSeconds 盖上它,所以一个从未完成的子代理无法将请求打开 . waitFor: "first" 将加盟转换成比赛:工具一旦列出的任务完成就立即返回,而其余的任务则继续运行。 流产可以安全地调用任何任务:一个已经完成的任务被单独留下并报告其结果,因此管弦乐团永远不会因为放弃而失去一个答案. 任务实况报告 aborting 风吹而下 aborted 与它所节省的进展; wait_for_background_tasks 跟着它.

解决问题的代表团留下一个可继续的手柄。 A. 具有下列特性的子代理人的代表团结果或背景任务报告 store 携带一个 taskId,共享 continue_task 工具会花掉它。 失败或中止的任务从上次保存的进度继续:没有 instructions 执着的转弯将按原样重新尝试 instructions 重试被引导。 完成的任务接受子代理自身会话内的后续指令,因此按下永远不重复完成的工作. 与 async: true, (中文(简体) ), continue_task 还要 background: true 并返回同一会话中的新任务ID。 空背景续作是重试的一个例外:一个没有消息的解去会跑不转,所以副代理获得一个简短的"继续从所停止的地方完成任务"的消息取而代之,而其笔录记录下来. 无代理代理代理 store 内部和解,没有 taskId,并再次授权重排;当没有配置的子代理有商店时,模型不显示 continue_task. 中断的任务无法继续。 一个过期的任务(工人已死亡)被用流产来围住,并且从父母的快照中继续,这是在拆卸前最后一次犯下的;一个在做任何事情之前就已经死亡的背景发射没有救赎,工具说要再次授权.

2. 中相器件(artifacts(中文(简体) )

提供与会话文物互动的模型工具并注入 <artifacts> 输入系统时, 提示每个回合 。 有用的独立(例如作为文物制作文件的工作空间-建设者代理人)或与 agents 使用中间软件 artifactStrategy: 'session',因此管弦乐团可以读取由子剂出品的文物.

提供的工具:

  • read_artifact ——从会话中读出被命名的文物并返回其文本内容.
  • write_artifact ——创建或更新被命名的文物(按名称复制). 何时开放 readonly: true。 。 。 .

选项 :

选项类型默认说明
readonlybooleanfalse当真,只有 read_artifact 提供了工具.
import { genkit } from 'genkit';
import { agents, artifacts } from '@genkit-ai/middleware';

const ai = genkit({ ... });

// Standalone: an agent that creates and reads artifacts.
const builder = ai.defineAgent({
  name: 'builder',
  model: 'gemini-flash-latest',
  system: 'You are a code generator. Use write_artifact to create files.',
  use: [artifacts()],
});

// Combined with the agents middleware (session strategy).
const orchestrator = ai.defineAgent({
  name: 'orchestrator',
  model: 'gemini-flash-latest',
  system: 'You coordinate sub-agents and review their work.',
  use: [
    agents({ agents: ['researcher', 'coder'], artifactStrategy: 'session' }),
    artifacts({ readonly: true }), // can read sub-agent artifacts
  ],
});

3. FileSystem Middle 软件(filesystem(中文(简体) )

通过注入标准文件操作工具,给予模型访问本地文件系统的机会(list_files, (中文(简体) ), read_file, (中文(简体) ), write_file, (中文(简体) ), search_and_replace) (中文(简体) ). 所有操作都被安全限制在一个指定的根目录. 注意写入操作需要设置 allowWriteAccess: true 在中间软件配置中.

import { genkit } from 'genkit';
import { filesystem } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: 'gemini-flash-latest',
  prompt: 'Create a hello world node app in the workspace',
  use: [
    filesystem({ rootDirectory: './workspace', allowWriteAccess: true })
  ]
});

4. 技能中间软件skills(中文(简体) )

自动扫描目录 SKILL.md 文件(和它们的YAML前题)并注入系统即时。 它还规定: use_skill 该模型可以用来根据需要检索更具体的技能.

import { genkit } from 'genkit';
import { skills } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  prompt: 'How do I run tests in this repo?',
  use: [
    skills({ skillPaths: ['./skills'] })
  ]
});

5. 工具核准中间软件toolApproval(中文(简体) )

将工具的执行限于核定清单。 如果模型试图调用一个未经批准的工具,它就会扔出一个 ToolInterruptError 允许您在恢复前提示用户手动确认 .

import { genkit, restartTool } from 'genkit';
import { toolApproval } from '@genkit-ai/middleware';

const ai = genkit({ ... });

// 1. Initial attempt
const response = await ai.generate({
  prompt: 'write a file',
  tools: [writeFileTool],
  use: [
    toolApproval({ approved: [] }) // Empty list means call triggers interrupt
  ]
});

if (response.finishReason === 'interrupted') {
  const interrupt = response.interrupts[0];

  // 2. Ask user for approval, then recreate the tool request with approval
  const approvedPart = restartTool(interrupt, { toolApproved: true });

  // 3. Resume execution
  const resumedResponse = await ai.generate({
    messages: response.messages,
    resume: { restart: [approvedPart] },
    use: [
      toolApproval({ approved: [] })
    ]
  });
}

6. 重试中件( E)retry(中文(简体) )

在瞬态错误代码上自动重试失败的模型代号( 如 RESOURCE_EXHAUSTED, (中文(简体) ), UNAVAILABLE)使用与焦躁相伴的指数后退.

import { genkit } from 'genkit';
import { retry } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: googleAI.model('gemini-pro-latest'),
  prompt: 'Heavy reasoning task...',
  use: [
    retry({
      maxRetries: 3,
      initialDelayMs: 1000,
      backoffFactor: 2
    })
  ]
});

7. 后退中软件(fallback(中文(简体) )

如果主模型在一组特定的出错代码上失败,则自动切换到不同的模型. 当一个大型模型超过配额限制时,它有助于回到一个较小/较快的模型.

import { genkit } from 'genkit';
import { fallback } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: googleAI.model('gemini-pro-latest'),
  prompt: 'Try the pro model first...',
  use: [
    fallback({
      models: [googleAI.model('gemini-flash-latest')], // try flash if pro fails
      statuses: ['RESOURCE_EXHAUSTED']
    })
  ]
});

8. 背景压缩中间软件(contextCompression(中文(简体) )

当对话增长过大时会压缩对话上下文,减少代理工作流程和工具循环中的象征性使用和成本. 当估计的令牌或先前的转弯用法超过时会触发压缩 maxInputTokens。 。 。 .

实施的战略:

  1. 安全盖: 硬调出任何单一的超大小工具响应(maxToolResponseChars,默认值:40万个字符) [TRUNCATED: ...] 标记.
  2. 复制: 以短通知取代重复工具回复(deduplicateToolResponses) (中文(简体) ).
  3. 工具响应截取: 超过字符限制的截断工具响应( T)toolResponses,保留最新的工具响应信息,并附上 [Truncated N characters] 标记.
  4. 信件计数封顶: 超过时丢弃旧的非系统消息 maxMessages,保存系统信息并确保对话历史从用户回合开始.
  5. 总结: 使用 LLM(summarize),可选阈值跳过(skipSummarizationThreshold)和动态超射调整.
  6. 汇算预算回落: 如果调试和工具响应调试不能将上下文带入 maxInputTokens,没有摘要可以取代旧消息,旧的非系统消息会降为 preserveRecent。 。 。 .
  7. 无损会话历史: 默认preserveOriginalMessages: true),压缩状态保存在消息元数据中(message.metadata.contextCompression)而不是修改原信息。 模型调用在会话和UI日志保留完整原始消息的同时接收压缩视图. 使用 resolveCompressedHistory(messages) 以提取活动信件.

顺序符 : 组合时 contextCompression 与上下文输入的中间软件(例如 filesystem(), (中文(简体) ), skills(),或 artifacts()),地点 contextCompression 之后 那些中间的软件 use: [...] 因此,它们的被注入指令和工具输出在压缩时被核算.

import { genkit } from 'genkit';
import { contextCompression, resolveCompressedHistory } from '@genkit-ai/middleware';

const ai = genkit({ ... });

const response = await ai.generate({
  model: googleAI.model('gemini-flash-latest'),
  prompt: 'Research and summarize...',
  tools: [searchTool],
  use: [
    contextCompression({
      maxInputTokens: 80000,
      deduplicateToolResponses: { matchBy: 'name-and-input' },
      toolResponses: { maxChars: 2000, preserveRecent: 2 },
      summarize: {
        model: googleAI.model('gemini-flash-lite-latest'),
        preserveRecent: 6,
      },
      skipSummarizationThreshold: 0.25, // Skip LLM summary if cheap strategies save >= 25%
      preserveOriginalMessages: true, // Non-destructive (default)
      maxMessages: 20,
    }),
  ],
});

// Original uncompressed history is preserved in response.messages:
console.log(response.messages.length);

// Resolve the active compressed messages sent to the model:
const activeMessages = resolveCompressedHistory(response.messages);

选项

选项类型默认说明
maxInputTokensnumberInfinity当令牌计数超过此阈值时触发压缩 .
preserveRecentnumber4丢弃旧信件时需要保存的最新非系统消息数量(以及用于 summarize.preserveRecent) (中文(简体) ).
preserveSystembooleantrue始终保持系统指令完整.
maxToolResponseCharsnumber400000字符中任何单个工具响应大小的硬盖( 覆盖) output 财务报告和审定财务报表 content ) (中文(简体) ). 设定 <= 0 或者说 Infinity 以禁用.
deduplicateToolResponsesobject—— 说重复工具呼叫的复制设置 .
deduplicateToolResponses.matchBy'name-and-input' | 'name-only''name-and-input'如何匹配重复的工具呼叫 . 'name-and-input' 匹配相同的工具名称和参数. 'name-only' 组全部单独调用一个工具,并丢弃先前的响应,即使调用不同的输入(仅用于返回最新状态的工具,而不论参数如何).
deduplicateToolResponses.keepRecentnumber1保留每个重复组的最新答复数目(最少 1) (中文(简体) ).
deduplicateToolResponses.noticestring标准文本自定义工具回复的替换文本 .
toolResponsesobject—— 说旧工具响应的截断设置 .
toolResponses.maxCharsnumber—— 说每个旧工具响应的最大字符( 覆盖) output 财务报告和审定财务报表 content 一起折叠文本 content 输入 output 当他被截断的时候.
toolResponses.preserveRecentnumber2保存未显示的最新工具响应消息数量 .
summarizeobject—— 说LLM 汇总设置( R)model, (中文(简体) ), preserveRecent, (中文(简体) ), prompt) (中文(简体) ).
summarize.modelModelArgument(必须)用于归纳的模型(模型参考、模型名称字符串,或 ModelAction) (中文(简体) ).
summarize.preserveRecentnumber6保留未归纳(默认为顶级)的最新非系统消息数量 preserveRecent 如果设定,则返回 preserveRecent (c) 缩短预算外历史.
summarize.promptstring标准提示自定义汇总提示 。 使用 {conversation} 作为发送信件摘要的占位符.
skipSummarizationThresholdnumber—— 说如果廉价策略至少保存这个分数, 则跳过总和( S)0..1上下文并带来估计值 maxInputTokens。 。 。 .
maxMessagesnumber—— 说最大消息计数目标 。 丢弃旧的非系统消息,确保历史从用户回合开始。 当系统消息和截取通知填补了封顶时,可能会被超越,因为最新的转弯总是保持.
insertTruncationNoticebooleantrue在删除信件时插入咨询通知.
truncationNoticestring标准文本自定义删除信件时使用的通知文本 .
preserveOriginalMessagesbooleantrue保存原始未压缩信件 request.messages 财务报告和审定财务报表 response.messages 将压缩状态存储于 message.metadata.contextCompression设置为 false 覆盖 request.messages 已经就位.

版本与发布记录

@genkit-ai/middleware 共发布 20 个版本,首次发布于 2026/04/14;过去 12 个月发布了 20 个版本。

版本发布日期距今
0.12.0latest2026/11/0412 天前
0.11.02026/10/2225 天前
0.11.0-rc.3next2026/10/2225 天前
0.11.0-rc.22026/10/2126 天前
0.11.0-rc.12026/10/091 个月前
0.11.0-rc.02026/10/091 个月前

关于 @genkit-ai/middleware 的常见问题

@genkit-ai/middleware 是什么?

Genkit 的中间软件

如何安装 @genkit-ai/middleware?

在项目目录运行 npm install @genkit-ai/middleware,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:genkit(^1.44.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@genkit-ai/middleware 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genkit-ai/middleware 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@genkit-ai/middleware 可以商用吗?

@genkit-ai/middleware 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@genkit-ai/middleware 的下载量有多少?

根据 npm 官方下载统计,@genkit-ai/middleware 在 2026/10/16 – 2026/11/14 这 30 天内被下载 27,314 次,日均约 910 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genkit-ai/middleware 还在维护吗?

最新版本 0.12.0 发布于 2026/11/04(12 天前);至今共发布 20 个版本,其中过去 12 个月发布了 20 个;首次发布于 2026/04/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。