@agnt-sdk/ studio (英语)

V2 显式 LLM 执行器 动画 提示,在本地显示拖放/运行代理和从平台拖取任务/聊天运行细节时使用 CLI .

安装

npm install @agnt-sdk/studio

对于CLI:

npm install -g @agnt-sdk/studio
agnt --help

配置

创建 agnt.config.js 在您的项目根。 见 @agnt-sdk/config 详细参考.

// agnt.config.js
export default {
  privateKey: `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----`,
  kid: 'your-key-id',
  apiUrl: 'https://api.agnt.ai',
  serviceKey: '',
  outputDir: './agnt/prompts',
  apiMode: true, // false = load from local files (after agnt pull)
};

国 际

agnt pull

从 Agnt 平台提取一个或所有快速的列表到您的本地 outputDir数字 :

# Pull a specific prompt
agnt pull myaccount/flight-planner

# Pull all public prompts for an account
agnt pull myaccount/*

声明保存到 outputDir/accountSlug/promptSlug.json设置 apiMode: false 在您的配置中执行这些本地文件, 而不是在每次运行时从 API 获取 .

agnt init

脚手架a agnt.config.js 在当前目录中:

agnt init

agnt configure 编号 : agnt run ——从 DB 拖取任务/聊天运行细节

用于调试代理在任务或聊天中实际做的事情——每一次工具呼叫和结果,而不只是消息记录——而不通入数据库或刮取日志. 使用标准 /tasks 财务报告和审定财务报表 /chats API,所以它需要一个真正的 API 密钥,而不是项目级别 agnt.config.js。 。 。 .

设置 — 薄荷 API 密钥, 然后保存为命名配置文件 (AWS- CLI 样式;配置文件运行于 ~/.agnt/credentials,独立于任何项目):

agnt configure --profile production --api-url https://api.agnt.ai --api-key ak_live_...
agnt configure --profile staging --api-url https://staging-api.agnt.ai --api-key ak_live_...

每个命令选择配置文件 --profile,或设置 AGNT_PROFILE 在你的壳里。 默认名为配置文件 default。 。 。 .

# List recent tasks/chats
agnt run list --since 24h --profile production
agnt run list --status active --profile production

# Full activity timeline for one task/chat (tool calls + results, paginates
# through everything automatically — capped at 1000 activities by default)
agnt run task <taskId> --profile production
agnt run chat <chatId> --profile production

# No cap — fetch every activity, however many pages that takes
agnt run task <taskId> --all --profile production

# Raw JSON for piping into other tools (e.g. `jq`, or Claude Code via Bash)
agnt run task <taskId> --json --profile production

账户级 API 密钥( 一个创建时未指定) userId在其账户中看到一切。 一个用户扫描的密钥只看到一个用户自己的任务/聊天.

agnt eval 阅读运行审查评价

Run Review的分数完成后,从用户的角度(他们是否得到了他们要求的,感觉如何),也是Agnt-console的评价页面所显示的. agnt eval 将相同的三个视图放入终端,所以一个代理可以从"如何运行"到一个评估到它背后的运行. 配置设置与 agnt run不过 需要一个账户级 API 密钥 (一个创建时没有用户,而一个Org):一个评价是交叉用户视图,因此一个与用户或一个Org绑定的密钥被拒绝. 一个密钥的瞄准镜没有检查:在任何路线上都没有强制执行,每个密钥控制台薄荷会携带一些.

# How runs are doing: averages, outcome and ending buckets, and the by-task-type table
agnt eval summary --days 30

# The evaluations, worst first. Filter to a task type from the table above,
# an outcome, how the user ended, or a score range
agnt eval list --task-class schedule_meeting_multi_participant
agnt eval list --max-score 2 --outcome failed --sort newest
agnt eval list --unclassified
agnt eval list --page 2

# One evaluation in full
agnt eval get <reviewId>

# Raw JSON for piping into other tools
agnt eval list --max-score 2 --json

每个评论都点出任务 和聊天,全部. agnt eval get 打印随行的命令 : agnt run task <taskId> 工具召唤时间表, agnt run chat <chatId> 还有LangSmith的追踪查询.

agnt workflow - 推、拉和列出工作流程技能

保持工作流程(技能: kind: "workflow"作为JSON文件 使用与控制台相同的路线(POST /skills, (中文(简体) ), PATCH /skills/:id),因此触发器被加盖了印章并安排了工作流程;它不使用显示的导入路径.

agnt workflow list [--json]
agnt workflow pull daily-digest -o daily-digest.json    # omit -o to print to stdout
agnt workflow push daily-digest.json                    # create; fails if the name exists
agnt workflow push daily-digest.json --update           # update in place (name cannot change)
# all accept --profile <name>

示例定义kind 默认为 workflow· ; name 是一个小写流:

{
  "name": "daily-digest",
  "title": "Daily digest",
  "description": "Summarise the day each morning",
  "scheduleType": "trigger-based",
  "workflowStatus": "active",
  "hidden": false,
  "triggers": [{ "on": "cron", "schedule": "0 9 * * *" }]
}

服务器管理字段( E)id, (中文(简体) ), origin, (中文(简体) ), tier, (中文(简体) ), createdBy, (中文(简体) ), account, (中文(简体) ), followers, (中文(简体) ), billedTo, (中文(简体) ), triggerSources时间戳,运行计数器) 被扔出拉出,被忽略在推出.

已知的限度(已核实,2026-09-29)

• list, (中文(简体) ), pull 并创造 -push 用 API 键工作。 一个创建的工作流程回合 pull (服务器添加触发器) _id, (中文(简体) ), intelligenceTier 财务报告和审定财务报表 subTriggers) (中文(简体) ).
• push --update 被API拒绝 403 You can only edit skills you own 在工作流程上,刚刚创建的同一键。 在后端接受之前,更改控制台中已有的工作流程.
• userFacingPlan 在更新时被接受,但在创建时被放弃(它从创建的计划中缺失),所以它会回来 null 第一次之后 push。 。 。 .
• user.* 系统触发器只能由控制台创建.
• 用户扫描的密钥无法在 list; 使用账户级密钥.
• workflowStatus 以创造为荣誉 "paused" 回来 "disabled" 而不为所定也. status, (中文(简体) ), followers, (中文(简体) ), silentOnNoOp, (中文(简体) ), processingBufferMs 财务报告和审定财务报表 skillCollection 然而,在创建时被忽略了(在不违约时会打印出警告).
• list 每个安装时显示一行, 因此安装了不止一次的工作流程可以出现两次; 这来自 GET /skills,不是CLI(英语:CLI).

程序使用

AgntExecutor

通过地址执行提示( E)accountSlug/promptSlug) (中文(简体) ). 从 API 或本地文件获取列表,取决于 apiMode。 。 。 .

import { AgntExecutor } from '@agnt-sdk/studio';

const executor = await AgntExecutor.create({
  credentials: {
    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
  },
});

const result = await executor.execute(
  'myaccount/flight-planner',
  { destination: 'New York', departDate: '2025-06-15' },
  {
    // optional tool implementations
    get_flights: {
      execute: async (args) => { /* ... */ }
    }
  }
);

