AssemblyAI Agent SDK

Install

npm i -g @alexkroman1/aai-cli
aai init my-agent
cd my-agent
aai dev

aai dev prints a URL. Open it and talk to your agent.

You need Node.js 24, 25, or 26 and an ASSEMBLYAI_API_KEY. That one key covers listening, thinking, and speaking.

A whole agent

Three files. None of them imports another.

agent.ts

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

export default agent({
  name: "Weather Line",
  greeting: "Which city are you asking about?",
  voice: "michael",
});

system-prompt.md

You help callers plan around the weather.
Answer in one or two sentences. This is a phone call.

tools/get_weather.ts

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

export default tool({
  description: "Get the current weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => {
    const res = await fetch(`https://wttr.in/${city}?format=3`);
    return { report: await res.text() };
  },
});

The model can call that tool, and it calls it get_weather. There is no registration step: a file in tools/ is a tool because it is in tools/, and system-prompt.md is the system prompt because it exists.

Start here

Quickstart — a working agent, published, in about five minutes.

What a project looks like

How it works — the files, and what happens on a call.

Give it abilities

Tools are ordinary async functions. The model decides when to call them.

Every option

The SDK reference is generated from the source. Every field, provider, and helper is in it.