@ cerebro- labs/ agentnava- sdk

配置代理,开始谈话,与之合作.

npm install @cerebro-labs/agentnava-sdk

18号或以后,或Bun, 或任何运行时间与 fetch两者 import 财务报告和审定财务报表 require 工作,和TypeScript类型 船与之.

import { AgentNava } from '@cerebro-labs/agentnava-sdk';

const ws = AgentNava.getWorkspace(); // reads AGENTNAVA_API_KEY

const agent = await ws.agents.create({
  name: 'Refund checker',
  instructions: 'Decide whether a late delivery qualifies for a refund.',
});

const conversation = await agent.start({ endUserId: 'u_ananya' });
console.log(await conversation.ask('Order 4471 arrived nine days late.'));

全文见 https://docs.agentnava.com (中文(简体) ). (它曾经在这里指向 在我们自己的仓库内的文件路径, 没有人安装此软件包 已经。 ) 此读取母覆盖 只有容易出错的东西.

连接账户, 结束到结束

一个 账户 一个被保存的登录到一个应用程序。 A 类 连接 是条目 代理商的设置 名字之一, 所以代理完全使用 该账户,从来没有 另一个. ws.accounts.connect() 给你一个URL,一个人可以访问,和 waitUntilConnected() 告诉你什么时候完成.

import { App, Connection } from '@cerebro-labs/agentnava-sdk';

const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });
showToUser(url);                      // popup, redirect, QR code, your choice
await account.waitUntilConnected();   // resolves once they have signed in
await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));

您如何显示 URL 是您的: 此 SDK 认证带有 API 密钥, 所以它 运行在您的服务器上,浏览器的一半是您的应用程序.

超时就扔了 account_not_connected 和信件名称 和它现在的位置。 再打个电话是安全的 还没打完的人 签名可能只是需要更长的时间。 之后 account.reconnect() 它等待着 也新建登录:账户同时工作,使用 reconnecting 没错.

对于一个应用程序,你的每个用户 自己签名,连接使用 终端用户账户。 每个人签一次字, 记住他们 每一次谈话都没有附加任何内容:

await agent.connections.add(Connection.endUserAccount(App.GOOGLE_CALENDAR));

const conversation = await agent.start({ endUserId: user.id });
for (const { app, url } of await conversation.accountsNeeded()) {
  showToUser(app, url);               // the ones this person has not connected yet
}

终端用户的账户是普通的 Account数字 : agent.endUser(id).accounts.connect() 返回一个,并 waitUntilConnected(), (中文(简体) ), ws.account(id) 和所有其他账户 要求工作的方式一样. account.data.owner 说是谁的.

建造者创造许多明亮的物体, { app, account: '<id>' } 财务报告和审定财务报表 { app, endUser: true },其中任何一个手写对象也被接受. App.GMAIL 是字符串 'gmail',所以一个平整的字符串在常数的任何地方起作用 ,包括用于您 SDK 版本后添加的应用程序.

0.80:一个代理可以记住每个终端用户

直到你打开它 0.79个课间休息 才有变化.

await agent.update({ memorySettings: { on: true } });
const conversation = await agent.start({ endUserId: 'u_ananya' });

闲聊之后,一个背景特工 保持一个简短的记忆 用户,仅在该代理上,之后聊天使用. 你的团队可以读取和改变 这个 它需要一个团队计划或更高.

你通过的ID决定谁的记忆, 所以用一个稳定的ID一个人。 这个 指南,当您需要同意时: https://docs.agentnava.com/memory (中文(简体) )

0.79.0是一个突破性更改:一个终端用户属于一个代理

每个代理都是自己的应用程序,有自己的终端用户. 两名探员的同一身份是 两个不同的人, 分别的账户,秘密和谈话。 一个人 他们使用两个你的特工 标志每个.

直到现在,一个人的连通账户 被工作空间和ID单独发现,所以 代理B可以使用一个账户,该账户中不同的人与同一ID连接 通过特工A。 这就是这个结局.

