@alexkroman1/aai (英语)

Assembly Associate SDK:一切都是一个 agent.ts 文件导入。 这个 自控运行时间 CLI 和管理的平台运行为 @alexkroman1/aai-runtime。 。 。 .

npm i @alexkroman1/aai zod

大多数项目不直接安装这个.. aai init (从) @alexkroman1/aai-cli(中文(简体) ) 脚手架用它连接一个项目.

简单的案子就简单

SDK的一种模式是单个套接字上的快取、语音和一些密钥名词 整个特工:

import { agent, assemblyAIS2s } from "@alexkroman1/aai";

export default agent({
  name: "Support",
  // The prompt is the system-prompt.md beside this file.
  mode: "s2s",
  s2s: assemblyAIS2s({ voice: "jane", keyterms: ["AssemblyAI"] }),
});

下方的一切都是当您自己的代码运行在它旁边时 能得到的. 这里不需要任何工作代理.

定义代理人

agent.ts ——定义,加上拥有会话状态的槽:

import { agent, sessionSlot } from "@alexkroman1/aai";

export const notesSlot = sessionSlot("notes", () => ({ items: [] as string[] }), {
  view: (notes) => ({ count: notes.items.length }),
  sync: true,
});

// `sync: true` on the slot is what shows it to the browser client (read there
// with `useAgentState`); the prompt is the system-prompt.md beside this file.
export default agent({ name: "Notes" });

• agent() ——代理定义;每个字段和默认记录在 AgentDef。没有提供者字段 运行默认的 Assembly STT → LLM → TTS 管道,计费为 1 ASSEMBLYAI_API_KEY· ; voice: "aai-michael" 选它TTS的声音.
• tool() - 无国籍人案件输入的工具:Zod inputSchema 还有一个 execute(args, ctx) 运行服务器侧 ctx.env (秘诀), ctx.signal (驳船时的破坏), ctx.generate (一发LLM呼叫), ctx.delegate (水手们), ctx.workflows (启动并找到可持久运行)和 ctx.send (向浏览器客户端推出事件).
• sessionSlot() ——一个被打出名的槽,拥有会话状态. slot.tool() 读取(数值被深深地冻结)和 slot.updateTool() 写出来 同步进行. 没有 ctx.state 没有 ctx.db。 。 。 .
• dialog() 编号 : procedure() - 车型被门挡住 车型自有 密码驱动器.
• speaker() 编号 : roster() 第2个声音:下放到线下 (单位:千美元)ctx.delegate),或发出电话(speaks: true) (中文(简体) ).
• workflow() 编号 : workflowApp() - 耐用跑道, 和形式形状的代理人 前门是工作流程而不是麦克风.
• assemblyAIPipeline() ——与明确分布相同的默认管道 (单位:千美元)...assemblyAIPipeline({ region: "eu" })),因为当你想要三个 在配置或跨STT和网关的欧盟区域可见.

agent() 取一个物体. AgentDef 是每个字段的参考文献 E. 方法——每个字段和默认都记载在那里 AgentParams 这是 以法律为组合的参考。 更全面的配置,包括 字段,上面的例子除外:

import { agent, sessionSlot } from "@alexkroman1/aai";
import { assemblyAITts } from "@alexkroman1/aai/tts";

// `sync: true` is what the browser client renders with `useAgentState`.
const cart = sessionSlot("cart", () => ({ items: [] as string[] }), {
  view: (c) => ({ count: c.items.length }),
  sync: true,
});

export default agent({
  name: "Storefront",
  greeting: "Storefront here — what are you after?",
  tts: assemblyAITts({ voice: "aai-michael" }),
  // Server-side helpers the model may call, on top of your own tool files.
  builtinTools: ["calculate"],
  // Tool-calling steps per reply, and how long a pause ends the caller's turn.
  maxSteps: 6,
  turnTaking: { minSilenceMs: 1200 },
  // Observe-only hooks over the session event stream.
  events: {
    "tool.called": (event) => {
      console.log("called", event.toolName);
    },
  },
});

工具:一个工具是 FILE

一个特工的价值是它要采取的行动, 他们每个人都生活在一个 只有您的代码才能到达系统 。 工具是一个文件在 tools/,以其名称命名 文件名 - agent() 采取不 tools 字段,没有记录:

// file: agent.ts
import { agent, sessionSlot } from "@alexkroman1/aai";

export const notesSlot = sessionSlot("notes", () => ({ items: [] as string[] }));

export default agent({ name: "Notes" });

// file: tools/add_note.ts
import { z } from "zod";
import { notesSlot } from "../agent.ts";

export default notesSlot.updateTool({
  description: "Save a note for the caller",
  inputSchema: z.object({ text: z.string() }),
  // `updateTool` hands the body a mutable draft, stored when it returns.
  execute: ({ text }, notes) => {
    notes.items.push(text);
    return { saved: notes.items.length };
  },
});

秘密不在代码之外 飞行中的工作就停止了 打断.. 通过 ctx.signal 任何缓慢的事物数字 :

import { requireEnv, tool } from "@alexkroman1/aai";
import { z } from "zod";

export default tool({
  description: "Get current weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }, ctx) => {
    const key = requireEnv(ctx, "WEATHER_KEY");
    const resp = await fetch(`https://api.example.com/weather?q=${city}&key=${key}`, {
      // Aborts on barge-in, reset, session stop, or this call's timeout.
      signal: ctx.signal,
    });
    return await resp.json();
  },
});

内置工具和代码执行

builtinTools 将模型选择为服务器侧助手, 它可以调用 - web_search, (中文(简体) ), visit_webpage, (中文(简体) ), get_page_design, (中文(简体) ), fetch_json, (中文(简体) ), think, (中文(简体) ), remember编号 :recall, (中文(简体) ), calculate,以及 run_code,模型写 JavaScript并运行在代理的沙盒中. 模型在精神上是不可靠的 算术; 真正的执行是使拨打的号码正确 打电话者要采取行动了.

import { agent } from "@alexkroman1/aai";

// system-prompt.md: "Use run_code for ANY math, counting, or data processing."
export default agent({
  name: "Analyst",
  builtinTools: ["web_search", "run_code"],
});

选择 builtinTools 让他们都无法生存 网络化的内建 模型控制的 URL,所以它们在容器和盖外被 SSRF 筛选 回来的是什么; run_code 需要一个沙盒——平台,或 零允许 AAI_RUN_CODE=deno - 并拒绝一个外.

输入会话状态

长时间的通话积累了事实——订单号,什么已经核实,什么在 车。 没有结构化的状态 探员从记录中重新找到他们 每转一圈. sessionSlot() 在一个共享模块中声明,唯一的 如何在会话工具中保持状态 :

import { sessionSlot } from "@alexkroman1/aai";
import { z } from "zod";

export const cartSlot = sessionSlot("cart", () => ({ items: [] as string[] }));

// `slot.tool()` READS — what the body is handed is frozen.
export const listCart = cartSlot.tool({
  description: "List what's in the cart",
  execute: (_args, cart) => ({ items: cart.items }),
});

// `slot.updateTool()` WRITES — mutate the draft; it is stored when the body
// returns, so a write is SYNCHRONOUS and may not `await`.
export const addItem = cartSlot.updateTool({
  description: "Add an item to the cart",
  inputSchema: z.object({ item: z.string() }),
  execute: ({ item }, cart) => {
    cart.items.push(item);
    return { count: cart.items.length };
  },
});

槽持有纯数据(a) Map, (中文(简体) ), Set, (中文(简体) ), Date 或类案例被拒绝 字段名称)。 在平台上,他们被储存 为你 - 一个坠机或一个 调用不再失去它们,也没有任何可用的. 下 aai dev 他们生活在记忆中 除非你设置 DATABASE_URL代码是相同的 就是这样.

每届会议可以复会

连接下降, 五分钟的身份验证加半建 命令不应该重新启动。 客户端重新连接 ?sessionId=<id> 重新登记 同一会话:事件日志被恢复,槽值被还水 问候被压制,因为呼叫者已经听到了. 简历 没有东西被当做新会议 而不是坐着问候 相通而无声. 背景工作按键再次找到——稍后, 或者在下一个电话:

import { tool, workflow } from "@alexkroman1/aai";
import { z } from "zod";

export const research = workflow({
  description: "Research a topic",
  input: z.object({ topic: z.string() }),
  run: async (input) => ({ topic: input.topic, findings: [] as string[] }),
});

