fishaudio · Him188 · Aug 9, 2026 · Aug 9, 2026
diff --git a/agents/build/configuration.mdx b/agents/build/configuration.mdx
@@ -8,7 +8,7 @@
 
 ## System prompt
 
-The system prompt sets the personality, goals, and guardrails that steer every reply. It is capped at **4,000 characters** — the Builder stops input at the limit, and the API rejects longer prompts with `422 Unprocessable Entity`.
+The system prompt sets the personality, goals, and guardrails that steer every reply. It is capped at **4,000 tokens** — the API rejects longer prompts with `422 Unprocessable Entity`. Keeping it under **2,000 tokens** is recommended: shorter prompts cut latency and cost, and hold the model's attention better.
 
 <Tip>
 Keep the prompt focused:
@@ -68,7 +68,7 @@

 `conversation.timezone` is the default IANA timezone (like `Asia/Shanghai`) the agent uses for dates and times in conversation. Leave it empty for **automatic** — each session follows the caller's device or phone number, falling back to UTC. Set one when your agent serves a single region regardless of who calls. A per-session `timezone` on the [session request](/agents/build/time-timezone) overrides this. See [Time & timezone](/agents/build/time-timezone) for the full resolution order.

 ## Autosave and publishing

 There is no Save button. Each change is written to the agent's draft moments after you stop editing, and the **Saving… / Saved** indicator at the bottom-left of the page shows the current state. If a save fails, the Builder tells you and keeps your pending edits so nothing is lost.