年长的SDK会怎样. ws.endUser(id).accounts.* 财务报告和审定财务报表 ws.endUser(id).secrets.* 拒绝使用410(end_users_are_per_agent上面写着该怎么称呼. 一个空列表会读作"没有连接",所以他们从来不回答一个. agent.start, (中文(简体) ), conversation.ask,以及 conversation.accountsNeeded() 联合国 签入链接继续研究更古老的SDK:对话知道它的代理人.

现有账户 被提交到使用它们的代理人,没有新的 注册。 几个特工用过的一个没有去, 因为同样的身份可能 两个人 所以每个探员都请当事人签字. 工作空间成员 为: 不变:成员自己的账户不属于任何代理人.

0.44.0是一个突破性变化:应用程序和账户

现在两个词意味着两个东西。 一个 账户 一个被保存的登录到一个应用程序. A 类 连接 是一个代理商设置的条目: 一个名字,一个应用程序,以及其 账户,使用 Connection.creatorAccount(app, account) 联 合 国 代理创建者的账户或 Connection.endUserAccount(app) 每个终端用户 拥有的。 转弯完全使用账户设置名称 。 没有附着在 继续谈话,没有什么可以回溯到 与同一说法 应用.

升级与为新路线服务的生产发布: 0.44个电话 /v1/accounts, (中文(简体) ), /v1/end-users/:id/accounts 和代理连接 和连接路线0.43的电话在同一版中被删除. 没有兼容 shim: 这个软件包是发射前的, 所以旧名称 被删除,而不是贬值.

新建分支错误代码 : account_not_found, (中文(简体) ), connection_name_taken, (中文(简体) ), account_app_mismatch, (中文(简体) ), connection_not_found (从) agent.connections.change, (中文(简体) ), account_not_connected (从) waitUntilConnected, (中文(简体) ), account_required (从) Connection.creatorAccount 并且没有帐户 not_a_secret (已交给 attach) (中文(简体) ).

秘密没有移动 : agent.attach({ secrets }), (中文(简体) ), conversation.attach(secret), (中文(简体) ), conversation.attach({ secrets }) 财务报告和审定财务报表 agent.start({ attach: secret, secrets }) 像以前一样工作.

0.2.0是一个突破性的变化。 从0.1.1升级,不要留在上面.

"会议"从你触摸的一切中消失。 它只在我们的仓库里生存, 你永远也看不见.

0.1.1 停止工作 一旦它们到达生产, 因为API只读 新字段名称。 没有兼容 shim: 此软件包是私有的 因此旧的拼写被删除而不是被贬低.

如果你在0.1.1上,变化是机械的:重命名 sessionId 改为 conversationId 无论你读还是通过 没有别的形状 移动.

持有物体是自由的

ws.agent(id), (中文(简体) ), agent.conversation(id), (中文(简体) ), ws.project(id) 财务报告和审定财务报表 ws.account(id) 生产 没有网络呼叫。得到一些可以调用的方法,第一个请求会发生 当你打电话给一个.

存储 id,不是对象。 返回的对象是一个手柄,而不是JSON.

问:一种方法,两种形状

const reply = await conversation.ask('...');          // just the answer

for await (const e of conversation.ask('...')) {      // as it happens
  if (e.type === 'progress') showSteps(e.steps);       // the whole list, each time
  if (e.type === 'text') append(e.text);
  if (e.type === 'file') show(await conversation.readFile(e.path));
  if (e.type === 'done') save(e.reply);
}

progress 列表 AgentNava 应用程序在代理工作时显示的步骤, 在 相同词句("围网:钢铁关税"),每句 active, (中文(简体) ), done 或者说 error。将显示的内容替换为每个. file 命名代理文件 写了,每个文件一次.

留言在打电话时发出 ask而不是当你等待或提炼它. 通话 ask 两次生成两个提交密钥并两次询问。 如果你需要的话 ,在发送前保存密钥:

const idempotencyKey = crypto.randomUUID();
const reply = await conversation.ask('...', { idempotencyKey });

在同一次谈话中只用相同的内容重新使用该密钥. API (英语) 拒绝已经接受的回合 turn_already_accepted 而不是运行 又来了 一个新的有意问题需要一个新的关键。 错误包括: 用于检查状态的原始密钥和指示; a retryable: false 错误 不得作为新的呈文重新审理.

你们或许不止等待一次,这是应许,你们也得等待一次 答话 可能你不会用两下或混在一起 因为事情是 活流而不是存储列表,第二个消费者会收到 什么都没有。 换句话说.

轮不到你的要求了. 服务器一接受,就掉下来 连接, 中止 AskOptions.signal,或离开 for await 提前循环 停止接收回复。 接受的工作可以继续进行,正常收费 应用; 断开不会取消服务器工作或自动退款 转 已经放弃的信号传递给 ask() 阻止提交,所以没有 转弯被接受 或为这个电话收取费用.

使用信号限制应用程序等待时间 :

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10_000);
try {
  const reply = await conversation.ask('Summarize the report.', {
    signal: controller.signal,
  });
  save(reply);
} catch (error) {
  if (!controller.signal.aborted) throw error;
  // We stopped waiting. A turn already accepted by the server can still run.
} finally {
  clearTimeout(timer);
}