export default tool({
  description: "Check on research from earlier",
  execute: async (_args, ctx) => {
    // The run outlived the call — find it by the key it was started with.
    const [run] = await ctx.workflows.find(research, ctx.sessionId);
    if (!run) return { status: "none started" };
    return run.status === "completed" ? run.output : { status: run.status };
  },
});

作为保证的谈话令

在系统提示中“在披露前验证”是建议. dialog() 让它成为一个 规则: 以 when 根本就没有在这些国家之外运行 模型会回来的 ToolFailure 命名必须先发生的事情。 这个 位置是下面的一个插槽,所以它能活过再连接.

import { dialog } from "@alexkroman1/aai";
import { z } from "zod";

export const claim = dialog("claim", {
  initial: "verifying",
  states: {
    verifying: {
      instruction: "Verify the caller's policy number before quoting anything.",
      on: { VERIFIED: "quoting" },
    },
    quoting: {
      instruction: "Quote the excess. Do not re-verify.",
      on: { QUOTED: "done" },
    },
    done: { final: true },
  },
});

// Cannot run before the caller is verified; advances the dialog when it does.
export const quoteClaim = claim.tool({
  when: "quoting",
  send: { type: "QUOTED" },
  description: "Quote the premium for an excess",
  inputSchema: z.object({ excess: z.number() }),
  execute: ({ excess }) => ({ premium: excess * 2 }),
});

州和事件是从谱中推断出来的 所以拼错了 send 是一个 编译错误 . procedure() 是无型号驱动的流体兄弟 循环中的 X 状态机器,有分支、重试和有限制的预算,运行 与 await procedure(machine).run(input)。 。 。 .

理解中转

特工们不断需要小的谅解行为: 从乱伦的句子中,对意图进行分类,对检索到的文件进行分级. ctx.generate() 一个LLM呼叫,主机侧, 保证形状回:

import { tool } from "@alexkroman1/aai";
import { z } from "zod";

export default tool({
  description: "Start an order from what the caller just said",
  inputSchema: z.object({ utterance: z.string() }),
  execute: async ({ utterance }, ctx) => {
    const parsed = await ctx.generate({
      prompt: `Extract the order from: "${utterance}"`,
      schema: z.object({ sku: z.string(), qty: z.number() }),
    });
    // `object` is typed by the schema: { sku: string; qty: number }.
    return parsed.object;
  },
});

它默认为代理自己的 llm; 通过一个 llm 描述符或模型代号 字符串用于使用密钥在代理机密中的任何提供者——这也是 s2S代理如何到达模型.

副剂

复杂请求需要未知数量的查询 呼叫者不需要 听着 排出队来,他们低声说话,每转一转就慢一点; 外出时,腿部工作会从侧面进行——如果有的话,则平行进行 数个角度——呼叫只带答案. 副剂是第二 工具环路, 带有自己的系统即时、模型、工具和上下文窗口:

import { speaker, tool } from "@alexkroman1/aai";
import { z } from "zod";

const researcher = speaker({
  name: "researcher",
  systemPrompt:
    "Research the task with the tools you have. IMPORTANT: your final message " +
    "is the only thing the caller sees — end with a self-contained summary.",
  builtinTools: ["web_search", "visit_webpage"],
  maxSteps: 6,
});

export default tool({
  description: "Research a question in depth",
  inputSchema: z.object({ question: z.string() }),
  execute: async ({ question }, ctx) => {
    const { text, toolCalls } = await ctx.delegate(researcher, { task: question });
    return { answer: text, lookups: toolCalls.length };
  },
});

你收到它的最后信息,它的背景是孤立的,因此请它 总结和写 task 作为完整的简介。 代表团是一个深层.

活在电话里的工作

报告生成时,没有呼叫者持有4分钟。 工具开始持久 运行并回答转弯; 运行是日记的, 因此它能通过重启, a 调用和闲置的沙盒。 与 notify 经纪人说结果的时候 lands——普通可中断的转会,只有在呼叫者仍然在线上. 如果他们挂了,运行完成 反正下一个电话找到它 key。 。 。 .

import { tool, workflow, type WorkflowContext } from "@alexkroman1/aai";
import { z } from "zod";

