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离开ataskId后面,还有continue_task(见下文). - 代表团可携带可选文件
name标签、结果、背景任务报告和续作.
选项 :
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
agents | (string | { name, description? })[] | ——(需要) | 授权代理 字符串是代理名称;对象表允许您覆盖描述. |
toolPrefix | string | 'delegate_to' | 生成的代表团工具名的前缀 。 设定为 '' 以使用裸体代理名称。 非空前缀也会给共享工具命名空格(continue_task 和背景任务工具),因此一个生成调用的两个实例需要不同的前缀. |
maxDelegations | number | 无限制 | 允许每个生成调用的最大副代理代表团。 防止出轨 授权循环. |
historyLength | number | 0 | 转发给子代理作为上下文的最近谈话消息(仅使用/模式)的数量 . |
artifactStrategy | 'inline' | 'session' | 'inline' | inline: 将文物内容列入工具结果 财务报告和审定财务报表 合并为主会话. session:文物只被合并到母会话(工具结果只列出名称). 对 session 与 artifacts 中间软件. |
async | boolean | false | 启用背景代表团: 代表团工具接受 a background 立即返回任务标识的旗帜,以及 check_background_tasks, (中文(简体) ), wait_for_background_tasks,以及 abort_background_tasks 增加了工具。 需要用一个 store。 。 。 . |
maxWaitSeconds | number | 无约束 | 上面绑着一个 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。 。 。 .
选项 :
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
readonly | boolean | false | 当真,只有 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。 。 。 .
实施的战略:
- 安全盖: 硬调出任何单一的超大小工具响应(
maxToolResponseChars,默认值:40万个字符)[TRUNCATED: ...]标记. - 复制: 以短通知取代重复工具回复(
deduplicateToolResponses) (中文(简体) ). - 工具响应截取: 超过字符限制的截断工具响应( T)
toolResponses,保留最新的工具响应信息,并附上[Truncated N characters]标记. - 信件计数封顶: 超过时丢弃旧的非系统消息
maxMessages,保存系统信息并确保对话历史从用户回合开始. - 总结: 使用 LLM(
summarize),可选阈值跳过(skipSummarizationThreshold)和动态超射调整. - 汇算预算回落: 如果调试和工具响应调试不能将上下文带入
maxInputTokens,没有摘要可以取代旧消息,旧的非系统消息会降为preserveRecent。 。 。 . - 无损会话历史: 默认
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);
选项
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
maxInputTokens | number | Infinity | 当令牌计数超过此阈值时触发压缩 . |
preserveRecent | number | 4 | 丢弃旧信件时需要保存的最新非系统消息数量(以及用于 summarize.preserveRecent) (中文(简体) ). |
preserveSystem | boolean | true | 始终保持系统指令完整. |
maxToolResponseChars | number | 400000 | 字符中任何单个工具响应大小的硬盖( 覆盖) output 财务报告和审定财务报表 content ) (中文(简体) ). 设定 <= 0 或者说 Infinity 以禁用. |
deduplicateToolResponses | object | —— 说 | 重复工具呼叫的复制设置 . |
deduplicateToolResponses.matchBy | 'name-and-input' | 'name-only' | 'name-and-input' | 如何匹配重复的工具呼叫 . 'name-and-input' 匹配相同的工具名称和参数. 'name-only' 组全部单独调用一个工具,并丢弃先前的响应,即使调用不同的输入(仅用于返回最新状态的工具,而不论参数如何). |
deduplicateToolResponses.keepRecent | number | 1 | 保留每个重复组的最新答复数目(最少 1) (中文(简体) ). |
deduplicateToolResponses.notice | string | 标准文本 | 自定义工具回复的替换文本 . |
toolResponses | object | —— 说 | 旧工具响应的截断设置 . |
toolResponses.maxChars | number | —— 说 | 每个旧工具响应的最大字符( 覆盖) output 财务报告和审定财务报表 content 一起折叠文本 content 输入 output 当他被截断的时候. |
toolResponses.preserveRecent | number | 2 | 保存未显示的最新工具响应消息数量 . |
summarize | object | —— 说 | LLM 汇总设置( R)model, (中文(简体) ), preserveRecent, (中文(简体) ), prompt) (中文(简体) ). |
summarize.model | ModelArgument | (必须) | 用于归纳的模型(模型参考、模型名称字符串,或 ModelAction) (中文(简体) ). |
summarize.preserveRecent | number | 6 | 保留未归纳(默认为顶级)的最新非系统消息数量 preserveRecent 如果设定,则返回 preserveRecent (c) 缩短预算外历史. |
summarize.prompt | string | 标准提示 | 自定义汇总提示 。 使用 {conversation} 作为发送信件摘要的占位符. |
skipSummarizationThreshold | number | —— 说 | 如果廉价策略至少保存这个分数, 则跳过总和( S)0..1上下文并带来估计值 maxInputTokens。 。 。 . |
maxMessages | number | —— 说 | 最大消息计数目标 。 丢弃旧的非系统消息,确保历史从用户回合开始。 当系统消息和截取通知填补了封顶时,可能会被超越,因为最新的转弯总是保持. |
insertTruncationNotice | boolean | true | 在删除信件时插入咨询通知. |
truncationNotice | string | 标准文本 | 自定义删除信件时使用的通知文本 . |
preserveOriginalMessages | boolean | true | 保存原始未压缩信件 request.messages 财务报告和审定财务报表 response.messages 将压缩状态存储于 message.metadata.contextCompression设置为 false 覆盖 request.messages 已经就位. |