中断后读取 await conversation.messages() 在另一个之前 ask()。答案可能还在,所以稍后再检查历史 而不是再次提出同样的问题.

一个成功的 await 或者说 done 事件需要服务器的完成标记. 如果溪流提前关闭, SDK 报告一个不可重复的中断甚至 当回复文本已经到达时; 使用原始提交密钥检查其 在开始更多工作之前,请先确认身份.

更改代理发布一个版本

没有单独的保存. agent.update(), (中文(简体) ), setWorkflow, (中文(简体) ), removeWorkflow 财务报告和审定财务报表 setTriggers 每个版本发布新版本.

只发送什么变化. 你没有寄的都是继承的 当前版本。 这使得改变一个领域是安全的,它不是一个 方便:一个重建并重新发送整个配置的调用器 不管它忘了什么, 这已经造成了四个不同的数据丢失bug 密码库.

await agent.update({ instructions: 'Be brief.' });    // keeps everything else

一个对话会贴上它的版本

它在代理机的版本开始并保存时会固定. 之后出版 不移动已经打开的对话.

知识是例外,是故意的,是读的 参考文献这样 替换一个知识文件, 更改打开的对白中看到的内容 转 价格表,你无法纠正 不重写代理是 没用的.

两个驱动器

一份申请材料,在询问前写入:

await conversation.writeFile('/input/contract.pdf', bytes);
await conversation.ask('What are the payment terms?');

根下之所为. input/ 这儿是公约 什么都没有 执行它,因为代理和您的应用程序共享一个命名空间.

代理人使用的账户

每个连接在一个代理的设置名称 一个账户,一个转弯 准确使用 那个:

没有退路。 未签名的账户与其关联 找不到 代理商说 而不是找另一个 同样的应用程序.

秘密仍然分两层,不能替代: fixed 设置一次 经纪人, conversation 每次谈话都提供。 检查 conversation.ready 财务报告和审定财务报表 conversation.requires 来看看什么是杰出的.

您已经描述的 API 的起草工具

importTools 打开 OpenAPI 文档、 Postman 收藏或工作卷轴 命令为草稿 httpTools因此,没有人手写一个声明 终点.

import { importTools } from '@cerebro-labs/agentnava-sdk';

const draft = importTools({ openapi }, { include: (c) => !c.url.includes('/admin/') });
await ws.agents.create({ id: 'support', instructions, httpTools: draft.tools });

它完全运行在你的机器上。 没有任何关于源 发送到 Agent Nava, 这很重要, 因为这些文件通常包含活符 : 任何证书都用 {{secrets.NAME}} 占位符和 列入清单 draft.secrets,没有数值横跨。 每个起草的工具也 宣布它自己的秘密 secrets 字段,这是允许 运行时间装入他们转弯.

