SDK reference

SDK reference (TypeScript)

The full public surface of @relayhq/sdk: createAgent, builtin tools, custom tools, memory, and the event stream you iterate. For Python, see Languages & SDKs.

Install

@relayhq/sdk·View on npm ↗Source ↗

npm install @relayhq/sdk
# or
pnpm add @relayhq/sdk
# or
yarn add @relayhq/sdk

Zero runtime dependencies. ESM only. Works in Node 18+, Bun, Deno (via npm:), Cloudflare Workers, and the browser.

createAgent

Returns an Agent. All configuration is one object. There is no second method to call before .run().

example.ts

import { createAgent, builtin, tool } from "@relayhq/sdk";

const agent = createAgent({
  apiKey: process.env.RELAY_API_KEY!,
  baseUrl: "http://localhost:4000",  // your control plane
  model: "claude-sonnet-4-6",
  system: "You are a helpful assistant.",
  tools: [builtin.calculator, myCustomTool],
  memory: { namespace: `user:${userId}` },
});

Options

Field	Type	Description
model	ModelId	Required. e.g. `claude-sonnet-4-6`, `gpt-4o-mini`, `o3-mini`, or `openai:llama3.1` for an OpenAI-compatible endpoint.
apiKey	string	Your `relay_live_…` tenant key. Falls back to `process.env.RELAY_API_KEY`.
baseUrl	string	Control plane URL. Defaults to `process.env.RELAY_URL` then `http://localhost:4000`.
system	string	System prompt prepended to every run.
tools	Tool[]	Mix of `builtin.*` and `tool(...)` values.
memory	boolean \| { namespace }	`true` uses namespace `"default"`; `{ namespace }` scopes per-user/per-thread.

agent.run(input)

Returns an AsyncIterable<AgentEvent>. The stream stays open until the model is done or errors.

const stream = agent.run("What is 23 * 47?");

for await (const event of stream) {
  switch (event.type) {
    case "token":
      process.stdout.write(event.text);
      break;
    case "tool_call":
      console.log(`→ ${event.name}(${JSON.stringify(event.input)})`);
      break;
    case "tool_result":
      console.log(`← ${JSON.stringify(event.output)}`);
      break;
    case "done":
      console.log("usage", event.usage);
      break;
    case "error":
      console.error(event.message);
      break;
  }
}

Event shapes

type AgentEvent =
  | { type: "token";       text: string }
  | { type: "tool_call";   id: string; name: string; input: unknown }
  | { type: "tool_result"; id: string; output: unknown }
  | { type: "done";        output: string; usage?: { input_tokens; output_tokens } }
  | { type: "error";       message: string };

Built-in tools

Built-in tools execute server-side in the Go runtime. Zero round-trip to your code.

import { createAgent, builtin } from "@relayhq/sdk";

const agent = createAgent({
  model: "claude-sonnet-4-6",
  tools: [builtin.calculator],
});

Name	Input	Returns
calculator	{ a: number, b: number, op: "+" \| "-" \| "*" \| "/" }	number

Custom function tools

Your handler runs in your process. Relay orchestrates the call, pauses the LLM, waits for your response, then continues.

tools.ts

import { tool } from "@relayhq/sdk";

export const getUser = tool({
  name: "get_user",
  description: "Look up a user by id",
  inputSchema: {
    type: "object",
    properties: { id: { type: "string" } },
    required: ["id"],
    additionalProperties: false,
  },
  async handler({ id }: { id: string }) {
    return await db.users.findById(id);  // your code, your process
  },
});

The handler can be async. Whatever it returns gets JSON-serialized and shipped to the model as the tool result. If it throws, the error message goes back as "error: <message>" — the model sees it and usually self-corrects.

Full protocol (long-poll callback dance, retries, timeout) lives in Tools.

Memory

Flip the option and the agent recalls relevant past turns automatically. Embeddings happen server-side with text-embedding-3-small; retrieval is cosine-similarity top-5; storage is pgvector.

const agent = createAgent({
  model: "gpt-4o-mini",
  memory: { namespace: `user:${userId}` },
});

await agent.run("I'm Kevin. I drink only espresso.");
// Later, even in a different process:
for await (const e of agent.run("What's my coffee?")) {
  // → "Espresso, Kevin."
}

Exports

Name	Kind	Purpose
createAgent	function	Build an agent.
tool	function	Define a custom function tool.
builtin	object	Registry of built-in tools. Today: `builtin.calculator`.
Agent, AgentConfig, AgentEvent, ModelId, AnthropicModel, OpenAIModel, Tool, BuiltinTool, FunctionTool, MemoryConfig	type	Strongly-typed everything.