@@ -123,7 +123,7 @@
   }'
 ```
 
-The response includes the draft's new `config_hash`. Values outside the documented limits — a system prompt over 4,000 characters, `max_duration_seconds` outside 60–3600 — are rejected with `422 Unprocessable Entity` and the draft is left unchanged.
+The response includes the draft's new `config_hash`. Values outside the documented limits — a system prompt over 4,000 tokens, `max_duration_seconds` outside 60–3600 — are rejected with `422 Unprocessable Entity` and the draft is left unchanged.
 
 ### Config sections
 

diff --git a/agents/deploy/authenticated-sessions.mdx b/agents/deploy/authenticated-sessions.mdx
@@ -18,7 +18,7 @@
 <Note>
  No backend, and anyone may talk to the agent? A [public
  agent](/agents/deploy/public-agents) lets the SDK create sessions with just an
  `agentId` — no token involved, gated by an origin allowlist and rate limits.
 </Note>

 ## Create a token on your backend
@@ -109,7 +109,7 @@

 <Note>
  `overrides`, `dynamic_variables`, `language`, `tool_events`, `timezone`, and
  `world_context` belong in your backend's creation request — the SDK forwards
  these options only in [public agent](/agents/deploy/public-agents) mode.
 </Note>

@@ -118,12 +118,12 @@
 | Field               | Type              | Description                                                                                                                                                                                                                                                                               |
 | ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `agent_id`          | string, required  | The agent to talk to. It must have a [published version](/agents/deploy/versions-publishing).                                                                                                                                                                                             |
 | `name`              | string, optional  | Display name for this session in the console's Conversations list, up to 128 characters. Omit it to show the session's start time instead. API-key requests only — keyless (public) creation rejects it with `400`.                                                                       |
 | `overrides`         | object, optional  | Replace parts of the published configuration for this session — see [Overrides](#overrides).                                                                                                                                                                                              |
 | `dynamic_variables` | object, optional  | Up to 50 entries of string, number, or boolean values, substituted into `{{placeholders}}`. See [Dynamic variables](/agents/build/dynamic-variables).                                                                                                                                     |
 | `tool_events`       | boolean, optional | Stream tool lifecycle events (`toolCallStarted` / `toolCallCompleted` / `toolCallFailed`) to the client. Default `true`; set `false` to keep tool inputs and outputs off the client.                                                                                                      |
 | `end_user_id`       | string, optional  | Your identifier for the end user, for attribution in [conversation history](/agents/monitor/conversation-history).                                                                                                                                                                        |
 | `metadata`          | object, optional  | Your own key-value namespace. Stored and returned verbatim on session queries and webhooks — never read or interpreted by the platform.                                                                                                                                                   |
 | `record_audio`      | boolean, optional | Whether to record this session's audio. Overrides the agent's [recording setting](/agents/monitor/conversation-history#what-gets-stored) for this session only — it never changes the agent; omit it to use the agent's configuration.                                                    |
 | `timezone`          | string, optional  | IANA timezone (like `Asia/Shanghai`) for the agent's sense of local time. Invalid names are rejected with `422`. See [Time & timezone](/agents/build/time-timezone).                                                                                                                      |
 | `client_timezone`   | string, optional  | The end user's browser timezone, filled automatically by the SDK in public-agent mode. A hint, not a demand: it applies only when neither `timezone` nor the agent's configured timezone is set, and invalid values are ignored. See the [resolution order](/agents/build/time-timezone). |
@@ -139,7 +139,7 @@
 | ---------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `first_message`        | string, up to 10,000 characters          | The agent opens with exactly this text, spoken verbatim — whatever first-message mode the configuration sets. `{{placeholders}}` render inside it.                                                                |
 | `first_message_prompt` | string, up to 10,000 characters          | Instructions the agent generates its opener from, replacing the configured first-message behavior. `{{placeholders}}` render inside it. Mutually exclusive with `first_message` — sending both is `422`.          |
-| `system_prompt`        | string, up to 8,000 characters           | Replaces the configured system prompt entirely. `{{placeholders}}` render inside it.                                                                                                                              |
+| `system_prompt`        | string, up to 4,000 tokens               | Replaces the configured system prompt entirely, under the same token budget. `{{placeholders}}` render inside it.                                                                                                 |
 | `voice_id`             | string                                   | The voice the agent speaks with — any [voice model id](/agents/build/voice-language#use-any-voice-model) from the Voice Library. Voices bias pronunciation toward their own language, so pair it with `language`. |
 | `language`             | `en`, `ja`, `zh`, `ko`, `es`, `fr`, `de` | Pins the conversation language, taking precedence over the configured [speaking language](/agents/build/voice-language#speaking-language).                                       |
 
@@ -148,7 +148,7 @@
  "agent_id": "YOUR_AGENT_ID",
  "overrides": {
    "first_message": "Welcome back, {{name}} — picking up where we left off.",
    "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
    "language": "ja"
  }
 }
@@ -215,7 +215,7 @@

 | Status | Meaning                                                                                                                                       |
 | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `400`  | An `overrides` field is not enabled for this agent, or a keyless request sent an override [public sessions don't accept](#overrides).         |
 | `401`  | Invalid API key. A request with no `Authorization` header at all is treated as a public-agent request instead.                                |
 | `402`  | Quota exceeded.                                                                                                                               |
 | `403`  | Public-agent request rejected: the agent is not public, or the page's `Origin` is not on the allow-list.                                      |

diff --git a/agents/quickstart.mdx b/agents/quickstart.mdx
@@ -18,7 +18,7 @@ Build a voice agent and talk to it in a few minutes. Use the console for a no-co
         Go to [Agents](https://fish.audio/app/agents) and click **New agent**. Give it a name — you land in the Builder immediately.
       </Step>
       <Step title="Write the system prompt">
-        On the **Configuration** page, write the system prompt that defines who your agent is and how it should behave (up to 4,000 characters). Optionally set a **First message** so the agent opens the conversation.
+        On the **Configuration** page, write the system prompt that defines who your agent is and how it should behave (up to 4,000 tokens). Optionally set a **First message** so the agent opens the conversation.
 
         Edits save automatically as a draft — there is no Save button.
       </Step>
@@ -63,7 +63,7 @@ Build a voice agent and talk to it in a few minutes. Use the console for a no-co
         The response includes the agent's `agent_id` — use it as `$AGENT_ID` below. `voice_id` accepts any voice model id from the [Voice Library](/features/manage-voices).
 
         <Note>
-        `system_prompt` is limited to 4,000 characters; longer prompts return `422`.
+        `system_prompt` is limited to 4,000 tokens; longer prompts return `422`. Keeping it under 2,000 tokens is recommended for latency and cost.
         </Note>
       </Step>
       <Step title="Publish it">

diff --git a/api-reference/agent-errors.mdx b/api-reference/agent-errors.mdx
@@ -17,10 +17,10 @@
   ```json
   [
     {
-      "type": "string_too_long",
+      "type": "value_error",
       "loc": ["body", "prompt", "system_prompt"],
-      "msg": "String should have at most 4000 characters",
-      "ctx": { "max_length": 4000 }
+      "msg": "Value error, system_prompt exceeds 4000 tokens (got 5001)",
+      "ctx": { "error": "system_prompt exceeds 4000 tokens (got 5001)" }
     }
   ]
   ```
@@ -42,11 +42,11 @@
 | `422`  | Field-level validation failed                                            | Fix the fields listed in the error array.                                                                        |
 | `429`  | Public session creation is rate limited                                  | Back off and retry; per-agent and per-IP windows apply to [public agents](/agents/deploy/public-agents) only.    |
 | `502`  | An upstream dependency (conversation gateway, telephony provider) failed | Retry; for a failed phone-number purchase the row stays visible with status `error` and is safe to release.      |
 | `503`  | A platform dependency is temporarily unavailable                         | Retry with backoff.                                                                                              |

 ## 400 vs 422

 `422` is field-level validation: unknown fields (the public surface rejects them), length caps, enum values, invalid IANA timezones, dynamic-variable naming. `400` is semantic: an [override](/agents/deploy/authenticated-sessions#overrides) not enabled for the agent, mutually exclusive pagination parameters (`page` + `cursor`), an undecodable cursor, a page offset past 100,000 rows, or a knowledge upload that isn't UTF-8 plain text.

 Two quirks worth coding around:

@@ -87,7 +87,7 @@

 ## 5xx

 `502` names the failing upstream in the message: the conversation gateway (`Agent gateway is unreachable`) or the telephony provider (`Twilio refused the request: …`). Retrying is safe — a failed phone-number purchase leaves the row visible with status `error`, refunds the day charge, and can be released; a failed release keeps the number live so releasing again retries. `503` means a platform dependency was briefly unreachable; retry with backoff.

 ## Going further