他们是草稿. draft.warnings 说出人类要决定什么 最大的一个是 description-missing: 三种格式中没有包含 句子 一个模型读取一个工具, 一个不好的描述不会失败,它 使特工打错了电话.

OpenAPI 文档中的规则(最小值、长度、模式、格式、格式) oneOf)并不花费你的手术。 它被写入参数的 说明, Rules: at least 1; at most 100.,而你的API 执行它作为它 对于任何呼叫者来说都是无效的;由于失败的结果,其400人到达了代理者 没错 确定一个安全计划的文件,但从未列在 security 每一个操作都有一个计划 security-choice 警告;有几种办法,没有一种办法,警告是这样说的.

HTTP 工具响应限制

声明式 HTTP 工具最多保留 64 KiB 响应数据并停止读取 当发现溢出。 限制数为UTF-8字节,而不是字符. 答复过多 返回时 ok: false, (中文(简体) ), truncated: true,则a response_too_large 错误正文 带有页码/过滤指导; HTTP 状态仍然是上游 状态。 部分JSON从未作为完整结果呈现. 使用 API 软件 过滤器和页码以获取链接页面中的大数据集.

错误

每一次失败 AgentNavaError。 。 。 .

catch (err) {
  if (err instanceof AgentNavaError) {
    err.code;       // 'agent_not_found', branch on THIS
    err.status;     // 404
    err.retryable;  // 5xx, 429, and network failures
    err.retryAfter; // seconds, on a 429
  }
}

分会 code,没有打开 message。代码是稳定的; 信件是为 阅读日志的人.

retryable 唯一值得自动化的东西: 400 将同样失败 永远,一个404将无法找到.

404既包括"没有这样的事",也包括"不是你的",所以一个叫人调查的id不能 告诉另一个客户的经纪人 从不存在。 没有403个.

配置

AgentNava.getWorkspace();                                   // AGENTNAVA_API_KEY
AgentNava.getWorkspace({ apiKey, baseURL, timeout });
AgentNava.getWorkspace({ fetch: myFetch });                 // a proxy, or a test

到处跑 fetch 已存在:节点, Bun, Deno, Cloudflare Workers, 浏览器. loadWorkflows 是一个例外; 它从磁盘上读取一个目录, 所以需要 节点或邦.

指向不同的部署

SDK的谈话 https://api.agentnava.com 除非你另有说法 两种方式 以改变它,明确的选项胜过环境变量.

// a dedicated enterprise endpoint
const ws = AgentNava.getWorkspace({ apiKey, baseURL: 'https://acme.agentnava.example' });

# staging, which is where a test key works
AGENTNAVA_BASE_URL=https://api-staging.agentnava.com

生产 URL 的中键失败 invalid api key,哪个 读起来像一个糟糕的密钥 而不是错误的宿主。 如果你得到了一个测试钥匙, 上方设置 URL 。 后面的斜线很好,有路径的基地 前缀也有效,用于坐在我们面前的API网关.

许可证

阿帕奇许可证2.0. 见 LICENSE,以及 NOTICE 归属问题 第4(d)节请您继续.

自由使用、修改和再分配,包括商业用途 明确授予专利权。 第6条不赋予姓名权利:“AgentNava” 而"Cerebro Labs"仍然是Cerebro Labs股份有限公司的商标.

回复中的部件( 0. 50)