console.log(result.result);   // final output
console.log(result.messages); // full message history
console.log(result.usage);    // token usage + cost

createExecutor

下级工厂——取一V2 PromptManifestV2 直接对象 :

import { createExecutor } from '@agnt-sdk/studio';

const executor = await createExecutor({
  manifest,
  credentials: {
    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
  },
  variables: { key: 'value' },
  toolRouter: { /* tool implementations */ },
});

const result = await executor.execute();

带有稳定前缀的系统提示

当一个系统提示中有一个对调相同的部分和每个调用上变化的部分(一个时钟,直播) ,将系统消息作为文本部分发送,并标记最后一个稳定部分 cacheBoundary: true数字 :

{ role: 'system', content: [
  { type: 'text', text: stablePrompt, cacheBoundary: true },
  { type: 'text', text: perCallPrompt },
] }

Anthropic 每部分获得一个系统块,其缓存断点位于被标记的部分,所以读取了稳定的前缀 从快速缓存 通过呼叫。 OpenAI, Azure, OpenAI 兼容主机,双子座和贝德罗克获得部件加一 空白行(与一串同为正文),稳定前缀为先行,即自动前缀活塞需要的. 字符串 系统消息不变. SYSTEM_CACHE_BOUNDARY_SUPPORT (出口, 1)告诉一个呼叫者这个版本理解 这些部分.

OpenAI / Azure GPT-5.6+ 缓存断点

