@ felspar/ sdk (英语)
Felspar是企业代理商共同的,版本化的决定系统. 公司认可的含义,证据需要决定,决定本身在发布的"决定包"中一起出行. 特工们要求费尔斯帕做决定,获得他们可以核实的收据,只就费尔斯帕的决定采取行动.
此软件包将代理连接到 Felspar: a 爱娃 在两行中连接,一个为主机Felspar API提供的TypeScript客户端,和一个使代理工具在未经核实的Felspar决定的情况下不能行动的动作门. 它运行在节点24或以后, 它唯一的依赖是 zod. SDK是一个运输客户端:决定和政策停留在Felspar服务和放行的包上,而SDK不重新执行.
模块 draft/ 在 API 结算时, 可以在 1.0 之前在小版本之间更改 .
安装
npm install @felspar/sdk
连接 Eve 代理
单位 agent/connections/felspar.ts数字 :
import { defineMcpClientConnection } from "eve/connections";
import { felsparConnection } from "@felspar/sdk/eve";
export default defineMcpClientConnection(felsparConnection());
特工拿到菲尔斯帕的 list_jobs, (中文(简体) ), get_job_requirements, (中文(简体) ), get_job_decision 财务报告和审定财务报表 check_output 工具,没有别的。 关键是代理商自己的,在Felspar网页(Workspace → Company 代理商)上创建,并读取自 FELSPAR_AGENT_KEY 当 Eve 连接时; 终点是 FELSPAR_MCP_URL或生产。 过 { url, agentKey, description } 来推翻他们 这些工具采用的方法是: get_job_requirements 说要收集什么和如何收集,每个结果都说下一步要做什么,所以经纪人不需要费尔斯帕的技能或自己的快感.
超过MCP, get_job_requirements 财务报告和审定财务报表 get_job_decision 默认按紧凑方式回答。 简报 input 列出参数和一个简短 facts 以工作本身的问题为例。 裁决保留了特工的行为 executionObjectId,满 receipt,则 context 胶囊和 explanation.evidenceFreshUntil,这是动作门记录和验证. detail: "full" 返回 REST 简介或结果不变。 代理发送未执行 ID: 呼叫 get_job_decision 在同一小时内再次提出同样的论点,将已经作出的决定退回 blocked 表示第一通电话仍在运行. 见 MCP工具。 。 。 .
主机客户端
import { createHostedFelsparClient } from "@felspar/sdk/draft/hosted-client";
const felspar = createHostedFelsparClient({
origin: "https://api.felspar.ai",
agentKey: process.env.FELSPAR_AGENT_KEY,
});
// The jobs this agent key may run, by ID.
const { jobs } = await felspar.listJobs();
// What the job needs (questions, evidence rules, outcomes and their outputs),
// on the release Felspar runs for this key now.
const job = await felspar.describeCurrentJob("route-support-ticket");
const releaseId = job.release.releaseId;
// Facts in, decision out. The release pin comes from the job description.
const response = await felspar.resolveFacts(releaseId, {
jobId: "route-support-ticket",
executionId: crypto.randomUUID(),
entityId: "48213",
facts: {
request_type: {
text: "I was charged twice for my March invoice.",
source: { class: "ticket-thread", id: "48213", observedAt: new Date().toISOString() },
},
},
});
if (response.status === "ready") {
console.log(response.result?.outcome, response.result?.receipt);
}
一个电话: decide
自兹 0.4.4;规则、下一步、交接单词、收据和公开的事实 0.4.5。 。 。 .
当同样的证据每次到达时(一个编码代理的工具呼叫及其更改记录,一张支持票及其账户记录),按种类给每块贴上标签,让费尔斯帕在工作的问题下存档:
const decision = await felspar.decide({
job: "gate-deploys",
case: "toolu_01ABC", // the case's ID; leave it out where the job derives its IDs
evidence: [
{ kind: "tool-call", toolCall: { name: "Bash", input: { command: "kubectl apply -f deploy/prod.yaml" } } },
{ kind: "change-record", id: "CHG-1042", text: "CHG-1042: approved by Ana Ruiz; production" },
],
timeoutMs: 10_000, // the default; keep it inside your caller's own timeout
});
// { action: "allow" | "flag" | "block", reason, rule, nextStep, missing, escalation,
// resultId, receiptUrl, open, toProceed, outcome, receipt }
if (decision.action === "block") {
console.error(decision.reason, decision.nextStep, decision.toProceed);
}
decide 发送一个请求,没有执行ID或放行: Felspar使用代理的放行(Lasters或被绑),同一小时的同名呼叫返回同一个决定. 一个工具呼叫是 toolCall 正如特工的运行时间报告的那样 Felspar读了. action 这是做什么。 没错 allow 或者说 flag 只有在费尔斯帕决定一个结果 意味着,和 block 对于其他一切:阻碍的结果、缺少证据、拒绝、内部无答案 timeoutMs,或者没有连接。 所以,代码只作用于 action 未关闭 . reason 是政策所引用的规则,或者,用简单的话说,为什么没有决定. nextStep 政策是现在要做什么, escalation.text 谁从这里拿,和 resultId 财务报告和审定财务报表 receiptUrl 裁决的收据。 当费尔斯帕无法决定时, open 列出每个无法用平话解决的事实 label,以及 toProceed 说什么证据可以解决它。 派一个老费尔斯帕不回来 null 或为空. decide 永远不要扔, 并在最后期限内重复一次 当菲尔斯帕忙着,或者同一个电话仍在决定。 过 shadow: true 费尔斯帕记录下来 每个 kind 必须是工作描述列表 在问题接受的来源.
describeJob(releaseId, jobId) 描述一个你已经知道的释放, 比如一个你钉住.
事实可以直接来自一种记录系统,在两者之间没有代理人:将每个问题的证据作为消息来源自己的话发去(......)text,例如票房或账号记录的"计划:业务(月刊)",与票出处相通(出处相通)source.class, (中文(简体) ), source.id, (中文(简体) ), source.observedAt) (中文(简体) ). Felspar将这些单词归为回答选择和是/否问题;一个赤裸的标签,例如: { value: "business" } 拒绝使用 label_needs_mapping因为释放的问题决定了这些词的含义。 数字和日期问题按键 { value } (日期为: YYYY-MM-DD) (中文(简体) ). 只有工作本身的问题键被接受( E)unknown_question (否则).
一个人给代理人的言语(从电话中发出的一行信息)也是证据:按给与的发送 source: { class, manual: true, locator }名称 locator 他们的来源,没有 id 或者说 observedAt; Felspar 邮票收到时间,结果和收发情况将它们列在 manualFacts. 其描述包含 manualFacts: { allowed: false } 拒绝manual_facts_refused:引用源记录本身.
verifyReceipt(executionObjectId, { receipt, expectedReceiptDigest, deliveredCapsule }) 要求费尔斯帕重播一个决定并比较其收到,以及 checkOutput(job, { executionId, text, output? }) 检查您决定的文本( e)readOutputCheck(job, checkId) 读回一张支票).
如何识别案件来自该工作的描述(identity: 发送 entityId 为记录自己的身份(provided, (中文(简体) ), identity 字段值( r)fields),或无(content,以及第一个决定 issued 任务。 结果 case 给案件 id 财务报告和审定财务报表 mode; 发送 case.id 作为 entityId 以后对同一案件的判决 输入结果(FelsparJobResult: case, (中文(简体) ), subject 联合国 related 记录, escalation (单位:千美元)id, (中文(简体) ), trigger, (中文(简体) ), why和 missing 为了一个缺口.
拒绝的请求 FelsparRequestError 与 HTTP 连接 status 服务 refusal (数量) error 代码,其中有一个a fix (单位:千美元) recovery 联 合 国 fix_input, (中文(简体) ), retry 或者说 escalate,以及任意 escalation 名称,例如: attempt_limit_reached) (中文(简体) ).
行动门
大门坐落在一个工具前,它的行为,例如写出电子邮件草稿或回答罚单. 只有在允许调用字段时,才允许调用,调用的内容是本会中决定的一个案例Felspar,Felspar重新核实决定的收受,决定的结果允许该工具. 任何错误,以及任何未知或含糊不清的东西,都否认.
import {
createActionGate,
felsparJobDescriber,
felsparOutputCheckVerifier,
felsparVerifier,
} from "@felspar/sdk/draft/action-gate";
const felspar = { origin: "https://api.felspar.ai", agentKey };
const gate = createActionGate({
job: "route-support-ticket",
decisionTool: "felspar__get_job_decision", // exact tool names in your runtime
outputCheckTool: "felspar__check_output",
tools: {
helpdesk__reply: {
writes: "billing-team-reply",
entity: { field: "ticketId" },
fields: ["ticketId", "body"],
outputCheck: { fields: ["body"] },
},
},
verify: felsparVerifier(felspar),
describe: felsparJobDescriber(felspar),
verifyOutputCheck: felsparOutputCheckVerifier(felspar),
});
一个工具可能做的来自于释放的包,而不是出自大门的配置:
writes名称工具所写的输出, 以其在包中的 ID 。 只有当发布的职务说明列出了结果Felspar的回放报告下的输出时,才允许调用. (规则可以规定outcomes,则列出结果标识;确切地说,两者之一。 )- 哪个案子的电话来自被解职的主体和身份 决定记录在
case.idFelspar 的结果名称( 所以是发送否的代理entity_id,对于一个发行,字段或内容工作,仍然得到一个),而费尔斯帕尔的回放必须命名同一个案例ID和模式. 默认 :- 对于一个被提供对象的不敏感案例的ID,例如网页域(或无主题的发布),每个收件人的电子邮件域必须属于一个决定的Felspar公司;一个不是公司域的决定ID不允许收件人,所以给这样的规则一个实体域;
- 对于其他任何工作, 调用是关于此工作在会话中决定的一个案件; 对于几个案件, 调用会被拒绝, 直到规则指定一个字段.
entity: { field }覆盖:输入字段必须持有案件的ID,记录本身的ID(如票证)或case.idFelspar发布或衍生出,修剪并配对主体的匹配规则(除非主体对大小写不敏感;没有主体,HC-1201财务报告和审定财务报表hc-1201(见A/CN.9/WG.III/WP.96,第2段)。 接收者则不与案件挂钩,因此,一个能够解决任何人问题的工具也应加以限制(testRecipients,或工具自己的设置).outputCheck要求Felspar通过该呼吁为该决定发出的文本(check_output; 与writes用于输出.
拒绝是 { allow: false, reason, escalate?, escalation? }。 。 。 . escalate 是公司的下一步,引自所发布的描述:结果不允许工具时,结果的下一步,或者无所决定时该怎么办. 对于缺失或失败的输出检查,是固定指令来修正什么 check_output 标记和检查再次. escalation 政策名称是: { id, trigger, why },随着费尔斯帕尔重播结果的ID(或工作未解决的路径)和 why 引自该版。 释放时两人都缺席. 下方的每个适配器都带着理由向模型显示.
然后连接大门到你的代理框架。 工具名必须与运行时间报告完全匹配 .
爱娃
import { felsparDecisionEvents, felsparGate } from "@felspar/sdk/eve";
// On the connection whose tools act:
approval: felsparGate(gate),
// And in a hook that records Felspar's decisions and output checks:
export default defineHook({ events: felsparDecisionEvents(gate) });
克劳德探员SDK
import { felsparHooks } from "@felspar/sdk/draft/action-gate/claude-agent-sdk";
// Tool names are mcp__<server>__<tool>.
for await (const message of query({ prompt, options: { hooks: felsparHooks(gate) } })) {
// ...
}
OpenAI 代理服务器 SDK
import {
felsparDecisionOutputGuardrail,
felsparToolInputGuardrail,
} from "@felspar/sdk/draft/action-gate/openai-agents";
// sessionOf must return an ID unique to the conversation.
const sessionOf = (runContext) => (runContext.context as { conversationId: string }).conversationId;
// On the MCP server whose tools act:
toolInputGuardrails: [felsparToolInputGuardrail(gate, { sessionOf })],
// On Felspar's MCP server:
toolOutputGuardrails: [felsparDecisionOutputGuardrail(gate, { sessionOf })],
在代理框架之外, checkAction({ rules, toolName, input, decisions, verify, describe }) 返回同一判决.
对于生产行动,设定 environment: "production" 门规则; 使用
"staging" 为中转门。 此选项在 0.4.3A级
配置的门否认其他或缺失环境,包括中转决定
他们的释放后来得到了促进。 暗示它保留了现有的行为
没有环境限制。 保留设置主机; 自定义验证器
必须返回环境 Felspar确认。 A 类 releases 单针不会
建立决定的环境.
一份Felspar收据记录了Felspar从提供的证据中裁定的内容。 它不是事实、法律或安全证明,通过的产出检查意味着文本遵循已发布的规则,而不是真实或批准发送.
实例
felspar 实例 拥有完整的项目:一个Eve代理,一个在动作门后有电子邮件草稿的同一代理,以及一个在没有代理的情况下得到决定的脚本.
文档
完整文档: (原始内容存档于2017-09-28) (英语). docs.felspar.ai。 。 。 .
许可证
阿帕奇 - 2.0
为人们绘制的决策图
主机客户的 getReleaseGraph(releaseId), (中文(简体) ), getProposalGraph(proposalId)
财务报告和审定财务报表 getDecisionGraph(executionObjectId) 读取卡通美人鱼图
释放/物质针和仪表板链接。 这些检查方法要求:
; 拒绝代理密钥。 决定
图表复制其原始发行时保存的收据。 检查 status 在此之前
使用 mermaid: 没有历史不是推断路径 。 显示返回的
来源不变.
使用 getReleaseDiagram, (中文(简体) ), getProposalDiagram 或者说 getDecisionDiagram 联 合 国
简明概览。 每个都接受 { detail: "overview" | "full" };决定
帮助者也接受 { view: "run" | "release" }检查 availability显示
mermaid 和全面结果 overview,并提议
原图 canonical。原始的图表助手不变.