TypeScript SDK¶
Build agents that run in a browser, a web page or Node. They are governed by a Fadenstack server, or run on the person's own AI server in standalone mode.
Server version
This version of the SDK (0.3.0) is built against Fadenstack server 0.7.1. Agents need a server 0.4.2 or later;
with 0.4.1 and older, only plain chat completions work, without tool modes, rules and the
gateway's events. Where a server lacks a route that a newer feature uses, the SDK says so where it can:
listTools answers null, signing in by pairing throws a FadenstackPairingUnsupportedError, and an agent built
with requireHostToolPolicyChecks() refuses to start.
What the SDK does¶
The SDK runs the agent loop on the device. It sends the conversation to the server, runs the tools your application provides, asks the user before a tool changes something, and keeps the conversation on the device.
The server owns the parts that should not live in your application: the agent's instructions, its model and its knowledge. It also handles personal data (PII), rate limits and the audit record.
You register an agent on the server first, and your application then signs in to it on behalf of a user. See Agents for what the server keeps about an agent, and Your first agent to register one.
The SDK also powers Fadenstack's browser agent.
Packages¶
| Package | What it is | .NET |
|---|---|---|
@fadenstack/client |
The server connection: the gateway's chat completions (streamed, with the gateway's events), agent sign-in, the agent resource (profile, event reports, approvals), tool classes and modes, typed errors | Fadenstack.Client |
@fadenstack/agents |
The agent: the builder, the tool loop, tool classes and modes, approvals, sessions on the device, outcomes, stages and modules | Fadenstack.Agents |
@fadenstack/ui |
View models for a chat with an agent, with no UI framework | Fadenstack.UI |
@fadenstack/ui-web |
The web look every skin shares: the stylesheet, icons, the agent's avatar, the panel's browser behaviours | Fadenstack.UI.Wpf (its themes) |
@fadenstack/ui-react |
The React skin for those view models: a chat panel | Fadenstack.UI.Wpf, Fadenstack.UI.Avalonia |
@fadenstack/ui-vue |
The Vue skin for the same view models: the same chat panel | Fadenstack.UI.Wpf, Fadenstack.UI.Avalonia |
@fadenstack/testing |
A fake Fadenstack server for tests and demos | — |
@fadenstack/provenance |
Marks content the agent's tools place as made with AI: place(), markers for the hosts, signed records and placement reports |
Fadenstack.Provenance |
@fadenstack/skills |
Agent Skills on the device: load_skill and read_skill_resource, the person's own skills in IndexedDB, the faden.yaml pre-selection |
Fadenstack.Skills |
@fadenstack/mcp |
Local MCP servers over HTTP: the person's servers in IndexedDB, the hint rule, import and the policy | Fadenstack.Mcp |
The packages follow the .NET SDK: the same concepts, the same tool classes and modes, and the same transcript format for sessions. Libraries says what each package is for, and the parity table lists the features of both SDKs side by side.
Runtimes¶
- Browsers: Chrome 116 or later, in a web page or a browser extension.
- Node.js 24 or later.
The packages are ES modules with type declarations. They use standard web APIs only: fetch, Web Streams, Web Crypto
and AbortSignal, plus IndexedDB in a browser for sessions.
The client talks to a server over HTTPS. It refuses an http:// address unless you set allowInsecureHttp, which is
meant for a development server on your own machine. Sign-in, loginWithPassword, listModels and createAgent
send a password or a token: they refuse http:// to another machine unless you set allowInsecureHttp for them
too, and allow it to this machine (localhost, 127.0.0.1, ::1).
Dependencies¶
| Package | Depends on |
|---|---|
@fadenstack/client |
Nothing |
@fadenstack/agents |
@fadenstack/client |
@fadenstack/ui |
@fadenstack/agents, @fadenstack/client, and marked for Markdown |
@fadenstack/ui-web |
@fadenstack/ui and @fadenstack/agents |
@fadenstack/ui-react |
The four packages above, with React and React DOM 18.2 or later as peer dependencies |
@fadenstack/ui-vue |
@fadenstack/ui, @fadenstack/ui-web and the two below them, with Vue 3.5 or later as a peer dependency |
@fadenstack/testing |
@fadenstack/client; @fadenstack/agents and @fadenstack/provenance as optional peer dependencies |
@fadenstack/provenance |
@fadenstack/agents, @fadenstack/client |
@fadenstack/skills |
@fadenstack/agents, @fadenstack/client |
@fadenstack/mcp |
@fadenstack/agents, @fadenstack/client, and @modelcontextprotocol/client |
Install¶
Install the packages you need from npm, by name:
Add @fadenstack/ui, @fadenstack/ui-web and @fadenstack/ui-react or @fadenstack/ui-vue for the
chat panel. Add @fadenstack/testing as a development
dependency for testing without a server. The packages are released together, with one version; keep them
on the same version.
From source¶
To try changes that are not released yet, build the packages from source and add them to your project. You need Node.js 24 or later and git:
git clone https://github.com/fadenstack/fadenstack-sdk-typescript.git
cd fadenstack-sdk-typescript
npm install
npm run build
Then add the packages you need to your project, in one of two ways.
Pack each package into a .tgz file and install the files. Your project gets its own copy, as it would from npm.
# in fadenstack-sdk-typescript
mkdir ../fadenstack-packages
npm pack --workspaces --pack-destination ../fadenstack-packages
# in your project
npm install ../fadenstack-packages/fadenstack-client-<version>.tgz ../fadenstack-packages/fadenstack-agents-<version>.tgz
<version> is the version in the packages' package.json; npm pack names each file after it.
Install packages that depend on each other in one command. npm then finds @fadenstack/client among the files
instead of looking for it on npm.
Install the package folders. npm links them, so your project picks up the next npm run build in the SDK without
installing again.
# in your project
npm install ../fadenstack-sdk-typescript/packages/client ../fadenstack-sdk-typescript/packages/agents
Linked packages resolve their own imports from the SDK's node_modules. If you link @fadenstack/ui-react, make
your bundler use a single copy of React, for example with Vite's resolve.dedupe.
A complete example¶
This Node script signs in to the agent my-assistant, gives it one tool, and prints the answer as it streams. It
reads the user's e-mail and password from the environment.
import { FadenstackClient, loginWithPassword } from "@fadenstack/client";
import { FadenstackAgent, defineTool } from "@fadenstack/agents";
const serverUrl = "https://ai.example.internal";
// A host tool: something your application can do for the agent.
const readTicket = defineTool<{ id: string }>({
name: "read_ticket",
description: "Reads a support ticket by its id.",
toolClass: "read",
parameters: {
type: "object",
properties: { id: { type: "string", description: "The ticket id, e.g. T-1042." } },
required: ["id"],
},
run: ({ id }) => `Ticket ${id}: the printer on floor 2 jams on A3 paper.`,
});
// A client for one agent. Here the sign-in is kept in memory, for as long as the process runs.
const { client, tokens } = FadenstackClient.forAgent({ serverUrl, agent: "my-assistant" });
if (!(await tokens.isSignedIn())) {
const login = await loginWithPassword({
apiUrl: serverUrl,
email: process.env.FADEN_EMAIL ?? "",
password: process.env.FADEN_PASSWORD ?? "",
});
await tokens.signIn(login, "Ticket script");
}
const agent = FadenstackAgent.createBuilder().useClient(client).addTools(readTicket).build();
const session = await agent.startSession();
for await (const event of session.stream("What is ticket T-1042 about?")) {
if (event.type === "text") process.stdout.write(event.text);
if (event.type === "turn_completed") console.log(`\n(${event.result.outcome})`);
}
read_ticket only reads, so it runs without asking. A tool that changes something asks first, and without an
approval handler the SDK declines it. See Tools and approvals.
Where next¶
- Build an agent: the client, signing in, the builder, sessions and streaming.
- Tools and approvals: host tools, tool classes, tool modes and approvals.
- Approvals: the levels, standing approvals, the never-skip list, restarts and reasons.
- Host commands and central policy: host tools the person starts, and the fresh policy check around every host tool call.
- Outcomes and errors: how a turn ends, and what is thrown.
- Sessions on the device: where conversations are kept, and for how long.
- Data on the device: every database the SDK writes, how long it keeps it, and what the server keeps.
- The chat panel: a ready-made chat UI for React, and view models for other frameworks.
- Connecting an agent: the connection wizard, to a server or the person's own AI.
- Skills: skills on the device, the rules that pick them, the editor and its security rules.
- Testing without a server: the fake server in
@fadenstack/testing. - Plain chat completions: the gateway's chat without an agent.
- Hosting: where the SDK runs, a web page, a browser extension or Node, and what differs.
- Extending: modules, stages, tool sources, tool services and renderers.
- Local MCP servers: the person's own MCP servers over HTTP, plain http on the local network behind a switch, the class of their tools, the Tools view.
- Local tools: tools on request, and
find_tool. - Libraries: what each package is for.
- Samples: the live check against a server.
- Parity with the .NET SDK: each feature, by its name in both SDKs.