GPT-5.6和后来的家族只在断点缓存. 在回复路径( OpenAI 和 Azure Foundry v1) 中 执行器发送 prompt_cache_options: { mode: 'explicit' } 时间和地点 prompt_cache_breakpoint 打开:标记 cacheBoundary 系统部分(或整个系统消息),请求中最新的稳定项目,以及同一位置 在每一个早期的助手转身之前(在先前的请求中,这个可以读取). 跟踪信件 标记 releaseAfterRead (倒转音符) 在尾部断点后停留. A 类 function_call_output 携带一个是 作为附件 input_text 阵列. disableCache 只保留系统断点。 旧的模型都得不到参数. 最多出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出 服务只通过最新的四分 因此,系统必须停留在它们中间:一个新的觉醒,它的早期对话不同,只能与之相匹配 继续转弯与上个尾部相匹配。 空白项目是 从未标记; 没有中断点的请求没有发送 prompt_cache_options (隐也. metadata.prompt_cache_breakpoints: false 关掉这个模型。 请求中带断点的400是 在没有他们的情况下,再试一次;如果试验成功(提供部署,API无中断点),则不进行试验 给那个模特15分钟 在警告时登入 缺少目录写速率帐单缓存按输入速率写出. PROMPT_CACHE_BREAKPOINT_SUPPORT (出口, 1)告诉一个呼叫者这个版本将其放置. 缓存写入报告为 cache_creation_input_tokens。 。 。 .

快速缓冲每个提供者

promptCacheCapability(provider, model) (出口,与 takesPromptCacheKey 财务报告和审定财务报表 PROMPT_CACHE_CAPABILITIES_SUPPORT(中文(简体) ) 说一个提供者如何缓存, 所以一个呼叫者从来没有通过模型 id来决定:

metadata.prompt_cache_breakpoints: false 从未发送给任何提供者。 在Anthropic上,它降低了前一个尾部标记 在Bedrock上,它将每个检查站都停放;在OpenAI/Azure上,它关闭了GPT-5.6+断点.

失败的结果

失败 execute() 返回时 { ok: false, error, failure }。 。 。 . error 是信件串(未更改); failure 结构化,来源于提供者的打出错误(HTTP状态,错误类,机器代码)和 从来没有从消息文本,所以它是语言独立的:

if (!result.ok) {
  const { kind, status, provider, model, fallbackTrail, retryable } = result.failure!;
  // kind: 'quota' | 'timeout' | 'aborted' | 'unsupported' | 'auth' | 'provider_error' | 'bad_request' | 'unknown'
  // fallbackTrail: [{ provider, model, kind, status }] — every model-chain member tried, in order
}

• quota: HTTP 429,或配额/税率限制类别/代码(OpenAI/Azure创始公司) rate_limit_exceeded, (中文(简体) ), insufficient_quota, (中文(简体) ), RateLimitReached; 安东尼 rate_limit_error; 纪美 exceeded_current_quota_error; 谷歌 RESOURCE_EXHAUSTED· ; 贝德洛克 ThrottlingException。在暂停前检查配额. 配额可以是永久性的数字 : insufficient_quota 财务报告和审定财务报表 exceeded_current_quota_error 为: quota 与 retryable: false。 。 。 .
• timeout: 空闲/ 备份流中止, HTTP 408, 超时出错类或代码( 节点代码读取) .cause, (中文(简体) ), 这样 fetch failed 类型错误分类). 打电话的自己 deadlineAt 路过就是个 timeout 与 retryable: false。 。 。 . aborted:打电话者停止了跑道.

慢模型和呼叫者的期限

60 s( idle) 无令牌的流将转向下一个模式 spec.models (按 fallbackOrder页:1 仍然跑在10分钟的绝对后台 当呼叫者通过时 deadlineAt (没有后援) 结束转弯,所以长链不能乘以它). 当一个可达到的模型出现后,一个被停滞的模型会留在它的FIRST闲置处 摊位; 只有最后的摊位在原地。 过 deadlineAt 执行者配置中( 或每个调用中) InvokeOptions当呼叫者有坚硬的墙壁(工人的行刑时间)时: 更小的后台和剩下的时间,一旦它通过,就不再尝试或倒置模型被尝试. 贝德洛克, 不流,在截止日期也中止其请求(在节点18至20.2上,没有) AbortSignal.any, (中文(简体) ), Bedrock不能将最后期限与呼叫者的停止信号结合起来,也不对请求执行最后期限 执行器一旦通过,仍然没有进一步尝试模型). 打电话的人 停止( e)cancel() 编号 : signal) 保持终端状态并给其他模式提供粉丝.

