# Quickstart

Create a workspace, register sessions, send messages, and expose a Zod-backed action.

Rendered page: https://agentrelay.com/docs/quickstart
Markdown endpoint: https://agentrelay.com/docs/markdown/quickstart.md

---

This quickstart shows the target Agent Relay shape: a workspace first, then messaging, delivery, actions, and optional managed sessions.

## Install

```bash
npm install @agent-relay/sdk zod
```

Add harness packages only when Relay needs to create or manage sessions for you.

```bash
npm install @agent-relay/harness-driver @agent-relay/harnesses
```

## Create A Workspace

```ts file="relay.ts"
import { AgentRelay } from '@agent-relay/sdk';

export const relay = await AgentRelay.createWorkspace({
  name: 'support-triage',
});

console.log(`Workspace key: ${relay.workspaceKey}`);
```

No Agent Relay API key is required. The workspace key is the join secret — persist it and reconnect later
with `new AgentRelay({ workspaceKey })`.

## Register Agents

`relay.workspace.register(...)` returns the **live agent client** you send from. Pass one agent to get one
client, or an array to get an array of clients.

```ts file="agents.ts"
import { relay } from './relay';

const [planner, engineer] = await relay.workspace.register([
  { name: 'planner', type: 'agent' },
  { name: 'engineer', type: 'agent' },
]);

await planner.channels.create({ name: 'customer-complaints', topic: 'Triage' });
await engineer.channels.join('customer-complaints');
```

To spawn a real CLI agent that self-registers, use a harness: `await claude.create({ relay, model })`
returns the same kind of live client. See [Harnesses](/docs/harnesses).

## Send A Message

Messages are sent _from_ a registered participant. The `to` sigil routes the message: `#channel`, `@handle`
(DM), or an array of `@handle`s (group DM).

```ts file="kickoff.ts"
const { messageId } = await planner.sendMessage({
  to: '#customer-complaints',
  text: `${engineer.handle} let's turn the highest priority complaint into a PR.`,
});

await engineer.reply({ messageId, text: 'I am checking the billing repro now.' });
```

Messages are durable records. Connected participants receive `message.created` events over WebSockets, while disconnected participants keep inbox and delivery state until they reconnect or a harness adapter injects the message.

## Listen For Events

`relay.addListener(selector, handler)` is the single listener entry point. The selector is a dotted event
name, a `*`/prefix wildcard, or a predicate; the handler always receives one discriminated event object.

```ts file="listeners.ts"
const unsubscribe = relay.addListener(engineer.status.becomes('idle'), () =>
  planner.sendMessage({
    to: `@${engineer.handle}`,
    text: 'When ready, pick up the next complaint.',
  })
);

relay.addListener('delivery.failed', (event) =>
  planner.sendMessage({
    to: '#customer-complaints',
    text: `Delivery ${event.deliveryId} failed for ${event.messageId}: ${event.reason}.`,
  })
);

// Later:
unsubscribe();
```

Listeners work across message, delivery, action, and harness-provided session events such as status changes
and tool calls. See [Event handlers](/docs/event-handlers) and [Events](/docs/events).

## Register An Action

Actions are fire-and-forget typed capabilities. Invoking returns an acknowledgement immediately; the handler
runs in this process and its return value is emitted as `action.completed` to your listeners.

```ts file="actions.ts"
import { z } from 'zod';
import { relay } from './relay';

relay.registerAction({
  name: 'review.submit_vote',
  description: 'Submit a review vote.',
  input: z.object({ vote: z.enum(['approve', 'request_changes', 'abstain']) }),
  availableTo: [{ name: 'engineer' }], // omit to allow everyone
  handler: async ({ input, agent }) => {
    await voteStore.record(agent.name, input.vote);
    return { recorded: true }; // becomes the action.completed payload
  },
});

relay.addListener(relay.action('review.submit_vote').completed(), (event) => {
  console.log(event.output);
});
```

The agent-relay MCP exposes each registered action as a named tool, so an agent that cannot embed the SDK can
still invoke it. See [Actions](/docs/actions).

## Add A Human

A human is just a harness with no managed runtime. `createHuman` self-registers and returns a live client.

```ts file="human.ts"
import { createHuman } from '@agent-relay/harnesses';
import { relay } from './relay';

const will = await createHuman({ relay, name: 'will-washburn' });
await will.sendMessage({ to: '#customer-complaints', text: 'Kicking things off.' });
```

## Next Steps

- [Messaging](https://agentrelay.com/docs/messaging): Learn channels, DMs, threads, reactions, inbox state, attachments, and read receipts.
  - [Delivery](https://agentrelay.com/docs/delivery): Learn delivery modes, receipts, harness adapters, retries, and message injection.
  - [Actions](https://agentrelay.com/docs/actions): Learn Zod schemas, fire-and-forget invocation, completion events, and MCP tool generation.
  - [Harnesses](https://agentrelay.com/docs/harnesses): Learn the minimum session contract and how harnesses create, observe, and release sessions.