Skip to content

sdk: add spawn/release lifecycle hooks in TS and Python #477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
willwashburn merged 4 commits into from
Mar 4, 2026
Merged

sdk: add spawn/release lifecycle hooks in TS and Python #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e5ae266
sdk: add spawn/release lifecycle hooks in TS and Python
willwashburn Mar 4, 2026
bcdd0af
sdk: await async lifecycle hooks for spawn and release
willwashburn Mar 4, 2026
40177c8
sdk-py: align shorthand spawn hook ordering and document ReleaseOptions
willwashburn Mar 4, 2026
1a88e78
sdk: align release hook ordering with startup failures
willwashburn Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions docs/reference/sdk-py.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,14 +47,17 @@ agent = await relay.gemini.spawn(name="Researcher", model=Models.Gemini.GEMINI_2

**Spawn keyword arguments:**

| Parameter | Type | Description |
| ---------- | --------------- | --------------------------------- |
| `name` | `str` | Agent name (defaults to CLI name) |
| `model` | `str` | Model to use (see Models below) |
| `task` | `str` | Initial task / prompt |
| `channels` | `list[str]` | Channels to join |
| `args` | `list[str]` | Extra CLI arguments |
| `cwd` | `str` | Working directory override |
| Parameter | Type | Description |
| ------------ | ----------- | ---------------------------------------- |
| `name` | `str` | Agent name (defaults to CLI name) |
| `model` | `str` | Model to use (see Models below) |
| `task` | `str` | Initial task / prompt |
| `channels` | `list[str]` | Channels to join |
| `args` | `list[str]` | Extra CLI arguments |
| `cwd` | `str` | Working directory override |
| `on_start` | `Callable` | Sync/async callback before spawn request |
| `on_success` | `Callable` | Sync/async callback after spawn succeeds |
| `on_error` | `Callable` | Sync/async callback when spawn fails |

### `relay.spawn(name, cli, task?, options?)`

Expand Down Expand Up @@ -94,7 +97,7 @@ class Agent:
exit_reason: str | None

async def send_message(*, to: str, text: str, thread_id=None, priority=None, data=None) -> Message
async def release(reason=None) -> None
async def release(reason=None, *, on_start=None, on_success=None, on_error=None) -> None
async def wait_for_ready(timeout_ms=60_000) -> None
async def wait_for_exit(timeout_ms=None) -> str # "exited" | "timeout" | "released"
async def wait_for_idle(timeout_ms=None) -> str # "idle" | "timeout" | "exited"
Expand Down
72 changes: 43 additions & 29 deletions docs/reference/sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,18 @@ const relay = new AgentRelay(options?: AgentRelayOptions);

### AgentRelayOptions

| Property | Type | Description | Default |
| -------------------- | --------------------- | ------------------------------------------------------------- | -------------------- |
| `binaryPath` | `string` | Path to the broker binary | Auto-resolved |
| `binaryArgs` | `string[]` | Extra arguments for the broker process | None |
| `brokerName` | `string` | Name for the broker instance | Auto-generated |
| `channels` | `string[]` | Default channels agents are joined to on spawn | `['general']` |
| `cwd` | `string` | Working directory for the broker and spawned agents | `process.cwd()` |
| `env` | `NodeJS.ProcessEnv` | Environment variables passed to the broker | Inherited |
| `requestTimeoutMs` | `number` | Timeout for broker requests | `30000` |
| `shutdownTimeoutMs` | `number` | Timeout when shutting down | `10000` |
| `workspaceName` | `string` | Name for the auto-created Relaycast workspace | Random |
| `relaycastBaseUrl` | `string` | Base URL for the Relaycast API | `https://api.relaycast.dev` |
| Property | Type | Description | Default |
| ------------------- | ------------------- | --------------------------------------------------- | --------------------------- |
| `binaryPath` | `string` | Path to the broker binary | Auto-resolved |
| `binaryArgs` | `string[]` | Extra arguments for the broker process | None |
| `brokerName` | `string` | Name for the broker instance | Auto-generated |
| `channels` | `string[]` | Default channels agents are joined to on spawn | `['general']` |
| `cwd` | `string` | Working directory for the broker and spawned agents | `process.cwd()` |
| `env` | `NodeJS.ProcessEnv` | Environment variables passed to the broker | Inherited |
| `requestTimeoutMs` | `number` | Timeout for broker requests | `30000` |
| `shutdownTimeoutMs` | `number` | Timeout when shutting down | `10000` |
| `workspaceName` | `string` | Name for the auto-created Relaycast workspace | Random |
| `relaycastBaseUrl` | `string` | Base URL for the Relaycast API | `https://api.relaycast.dev` |

---

Expand All @@ -50,14 +50,17 @@ const agent = await relay.codex.spawn(options?)

**Spawn options:**

| Property | Type | Description |
| ---------- | ---------- | ------------------------------------- |
| `name` | `string` | Agent name (defaults to CLI name) |
| `model` | `string` | Model to use (see Models below) |
| `task` | `string` | Initial task / prompt |
| `channels` | `string[]` | Channels to join |
| `args` | `string[]` | Extra CLI arguments |
| `cwd` | `string` | Working directory override |
| Property | Type | Description |
| ----------- | ---------- | ------------------------------------------------ |
| `name` | `string` | Agent name (defaults to CLI name) |
| `model` | `string` | Model to use (see Models below) |
| `task` | `string` | Initial task / prompt |
| `channels` | `string[]` | Channels to join |
| `args` | `string[]` | Extra CLI arguments |
| `cwd` | `string` | Working directory override |
| `onStart` | `function` | Sync/async callback before spawn request is sent |
| `onSuccess` | `function` | Sync/async callback after spawn succeeds |
| `onError` | `function` | Sync/async callback when spawn fails |

### `relay.spawn(name, cli, task?, options?)`

Expand Down Expand Up @@ -105,14 +108,25 @@ interface Agent {
data?: Record<string, unknown>;
}): Promise<Message>;

