Build agents in TypeScript with the Suede AI SDK and CLI

How do I install the Suede AI SDK?#

Run one npm install. The package ships the SDK and the suede command, written in TypeScript with full type definitions, and it pulls in no model SDKs: Agent Studio provides the model.

npm install @suedeai/agents
npx suede init          # writes agent.ts, package.json, .gitignore and .suede/config.json
npx suede login <key>   # your workspace key from the Workspace page

What does an agent look like in code?#

An agent is a name, a list of triggers and an async run function. defineAgent validates the definition and freezes it, so a bad cron string or an empty trigger list fails on your machine instead of in production.

import { defineAgent, schedule, manual, suede } from "@suedeai/agents";

export default defineAgent({
  name: "price-watcher",
  description: "Reads a product page excerpt, remembers the price, flags a drop.",
  triggers: [schedule("0 13 * * *"), manual()],
  async run({ input, memory }) {
    const out = await suede.llm({
      system: "Extract the price as a number.",
      prompt: String(input ?? ""),
    });
    const last = await memory.get<number>("lastPrice");
    await memory.set("lastPrice", Number(out.text));
    return { price: out.text, dropped: last !== undefined && Number(out.text) < last };
  },
});

• suede.llm({ system, prompt }) calls the Agent Studio model gateway and returns { text }, billed to your usage credit.
• suede.run(nodeType, config) calls any Agent Studio node from code and returns { output }.
• memory.get and memory.set keep state between runs; locally they write to .suede/memory.json.
• A gateway failure throws a typed GatewayError whose status is 401 (bad key), 402 (out of credit) or 429 (rate limited).

Which triggers can start a code agent?#

Four trigger helpers cover every way work arrives. Combine them freely: one agent can run on a schedule and on demand.

Which CLI commands does Agent Studio support?#

How do I develop and self-host an agent?#

Set SUEDE_GATEWAY_STUB=1 and suede.llm echoes your prompt with no network call and no key, so you iterate offline at zero cost. When you want your own box to do the work, serve(agent, { port }) starts a plain Node HTTP server with the same POST /run and GET /manifest routes.

SUEDE_GATEWAY_STUB=1 npx suede dev

curl -X POST http://localhost:3001/run \
  -H 'content-type: application/json' \
  -d '{ "input": "Widget Pro, now $89" }'

npx suede link <slug> --url https://your-server.com/run
# prints SUEDE_RELAY_SECRET=<hex>   (save it now)

SUEDE_RELAY_SECRET=<hex> node dist/agent.js

Which environment variables does the SDK read?#