Skip to content
Merged
Changes from all commits
Commits
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
14 changes: 7 additions & 7 deletions agents/deploy/protocol.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "Wire Protocol"
description: "The realtime message contract between clients and agent sessions — for platforms the SDKs don't cover"

Check warning on line 3 in agents/deploy/protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

agents/deploy/protocol.mdx#L3

Did you really mean 'realtime'?

Check warning on line 3 in agents/deploy/protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

agents/deploy/protocol.mdx#L3

Did you really mean 'SDKs'?
icon: "network-wired"
---

Everything the SDKs do rides a small, versioned wire protocol: two JSON message channels, plus the transport's standard transcription and state mechanisms. This page documents that contract for consumers that cannot use the SDKs — custom native stacks or ports to new platforms.

Check warning on line 7 in agents/deploy/protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

agents/deploy/protocol.mdx#L7

Did you really mean 'SDKs'?

Check warning on line 7 in agents/deploy/protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

agents/deploy/protocol.mdx#L7

Did you really mean 'SDKs'?

<Note>
This is an escape hatch. For web and React apps, use the [Web
Expand All @@ -15,7 +15,7 @@

## The protocol package

Every message shape on this page is published as TypeScript definitions in `@fishaudio/agent-protocol` — zero runtime dependencies. This page documents protocol revision **0.3.0**; the npm package is versioned independently. The package is the source of truth for shapes; this page fixes the semantics.
Every message shape on this page is published as TypeScript definitions in `@fishaudio/agent-protocol` — zero runtime dependencies. This page documents the protocol as of package version **0.1.0**. The package is the source of truth for shapes; this page fixes the semantics.

```bash npm
npm install @fishaudio/agent-protocol
Expand Down Expand Up @@ -130,7 +130,7 @@
}
```

- `user.message` gets **no server echo** — you already hold the text, so render the bubble locally. Add `"audio": false` (protocol 0.3.0) to have the agent answer that turn in text only: no speech is synthesized and the reply arrives over transcription.
- `user.message` gets **no server echo** — you already hold the text, so render the bubble locally. Add `"audio": false` to have the agent answer that turn in text only: no speech is synthesized and the reply arrives over transcription.
- `client_tool.result` may carry `result` (any JSON value) or `"isError": true` to report the tool as failed to the model. Results for unknown or already-settled `callId`s are ignored.

## Transcription and agent state
Expand All @@ -142,7 +142,7 @@
- Agent segments stream incrementally, paced to audio playback. An interrupted segment closes containing only the words actually spoken — there is no residual text.
- User segments are interim until final; each interim update **replaces the entire segment text** under the same segment id.

**Agent state** is published as the sticky `lk.agent.state` participant attribute with values `initializing`, `idle`, `listening`, `thinking`, and `speaking`. Sticky means a client that connects late or reconnects reads the current value immediately. The SDKs derive their three public modes from this attribute plus transcript segment open/close.

Check warning on line 145 in agents/deploy/protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

agents/deploy/protocol.mdx#L145

Did you really mean 'SDKs'?

## Compatibility rules

Expand All @@ -150,12 +150,12 @@
2. **Evolution is additive-only.** Published fields never change name or meaning and are never removed; new fields are always optional. A semantic change ships as a new `type`.
3. **No replay.** Data-channel delivery is reliable and ordered within a connection, but after a reconnect or late join, missed messages are gone — never wait for history. Tool terminal messages repeat their identifying fields, and the state attribute is sticky, precisely to soften this.

## Protocol revision history
## Version history

| Revision | Changes |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| 0.2.0 | Added tool lifecycle events (`tool.started` / `tool.completed` / `tool.failed`) and the `tool_events` session option |
| 0.3.0 (current) | Added the optional `audio` flag on `user.message` for per-turn text-only replies |
| Version | Changes |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.0.1 | Initial public release — the complete message set on this page, including tool lifecycle events and the optional `audio` flag on `user.message` |
| 0.1.0 (current) | Revised the session-creation `SessionOverrides` shape; realtime messages unchanged |

Check warning on line 158 in agents/deploy/protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

agents/deploy/protocol.mdx#L158

Did you really mean 'realtime'?

## Going further

Expand Down
Loading