release(reason?: string): Promise<void>;
release(reasonOrOptions?: string | ReleaseOptions): Promise<void>;
Copy link

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The release(reasonOrOptions?: string | ReleaseOptions) signature references ReleaseOptions, but the documentation does not describe the shape of this type (its reason, onStart, onSuccess, and onError fields). Users who only refer to the reference docs won't know how to use the hook-based overload. Consider adding a ReleaseOptions properties table similar to the spawn options table, or at least a brief inline description near the Agent section.

Copilot uses AI. Check for mistakes.
waitForReady(timeoutMs?: number): Promise<void>;
waitForExit(timeoutMs?: number): Promise<'exited' | 'timeout' | 'released'>;
waitForIdle(timeoutMs?: number): Promise<'idle' | 'timeout' | 'exited'>;
onOutput(callback: (chunk: string) => void): () => void; // returns unsubscribe
}
```

### `ReleaseOptions`

`agent.release(...)` accepts either a reason string or a `ReleaseOptions` object:

| Property | Type | Description |
| ----------- | ---------- | -------------------------------------------------- |
| `reason` | `string` | Optional release reason sent to the broker |
| `onStart` | `function` | Sync/async callback before release request is sent |
| `onSuccess` | `function` | Sync/async callback after release succeeds |
| `onError` | `function` | Sync/async callback when release fails |

---

## Human Handles
Expand Down Expand Up @@ -249,16 +263,16 @@ await relay.shutdown();
import { Models } from '@agent-relay/sdk';

// Claude
Models.Claude.OPUS // 'opus'
Models.Claude.SONNET // 'sonnet'
Models.Claude.HAIKU // 'haiku'
Models.Claude.OPUS; // 'opus'
Models.Claude.SONNET; // 'sonnet'
Models.Claude.HAIKU; // 'haiku'

// Codex
Models.Codex.GPT_5_3_CODEX // 'gpt-5.3-codex'
Models.Codex.GPT_5_2_CODEX // 'gpt-5.2-codex' (default)
Models.Codex.GPT_5_3_CODEX_SPARK // 'gpt-5.3-codex-spark'
Models.Codex.GPT_5_1_CODEX_MAX // 'gpt-5.1-codex-max'
Models.Codex.GPT_5_1_CODEX_MINI // 'gpt-5.1-codex-mini'
Models.Codex.GPT_5_3_CODEX; // 'gpt-5.3-codex'
Models.Codex.GPT_5_2_CODEX; // 'gpt-5.2-codex' (default)
Models.Codex.GPT_5_3_CODEX_SPARK; // 'gpt-5.3-codex-spark'
Models.Codex.GPT_5_1_CODEX_MAX; // 'gpt-5.1-codex-max'
Models.Codex.GPT_5_1_CODEX_MINI; // 'gpt-5.1-codex-mini'
```

---
Expand Down
16 changes: 15 additions & 1 deletion packages/sdk-py/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,21 @@ Use runtime-specific spawners:
await relay.claude.spawn(name="Agent1", model=Models.Claude.SONNET, channels=["dev"], task="...")
await relay.codex.spawn(name="Agent2", model=Models.Codex.GPT_5_3_CODEX, channels=["dev"], task="...")
await relay.gemini.spawn(name="Agent3", model=Models.Gemini.GEMINI_2_5_PRO, channels=["dev"], task="...")

worker = await relay.claude.spawn(
name="HookedWorker",
channels=["dev"],
# Lifecycle hooks can be sync or async callables.
on_start=lambda ctx: print(f"spawning {ctx['name']}"),
on_success=lambda ctx: print(f"spawned {ctx['name']} ({ctx['runtime']})"),
on_error=lambda ctx: print(f"failed to spawn {ctx['name']}: {ctx['error']}"),
)

await worker.release(
"done",
on_start=lambda ctx: print(f"releasing {ctx['name']}"),
on_success=lambda ctx: print(f"released {ctx['name']}"),
)
```

### Sending Messages
Expand Down Expand Up @@ -108,7 +123,6 @@ Models.Gemini.GEMINI_2_5_PRO
Models.Gemini.GEMINI_2_5_FLASH
```


## License

Apache-2.0
Loading
Loading