• unsupported: HTTP 501/405/415或一 unsupported_*编号 :DeploymentNotFound 样式代码; 也是曾为 因为没有 executorFactory 可以建造它.
• auth: 401/403, (中文(简体) ), AuthenticationError编号 :PermissionDeniedError, AccessDenied 代码(一个被撤销的密钥不坏请求).
• provider_error:5xx(包括529个超载),网络故障. TLS/ 证书错误保留 unknown。 。 。 .
• bad_request: 任何其他4xx. (中文(简体) ). 没有密码的402是 bad_request; 402 的配额代码为 quota。 。 。 .
• unknown: 没有输入信号, 每一个没有通过模型链的错误 (工具处理器) 重排错误, 可变验证错误 : 工具错误 .status 连LM供应商都不说.

kind 不是一个重试指令. 使用 retryable (真为5xx/529,即时429,超时;假为永久) 配额、 认证、 不支持、 坏 请求; 缺席 unknown) (中文(简体) ).

SDK 故意不匹配消息文本 。 临时故障 提供者只报告传言(例如 Azure的"没有部署准备",一个没有代码的HTTP 400是 bad_request需要抓住它的消费者必须这样做 它自己的文本匹配.

因为一个429被供应商客户重审, streamWithRetry接下来是429个风暴 经常以 timeout 谁 fallbackTrail 仅显示 quota 条目。 检查线索,不只是 kind。 。 。 .

成功的结果 fallbackTrail (相同的条目形状)只有当至少一个较早的成员失败时,所以 配额是显而易见的。 不丢出返回的取消 ok: false 没有 failure。 。 。 .

日志

过 logLevel 以控制输出动词 :

const executor = await createExecutor({
  manifest,
  credentials,
  logLevel: 'debug',  // 'debug' | 'info' | 'silent'  (default: 'info')
});

• 'info' 生命周期事件(模型选择、工具呼叫)
• 'debug' 向LLM发送全部请求/答复有效载荷
• 'silent' ——无产出

V2 示意图格式

{
  "$schema": "https://agnt.ai/schemas/manifest/v2.json",
  "kind": "PromptManifest",
  "apiVersion": "v2",
  "metadata": {
    "name": "flight-planner",
    "title": "Flight Planner",
    "description": "Books flights based on user preferences."
  },
  "spec": {
    "routingStrategy": "fallback",
    "enableToolCalls": true,
    "variables": [],
    "models": [
      { "provider": "anthropic", "model": "claude-sonnet-4-5" }
    ],
    "tools": [],
    "files": [],
    "dependencies": []
  }
}

支助提供者

许可证

麻省理工学院

原生推理重放和观察

提供者 invoke() 结果可以携带 message.nativeState 与生产 提供商、模型、电线格式和完整订购的本地输出项目。 持久性 当恢复未完成的工具交换时,此信封不变。 兼容 适配器重放一次, 而不是重建第二个助手副本 文本和电话。 OpenAI和Azure反应保存ID、相、摘要和 加密内容不透明; 双子座保留工具和最后回答上签名的部分 turn; Anthropic 保存完整的内容块顺序. 兼容性是 保守准确的提供者/模型/格式。 它不承诺跨型号或 跨供应商可移植性。 老年人 rawParts 缩写仍然可以识别 Athropic/Gemini形状;一个不相容的信封从不回落到这些部分.

message.reasoningSummary 仅包含支持的公开摘要文本,单独 从答案。 汇总收藏仍然通过提供者的设置选择使用 (单位:千美元)reasoning.summary, (中文(简体) ), thinking.display,或 includeThoughts) (中文(简体) ). 没有设置曝光 一个通用的原始推理记录 不透明状态和遗留部分 不包括SDK痕迹,以及 llm_output 钩载荷. 追踪报告状态 存在、公开摘要、实际建造 reasoningConfig 设置和 提供者报告的推理数。 缺失的计数未知;0保留. 计数是包容性产出使用的细节,不是额外的计费桶.

双子座通用 reasoning_effort 绘图仅适用于支持的模型 家庭事务 生成内容双子座 3 用途支持 thinkingLevel 数值; 双子座2.5采用1024/8192/16384的SDK预算选择,用于低/中/高 供应商的范围. none 仅在 2.5 Flash 上将映射为预算零的地图,其中可禁用 思维得到支持。 明确本地预算或水平获胜。 不支持的等级, 未知的模型和专用的图像/音频/活性模型保持其本土的默认.