// workflows/research.ts — an ordinary async function of its input and a ctx.
export async function researchFlow({ topic }: { topic: string }, ctx: WorkflowContext) {
  // `ctx.step` runs once and journals what it returned; a replay never re-runs
  // it. The body itself makes no undurable decision — no Date.now(), no fetch.
  const findings = await ctx.step("gather", () => gather(topic));
  // Suspended, not blocked: the container may exit here and resume when due.
  // Ten minutes and six hours work the same way.
  await ctx.sleep("settle", 10 * 60 * 1000);
  return findings;
}

declare function gather(topic: string): Promise<{ topic: string; points: string[] }>;

export const research = workflow({
  description: "Research a topic and report back",
  input: z.object({ topic: z.string() }),
  run: researchFlow,
});

// tools/research_topic.ts — promise made, and kept.
export default tool({
  description: "Research a topic in the background",
  inputSchema: z.object({ topic: z.string() }),
  execute: async ({ topic }, ctx) => {
    await ctx.workflows.start(research, { topic }, {
      key: ctx.sessionId,
      notify: "Tell the caller what it found.",
    });
    return { started: true };
  },
});

宣布代理工作流程(agent({ workflows: { research } })和 ctx.workflows 能够 start, (中文(简体) ), find, (中文(简体) ), get, (中文(简体) ), wakeUp 财务报告和审定财务报表 stream 它的运行。 何时 产品是形式而不是呼唤, workflowApp() 其代理人 前门是一个工作流程——没有会话,没有LLM回路,每个语音节点 a 编译错误 .

说话,屏出

调用者在屏幕上的手推车、表格或行程更新时进行交谈 输入,屏幕确认。 这样一来,命令就不用读了 十六位数大声点. syncState 取一个proJECTION,而不是一面旗帜,所以你选择 允许浏览器查看的内容 :

import { agent, sessionSlot } from "@alexkroman1/aai";

// shared.ts — declare the view on the slot and import it at both ends.
// `staffPin` is not in the view, so it never reaches the browser.
export const cartSlot = sessionSlot("cart", () => ({ cart: [] as string[], staffPin: "" }), {
  view: (s) => ({ cart: s.cart }),
  sync: true,
});

export default agent({ name: "Storefront" }); // the `sync: true` slot is collected

import { sessionSlot } from "@alexkroman1/aai";
import { mountClient, useAgentState } from "@alexkroman1/aai-ui";

// client.tsx — in a project this is `import { cartSlot } from "./shared.ts"`,
// the same slot the agent declared, so the two ends cannot name different views.
const cartProjection = sessionSlot("cart", () => ({ cart: [] as string[] }), {
  view: (s) => ({ cart: s.cart }),
}).projected;

function App() {
  // The projection types the state AND supplies the frame rendered before the
  // first push — no type argument, no `?? EMPTY`.
  const view = useAgentState(cartProjection);
  return (
    <ul>
      {view.cart.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  );
}

mountClient({ component: App });

投影在每次工具调用后运行, 只有在结果出来时才发出 换了. ctx.send(event, data) {\fn黑体\fs20\shad2\2ah82\3ah20\4ah33\fscx95\3ch592001\be1}是一切不真实的推道 状态; @alexkroman1/aai-ui 有钩子和部件.

每行各一名探员

说出你的号码所在的载体, 和特工的电话 会话以 :

import { agent } from "@alexkroman1/aai";

export default agent({
  name: "Support",
  // `true` admits every carrier this build decodes; omit it and the phone
  // route is not served at all.
  telephony: ["twilio"],
});

然后把数字的语音网钩对准经纪人 用媒体回答 流线 :

wss://<your-agent-url>/phone?carrier=twilio
wss://<your-agent-url>/phone?carrier=telnyx

Twilio和Telnyx是这些建筑解码器的载体;它们都说出8千赫的m-law, 以两面相接而行, 驳船,工具和槽像浏览器一样在呼叫中运行. 一个电话是 运输,不是一种模式——你在网络演示中测试的是呼叫者得到的.

会话模式和提供者

管道模式 (默认) 串流 STT 部分进入服务器侧 LLM 循环和 通过 TTS 供应商来表达答案 。 把任何舞台都换成工厂 提供者子路径 - 设置任意子集 stt, (中文(简体) ), llm, (中文(简体) ), tts; 未设置的相位保留 assemblyAI 默认:

工厂返回纯描述符——可序列数据,而不是SDK客户端. 证书由代理服务器端解决(每个工厂的文件) 所以没有提供商SDK 或秘密进入代理包. llm 也接受一个模型化字符串 : "creator/model" 途经 Vercel AI Gateway,一个通过AssemblyAI LLM Gateway的赤裸的身份证—— agent({ name: "...", llm: "claude-sonnet-4-6" }) 换掉的只是模型.

S2S 模式 是语音对语音服务的明确选择,其中STT, lLM 环路和 TTS 都在一个套接字上运行: s2s: assemblyAIS2s() (源导出)或 openAIS2s() 从 @alexkroman1/aai/s2s。 。 。 .

测试工具

一个复杂的代理是一个活代码库——数十个工具,一个不断发展的即时, 有几个人编辑它。 一个工具是文件,所以 agent.ts默认导出 没有携带工具; deployedAgent 给您定义一个部署的代理 运行,然后每个工具都可以单独调用,没有会话、模型和 无网络 :

// file: agent.ts
import { agent, sessionSlot } from "@alexkroman1/aai";

export const notesSlot = sessionSlot("notes", () => ({ items: [] as string[] }));

export default agent({ name: "Notes" });

// file: tools/add_note.ts
import { z } from "zod";
import { notesSlot } from "../agent.ts";

export default notesSlot.updateTool({
  description: "Save a note for the caller",
  inputSchema: z.object({ text: z.string() }),
  execute: ({ text }, notes) => {
    notes.items.push(text);
    return { saved: notes.items.length };
  },
});

// file: agent.test.ts
import { createToolContext, deployedAgent, toolRunner } from "@alexkroman1/aai-runtime/testing";
import { expect, test } from "vitest";
import authored from "./agent.ts";
import addNote from "./tools/add_note.ts";

const agentDef = deployedAgent(authored, {
  tools: import.meta.glob("./tools/*.ts", { eager: true }),
});
const run = toolRunner(agentDef);

test("saves a note", async () => {
  // Typed by the tool's own def: `saved` is a number, no cast.
  const { saved } = await run(addNote, { text: "milk" }, createToolContext());
  expect(saved).toBe(1);
});

createToolContext() 建立一个完整的 ToolContext 有惰性默认和 a 录音 ctx.send· ; stubGenerate, (中文(简体) ), stubDelegate, (中文(简体) ), stubGateway 财务报告和审定财务报表 stubUploads 驱动工具合作者的答案. aai build 运行 在项目捆绑之前先检查套件和类型.

行为影响

快速的调子可以悄悄地降低工具纪律 没有人用手测试每部编辑的40种情景. describeEval (从) @alexkroman1/aai-runtime/testing/vitest运行 aai eval驱动一个真实的 并声称代理人做了什么 是什么工具 它叫什么顺序, 和它所说的:

import { agent } from "@alexkroman1/aai";
import { describeEval } from "@alexkroman1/aai-runtime/testing/vitest";
import { expect } from "vitest";

const agentDef = agent({ name: "Support" }); // the prompt is system-prompt.md

describeEval(agentDef, (test) => {
  test(
    "looks the order up first",
    async ({ session }) => {
      const turn = await session.say("where is order W1234?");
      expect(turn.toolCalls.map((c) => c.name)).toContain("look_up");
      expect(turn.text).toMatch(/shipped/i);
    },
    // What a scripted model answers when there is no provider key — the eval
    // still proves the agent boots, tools resolve, and a reply comes back.
    { stubReply: "Order W1234 shipped yesterday." },
  );
});

使用提供者密钥, 同一文件驱动一个活模式; 没有一个则运行 脚本,所以它在CI中是自由的和决定性的.

其他子路径

每个子路径都由WHO 读取它命名——当右侧一栏到达 描述你在做什么.

文档

完整 API 参考 : https://alexkroman.github.io/ agent/ 页面存档备份,存于互联网档案馆

完整的编写指南 agent() 字段、工作流程规则、UI 钩子 语音即时规则——本套装中的船为: AGENT_GUIDE.md, (中文(简体) ), 除了这个文件。 (直接不是相对链接: TypeDoc 复制链接) 文件输入了制成的 Docs 树,这个是生成的100 kB 文本 已经住在两个地方。 )