agent.start({ endUserId, widgets: true }) 说你的屏幕可以画出牌,表和图表. 每回转一回 widget 事件(每次有一个完整的部件,替换为 surfaceId, (中文(简体) ), done 携带最终 widgets,以及 messages() 返回每个回复。 继续一个 agent.conversation(id, { widgets: true }). 部件使用Google开放的A2UI格式,并配有AgentNava自己的一组部件(AgentNava)Widget, (中文(简体) ), WidgetPart: 以您自己的组件绘制每个组件, 从其部分开始 id root,或使用下面的现成反应视图. placeWidgets(text, widgets) 按读取顺序将回复分为单词和部件,用于任何框架.

import { ReplyView } from '@cerebro-labs/agentnava-sdk/react'
import '@cerebro-labs/agentnava-sdk/react/styles.css'

<ReplyView text={reply} widgets={widgets} onAsk={send} />

反应是可选的对等点:只有 @cerebro-labs/agentnava-sdk/react 进口 每一部分都有一个默认的外观 --an-w-* CSS变量; parts={{ Stat: MyStat }} 以任何种类交换自己的组件, renderText 画出词来, currency 财务报告和审定财务报表 locale 格式编号,和 allowUrl 缩小链接和图片打开的位置(https://仅默认)。 经纪人自己的 widgets: false 把他们关了 代理字段的旧意义,一个没有读到的部件类型的列表,已经消失了,同样 widgets.json 文件 loadAgentDir 用来装入.

代理人居住的地方(0.41)

agent.get() 财务报告和审定财务报表 ws.agents.list() 带只读 status: 经纪人居住的地方, 按规则 API 运行它通过,并在 needs 任何需要的账户或尚未建立的秘密(它仍然运行;使用它们的工具失效直到它们失效).

企业HTTP合同(0.34)

需要相应的 API 和运行时间更新 。 参数类型包括对象和阵列,嵌入属性/物品,需要的每件财产,可失效,整数和附加物. 使用选择原始的enums. 向paramsJson提供本地的JSON值;对象体不是JSON-encoded字符串.

OpenAPI进口商尊重操作安全,文档安全和安全:[] (公有). 当文档精确定义了一个支持的方案而无 security 数组任意名称之一,此方案适用于不表示的每个操作 security: [],带有 security-choice 警告 ; 有多个方案, 或一个进口商无法设置( Outh, cookie) , 没有应用, 警告说工具没有发送证书 。 支持Bearer, Basic和header/query API密钥. 它保存了被继承的参数,解决了循环本地的 schema 引用,以及 URL-encodes path/query 值. 未发送 Omited 的可选查询/标题值和一个可选的全正文; 缺少所需的值在 HTTP 之前仍然失败 。 查询值中的秘密使用已编码的秘密 .

这个 secretName 每个操作仅代表一个证书。 进口商将每个安全选项与操作的证书头参数一起检查,并选择第一个相容的选项. 如果没有人能够使用单一的证书,进口商会以警告跳过操作,而不是重用同样的秘密来获取独立证书. 关闭覆盖以生成独立的秘密名称, 或者明确配置操作 .

审查进口警告。 Schema规则从不跳过一个操作:将边框,长度,图案,字符串格式和项目或字段计数写入参数的描述,被叫作API的API执行. oneOf编号 :anyOf 成为接受每一种替代品的参数,并列出各种替代品(One of: Card (with type, token); BankTransfer (with type, iban).); “ X 或 无效” 成为无效的 X 和 地图 (additionalProperties 持有 schema)对任意密钥保持开放. 当替代品不能共享一个形状(列表或对象)时,第一个形状将保留,一个形状 unsupported-body 警告字段名称. allOf 成员合并,包括除类型外的只规则成员。 在安全备选办法中作出选择会产生警告。 仍然跳过一个操作,有一个 unsupported-operation 警告:一个自相矛盾的 allOf, tuple 阵列(prefixItems),递归性或外部引用,一种没有类型,结构化的查询序列化,cookie认证和OAuth获取/再生的图案. Schemas 无法声明一个财产命名 __proto__工人计划适配器无法保存.

计划旁边的关键词 $ref 如OpenAPI 3.1所定义的,在参考链的每一个步骤中,与被引用的策略一起应用:一个描述取代被引用的策略,一个规则被描述,一个enum会缩小选择. 仅标出响应属性 readOnly: true 在导入其请求计划之前仍然省略.

所有三个执行路径都共享一个HTTP执行器. 结果包括小写 Link, Retry-after, request ID,ETag, Last-Modified, Content-Type和速率限制头. 具有信誉的头被排除在外,元数据中已知的秘密值被修改. HTTP 错误和大小过大的响应也不错: 外出工具信封也是假的 。 响应字节限制仍为64 KiB:过滤或活化较大记录.