人体手动思维会降低不兼容的强制工具选择,温度, 和上 k;上-p仅在0.95-1范围内保留。 支持的适应模型保留 强制工具选择,但拒绝所有强制的模型除外. 导出 anthropicSupportsForcedTools(model, thinking) 上游使用实际请求 思维模式。 请求 thinking.display 财务报告和审定财务报表 thinking.block_binding 幸存下来 努力翻译.

新的Athropic模型还将思维与系统即时、工具定义和 对话前缀。 仅凭精确模型出处并不能证明重播 块在编辑前缀后有效。 适配器重试所记录的确切 前缀绑定 400 次与提供者的 drop_block 政策与政策 thinking-binding-controls-2026-08-01 当适应性思维是 兼容。 这是一种退化的恢复:低劣的推理可以被 供养. 它不会恢复通过前缀编辑丢失的连续性 。 通用或 被篡改的签名错误和不支持的思维模式不会以这种方式被重审. 一个明确的呼叫者 error 或者说 drop_block 政策优先。 一个成功的 恢复记录,追踪到 prefixBindingRecovery,并保留在 兼容 nativeState.replayPolicy 检查站恢复和执行人 例如,随后的请求. inputTransformations 报告提供者的 不透明内容的块路径/类型/理由.

要观察前缀不匹配报告而不选择新策略, 设置 metadata.anthropic_beta 改为 ['thinking-binding-controls-2026-08-01']。这些地图 给标题,而独自让提供者现有的不匹配行为完好无损. 现有β值在恢复期间被合并. 保留逻辑 压缩和正在变化的懒惰工具需要保留有效的前缀或使用 (a) 供应商的服务器侧上下文编辑 由 SDK 重放信封执行 .

资料来源: OpenAI 推理, (中文(简体) ), 人类思想, (中文(简体) ), 人类保留的思想, (中文(简体) ), 双子生成内容思维, (中文(简体) ), 双子座思想签名。 。 。 .

适配器调和 Canonic 工具呼叫ID 修复、调用清除/添加和 带有存储本地输出的可见内容编辑。 未编辑项目保留其精确 顺序、ID、相位、参数拼写和不透明值。 删除函数调用 不被重放, 修复的ID 匹配结果, 并添加的呼叫一次出现 . 这种编辑仍然可以降低提供者的连续性. 对于一个相容的双子座本土 转起,如果一个签名函数调用参数改变,或者一个已删除的签名调用 留下一个没有签名的幸存者, 只有受影响的重建电话使用双子座 输入历史 skip_thought_signature_validator 哨兵们 追踪 报告 inputTransformations 与 type: imported_history 财务报告和审定财务报表 reason: canonical_tool_history_changed; 不变的转弯使用其原始 签名。 可识别的遗留双子座部分使用相同的调节. 双子座 先前存在的函数名ID不是唯一的路由 ID; 适配器匹配 在对重复名称进行配对之前, 参数从不转移另一个调用 给幸存的兄弟签名 跨型号/供应商倒入持续 签名工具交换仍然需要重新启动或明确导入历史 . 此发行中的自动Anthropic 前缀恢复被绑定为适应/默认 相容模式; 明确的手动模式和 tools模式之间没有自动回收.

这一变化是0.0.65的发行候选. 先发布审查过的SDK软件包, 然后把后端的 确切的依赖性和锁文件更新到那个公布的文物上, 建立/部署它,并验证真正的提供者痕迹。 一个本地包装的柏油球 审核/整合证明,不建立已部署或已公布的版本.

原生现场通话痕迹

配备了账户级开发者密钥,并部署了电话追踪后端/出入口:

agnt run calls --task <taskId> --json
agnt run calls --chat <chatId>
agnt run call <Twilio-CallSid-or-session-UUID> --json
agnt run call <callId> --langsmith

追踪将后端的扬声器/推理者快照与网关分开 实际外出设置和以后的事件,加上最后记录、使用和结束. 外出设置可以证明网关写到它的套接字上;它不能证明 供应商应用了它。 A 类 running 追踪可能意味着结局从未被抓住. 捕捉有限度,旗子有遗漏/标记。 私密电话不接 内容和保留散列。 记录在14天后过期;旧电话无法恢复 及时回溯文本。 LangSmith 导出是可选的, 并报告失败 在留下的痕迹。 这些命令需要伴奏后端释放; a404 旧服务器提供的不是没有指示的证据.