From f57cc5f5a2884f9b74bd3c7ac8391c63767c6d18 Mon Sep 17 00:00:00 2001 From: Him188 Date: Sun, 25 Oct 2026 20:16:43 +0900 Subject: [PATCH 1/3] docs(agents): time awareness is an agent setting, with a per-session override (FA-528) conversation.world_context on the configuration page, the agent-level and per-session switches on the time and timezone page, and the session and web SDK parameter tables. Co-Authored-By: Claude Fable 5.1 --- agents/build/configuration.mdx | 9 +++++++-- agents/build/time-timezone.mdx | 6 +++++- agents/deploy/authenticated-sessions.mdx | 2 +- agents/deploy/web-sdk.mdx | 2 +- 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/agents/build/configuration.mdx b/agents/build/configuration.mdx index 4c869a66..941f151b 100644 --- a/agents/build/configuration.mdx +++ b/agents/build/configuration.mdx @@ -93,6 +93,10 @@ Turn it off if callers should be able to interrupt the agent within those 3 seco `conversation.timezone` is the default IANA timezone (like `Asia/Tokyo`) 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. +### Time awareness + +`conversation.world_context` (default `true`) is what makes the agent time-aware: every session learns today's date when it starts and the current time before each reply, in the timezone above. In the Builder this is the **Current date & time** toggle next to the time zone. Turn it off when the agent must not know the real date, for example a role-play set on a fictional date or a prompt that states its own. It is the default for every session on every channel, and the only switch for phone calls, which the platform creates without a session request. A per-session `world_context` on the [session request](/agents/deploy/authenticated-sessions) overrides it in either direction. See [Time & timezone](/agents/build/time-timezone#turn-it-off). + ## 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. @@ -138,7 +142,8 @@ curl --request GET "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \ "interruption_ignore_phrases": [], "echo_guard": null, "speculative_response": true, - "timezone": "" + "timezone": "", + "world_context": true } } ``` @@ -168,7 +173,7 @@ The response includes the draft's new `config_hash`. Values outside the document | `prompt` | System prompt and first-message settings | This page | | `voice` | Voice profile, text-to-speech model, speaking language, and expressive mode | [Voice & language](/agents/build/voice-language) | | `asr` | Speech recognition model, multilingual recognition, strict language, and recognition keyterms | [Voice & language](/agents/build/voice-language#speech-recognition-model) | -| `conversation` | Call duration, turn-taking, interruption behavior, timezone, and storage | This page; storage in [Conversation history](/agents/monitor/conversation-history#what-gets-stored) | +| `conversation` | Call duration, turn-taking, interruption behavior, timezone, time awareness, and storage | This page; storage in [Conversation history](/agents/monitor/conversation-history#what-gets-stored) | | `tools` | Attached webhook tools and system tool switches | [Tools](/agents/build/tools) | | `knowledge_base` | Attached knowledge sources | [Knowledge base](/agents/build/knowledge-base) | | `analysis` | Post-call summary, data fields, and success criteria | [Post-call analysis](/agents/monitor/post-call-analysis) | diff --git a/agents/build/time-timezone.mdx b/agents/build/time-timezone.mdx index c1f0a959..79d7b02e 100644 --- a/agents/build/time-timezone.mdx +++ b/agents/build/time-timezone.mdx @@ -63,7 +63,11 @@ curl --request POST https://api.fish.audio/v1/agent/sessions \ ## Turn it off -Time awareness is on by default. To withhold both the date and the per-turn time from a session (for example a role-play agent set on a fictional date, or a test that must be reproducible), set `world_context: false` when creating the session: +Time awareness is on by default. Turn it off when the agent must not know the real date and time: a role-play agent set on a fictional date, a prompt that states its own date, or a test that must be reproducible. Off means neither the opening date line nor the per-turn time is injected. + +**For the whole agent**, switch off **Current date & time** in the Builder (**Configuration**, next to the time zone) or set `conversation.world_context: false` through the [config API](/agents/build/configuration#time-awareness). This becomes the default for every session of the agent on every channel, and it is the only switch for phone calls, which the platform creates without a session request. Publish the agent for the change to reach live traffic. + +**For one session**, set `world_context` when creating it. An explicit value overrides the agent's setting in either direction: `false` withholds the date and time from a time-aware agent, `true` restores them for one session of an agent that has them off. ```bash API (curl) diff --git a/agents/deploy/authenticated-sessions.mdx b/agents/deploy/authenticated-sessions.mdx index 6f81d583..b709d580 100644 --- a/agents/deploy/authenticated-sessions.mdx +++ b/agents/deploy/authenticated-sessions.mdx @@ -135,7 +135,7 @@ More on what the SDK can do once connected is in the [Web SDK](/agents/deploy/we | `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; omit it to use the agent's configuration. | | `timezone` | string, optional | IANA timezone (like `Asia/Tokyo`) 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 device timezone as an IANA name. A hint, not a demand: it applies only when neither `timezone` nor the agent's configured timezone is set, and invalid values are ignored. The SDK fills it automatically in public-agent mode. From your backend, forward the value from your client. See the [resolution order](/agents/build/time-timezone). | -| `world_context` | boolean, optional | Whether the agent knows the current date and time. Default `true`; set `false` to withhold both from this session. | +| `world_context` | boolean, optional | Whether the agent knows the current date and time. Omit it to follow the agent's [time awareness setting](/agents/build/configuration#time-awareness) (on by default). `false` withholds both from this session, `true` injects them even when the agent has them off. | Unknown fields (top-level or inside `overrides`) are rejected with `422`. diff --git a/agents/deploy/web-sdk.mdx b/agents/deploy/web-sdk.mdx index 6962b02f..9abc3331 100644 --- a/agents/deploy/web-sdk.mdx +++ b/agents/deploy/web-sdk.mdx @@ -71,7 +71,7 @@ const session = await AgentSession.start({ sessionToken }); for `overrides.language` (`agentId` mode only). Omit it to use the agent's configured [speaking language](/agents/build/voice-language#speaking-language); any other value is rejected with `422` | | `toolEvents` | `boolean` | Whether tool lifecycle events reach this client (default `true`; `agentId` mode only, with `sessionToken` your backend sets `tool_events`) | | `timezone` | `string` | IANA timezone for the agent's sense of local time: the top of the [resolution order](/agents/build/time-timezone), overriding the agent's configured timezone. When omitted, the SDK still sends the browser timezone as a lower-priority hint (`client_timezone`), which applies only if the agent has no timezone configured | -| `worldContext` | `boolean` | Whether the agent knows the current date and time (default `true`; `agentId` mode only, with `sessionToken` your backend sets `world_context`) | +| `worldContext` | `boolean` | Whether the agent knows the current date and time. Omit it to follow the agent's [time awareness setting](/agents/build/configuration#time-awareness). `false` withholds both for this session, `true` injects them even when the agent has them off (`agentId` mode only, with `sessionToken` your backend sets `world_context`) | | `endUserId` | `string` | Your identifier for the end user, stored on the session and echoed in [webhooks](/agents/monitor/webhooks) (`agentId` mode only; with `sessionToken` your backend sets `end_user_id`) | | `metadata` | `object` | Your own key-values, stored on the session record and returned verbatim (`agentId` mode only; with `sessionToken` your backend sets `metadata`) | | `microphone` | `boolean` | Capture the microphone on start (default `true`). `false` joins muted with no permission prompt, for text-first UIs; the first `setMicMuted(false)` captures it, so call that from a user gesture | From d38f126f067c43ab3bee8066c1bc980a37bdfe12 Mon Sep 17 00:00:00 2001 From: Him188 Date: Sun, 25 Oct 2026 20:22:13 +0900 Subject: [PATCH 2/3] chore: update OpenAPI schema Same refresh the nightly job commits, pulled so the schema check on this branch compares against the current https://api.fish.audio/openapi.json. Co-Authored-By: Claude Fable 5.1 --- api-reference/openapi.json | 158 ++++++++++++++++++++++++++++++++++++- 1 file changed, 157 insertions(+), 1 deletion(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index f1e2faf5..eb47d254 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -1749,6 +1749,13 @@ } ], "default": null + }, + "llm_endpoint_errors": { + "items": { + "$ref": "#/components/schemas/AgentSessionLlmEndpointError" + }, + "title": "Llm Endpoint Errors", + "type": "array" } }, "required": [ @@ -19071,6 +19078,114 @@ "title": "AgentSessionAnalysisResult", "type": "object" }, + "AgentSessionLlmEndpointError": { + "description": "One failed reply from the customer's own LLM endpoint, after the\nplatform's single retry within the request.\n\n- http_error: the endpoint answered with a non-2xx status.\n- timeout: no response within the request timeout.\n- connection_error: the request got no answer. `reason` is dns_failed,\n connection_refused, connection_reset, tls_failed, address_not_allowed\n (an address the platform does not call) or unknown.\n- invalid_response: a 2xx response that was not a usable reply. `reason`\n is not_event_stream (a streamed request answered with something else),\n stream_incomplete (the stream ended without a finish_reason, usage or\n output), empty_reply (no text and no tool call) or unknown.", + "properties": { + "occurred_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Occurred At" + }, + "turn_id": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Turn Id" + }, + "type": { + "enum": [ + "http_error", + "timeout", + "connection_error", + "invalid_response" + ], + "title": "Type", + "type": "string" + }, + "reason": { + "anyOf": [ + { + "enum": [ + "dns_failed", + "connection_refused", + "connection_reset", + "tls_failed", + "address_not_allowed", + "not_event_stream", + "stream_incomplete", + "empty_reply", + "unknown" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Reason" + }, + "status_code": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Status Code" + }, + "response_body": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Response Body" + }, + "duration_ms": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Duration Ms" + }, + "consecutive_failures": { + "title": "Consecutive Failures", + "type": "integer" + } + }, + "required": [ + "type", + "consecutive_failures" + ], + "title": "AgentSessionLlmEndpointError", + "type": "object" + }, "AgentSessionMessageItem": { "description": "One transcript message; system messages never surface here.", "properties": { @@ -19152,6 +19267,19 @@ "default": null, "title": "Input Medium" }, + "fallback_reason": { + "anyOf": [ + { + "const": "llm_error", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Fallback Reason" + }, "turn_id": { "anyOf": [ { @@ -21205,6 +21333,22 @@ "default": null, "description": "Sent to your endpoint as the Authorization bearer token; write-only, reads return null. Required when introducing `custom`; omit to keep the stored key when updating.", "title": "Api Key" + }, + "headers": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Extra headers sent on every request to your endpoint, such as `x-vercel-protection-bypass`; write-only, reads return null. Omit to keep the stored headers, `{}` clears them.", + "title": "Headers" } }, "required": [ @@ -22345,7 +22489,7 @@ "type": "object" }, "AgentLLMCustomConfigRedacted": { - "description": "Read entity: the stored api_key never leaves the collection.", + "description": "Read entity: the stored api_key and headers never leave the collection.", "properties": { "base_url": { "minLength": 1, @@ -22361,6 +22505,11 @@ "default": null, "title": "Api Key", "type": "null" + }, + "headers": { + "default": null, + "title": "Headers", + "type": "null" } }, "required": [ @@ -23186,6 +23335,13 @@ "default": false, "title": "Passed", "type": "boolean" + }, + "llm_endpoint_errors": { + "items": { + "$ref": "#/components/schemas/AgentSessionLlmEndpointError" + }, + "title": "Llm Endpoint Errors", + "type": "array" } }, "title": "AgentTestSimulationResult", From c7ea69a07ebfce5e8f1583116a12ee4e406aac09 Mon Sep 17 00:00:00 2001 From: Him188 Date: Mon, 26 Oct 2026 00:23:32 +0900 Subject: [PATCH 3/3] docs(agents): the date and time switch is context.current_time, off for new agents (FA-528) A context section parallel to guardrails holds the facts the platform tells the agent on its own. New agents start with the current time off, agents created before the switch keep it on. Session requests override it with context.current_time, world_context stays as a deprecated alias. Co-Authored-By: Claude Fable 5.1 --- agents/build/configuration.mdx | 17 ++++++++++++----- agents/build/dynamic-variables.mdx | 10 +++++----- agents/build/time-timezone.mdx | 24 +++++++++++------------- agents/deploy/authenticated-sessions.mdx | 4 ++-- agents/deploy/web-sdk.mdx | 2 +- agents/test/agent-tests.mdx | 2 +- 6 files changed, 32 insertions(+), 27 deletions(-) diff --git a/agents/build/configuration.mdx b/agents/build/configuration.mdx index 941f151b..0cfa7a24 100644 --- a/agents/build/configuration.mdx +++ b/agents/build/configuration.mdx @@ -93,9 +93,13 @@ Turn it off if callers should be able to interrupt the agent within those 3 seco `conversation.timezone` is the default IANA timezone (like `Asia/Tokyo`) 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. -### Time awareness +## Context -`conversation.world_context` (default `true`) is what makes the agent time-aware: every session learns today's date when it starts and the current time before each reply, in the timezone above. In the Builder this is the **Current date & time** toggle next to the time zone. Turn it off when the agent must not know the real date, for example a role-play set on a fictional date or a prompt that states its own. It is the default for every session on every channel, and the only switch for phone calls, which the platform creates without a session request. A per-session `world_context` on the [session request](/agents/deploy/authenticated-sessions) overrides it in either direction. See [Time & timezone](/agents/build/time-timezone#turn-it-off). +The `context` section holds the facts the platform tells your agent on its own, one switch each. Guardrails constrain what the agent does, context switches add to what it knows. + +### Current date and time + +`context.current_time` (default `false`) tells the agent today's date when a session starts and the current time before every reply, in the agent's [timezone](#timezone). In the Builder this is the **Current date & time** toggle under the time zone. Turn it on for scheduling, reminders, or any prompt that says "tomorrow" or "next Tuesday". Leave it off when the prompt states its own date, for example a role-play set on a fictional day. Agents created before the switch existed have it on, which was their behavior. A session request's `context.current_time` overrides the agent's setting in either direction. See [Time & timezone](/agents/build/time-timezone). ## Autosave and publishing @@ -142,8 +146,10 @@ curl --request GET "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \ "interruption_ignore_phrases": [], "echo_guard": null, "speculative_response": true, - "timezone": "", - "world_context": true + "timezone": "" + }, + "context": { + "current_time": false } } ``` @@ -173,7 +179,8 @@ The response includes the draft's new `config_hash`. Values outside the document | `prompt` | System prompt and first-message settings | This page | | `voice` | Voice profile, text-to-speech model, speaking language, and expressive mode | [Voice & language](/agents/build/voice-language) | | `asr` | Speech recognition model, multilingual recognition, strict language, and recognition keyterms | [Voice & language](/agents/build/voice-language#speech-recognition-model) | -| `conversation` | Call duration, turn-taking, interruption behavior, timezone, time awareness, and storage | This page; storage in [Conversation history](/agents/monitor/conversation-history#what-gets-stored) | +| `conversation` | Call duration, turn-taking, interruption behavior, timezone, and storage | This page; storage in [Conversation history](/agents/monitor/conversation-history#what-gets-stored) | +| `context` | Facts the platform tells the agent on its own, currently the current date and time | This page | | `tools` | Attached webhook tools and system tool switches | [Tools](/agents/build/tools) | | `knowledge_base` | Attached knowledge sources | [Knowledge base](/agents/build/knowledge-base) | | `analysis` | Post-call summary, data fields, and success criteria | [Post-call analysis](/agents/monitor/post-call-analysis) | diff --git a/agents/build/dynamic-variables.mdx b/agents/build/dynamic-variables.mdx index 5b188449..0b31f69c 100644 --- a/agents/build/dynamic-variables.mdx +++ b/agents/build/dynamic-variables.mdx @@ -148,7 +148,7 @@ The platform fills a handful of `{{system.*}}` placeholders itself, on every ses |---|---|---| | `system.channel` | `phone_inbound`, `phone_outbound`, or `web_voice` | Web SDK, API, preview, and Single Turn and Tool test sessions are `web_voice`. A Simulation test uses its [channel](/agents/test/agent-tests#channel). | | `system.timezone` | The session's resolved IANA timezone, for example `Asia/Tokyo` | `UTC` when nothing resolves. Always equals the session's `timezone` field; see [which timezone a session uses](/agents/build/time-timezone#which-timezone-a-session-uses). | -| `system.today` | Today's date in that timezone, ISO 8601 `YYYY-MM-DD` | The calendar date at session creation. There is no `system.now`; see [World context](#world-context). | +| `system.today` | Today's date in that timezone, ISO 8601 `YYYY-MM-DD` | The calendar date at session creation. There is no `system.now`; see [Current date and time](#current-date-and-time). | | `system.language` | The session language code, one of the [52 supported languages](/agents/build/voice-language#speaking-language) | The `language` [override](/agents/deploy/authenticated-sessions#overrides) when the request carries one, otherwise the agent's [speaking language](/agents/build/voice-language#speaking-language). | | `system.caller_number` | The human party's number, E.164 | Inbound: the caller (empty if withheld or not a valid E.164 number). Outbound: the number you dialed. Empty on non-phone sessions. | | `system.caller_number_spoken` | The same number written for speech, for example `+1; 4 1 5; 5 5 5; 0 1 2 3` | Use it wherever the agent should say the number out loud; see [Reading a number out loud](#reading-a-number-out-loud). Empty whenever `system.caller_number` is empty. | @@ -183,7 +183,7 @@ On a web session the same prompt renders `The caller's number is "".`, and the a ### Date and timezone -`system.today` is always ISO formatted, whatever the session language: in the system prompt the model reads it and speaks it in the session's language, while a fixed first message containing `{{system.today}}` is spoken verbatim as `2026-08-21`. A session that runs past midnight keeps its opening date. Template it, and `system.timezone`, when a request needs them explicitly, for example a webhook tool's query string; for the agent's own sense of time no variable is needed, see [World context](#world-context). +`system.today` is always ISO formatted, whatever the session language: in the system prompt the model reads it and speaks it in the session's language, while a fixed first message containing `{{system.today}}` is spoken verbatim as `2026-08-21`. A session that runs past midnight keeps its opening date. Template it, and `system.timezone`, when a request needs them explicitly, for example a webhook tool's query string; for the agent's own sense of time, turn on the agent's `context.current_time` switch instead of templating, see [Current date and time](#current-date-and-time). ### In webhook tools @@ -197,11 +197,11 @@ https://crm.example.com/availability?phone={{system.caller_number}}&from={{syste A reference to a system variable that does not exist (`{{system.foo}}`) is rejected with `422` when you save the configuration or the tool, and when you send it in session overrides. The error lists the available names. -## World context +## Current date and time -The agent knows the current date and time without any variable. The platform states the date and the session's timezone at the start of every session and refreshes the time on every turn, so "tomorrow morning" or "next Tuesday" resolve correctly even in a long conversation. You don't need a custom `{{today}}` or `{{now}}`, and there is no `system.now`: variables render once, when the session is created, so a templated time would be stale from the first reply onward. When you want the date or timezone as text in a template, for example in a webhook tool URL, use the [`system.today` and `system.timezone`](#system-variables) system variables. +With the agent's `context.current_time` switch on, the agent knows the current date and time without any variable: the platform states the date and the session's timezone at the start of every session and refreshes the time on every turn, so "tomorrow morning" or "next Tuesday" resolve correctly even in a long conversation. You don't need a custom `{{today}}` or `{{now}}`, and there is no `system.now`: variables render once, when the session is created, so a templated time would be stale from the first reply onward. When you want the date or timezone as text in a template, for example in a webhook tool URL, use the [`system.today` and `system.timezone`](#system-variables) system variables, which work whether the switch is on or off. -See [Time & timezone](/agents/build/time-timezone) for how the timezone is resolved and how to turn the injection off for a session (`world_context: false`). +See [Time & timezone](/agents/build/time-timezone) for how the timezone is resolved and how the switch works per agent and per session. ## Going further diff --git a/agents/build/time-timezone.mdx b/agents/build/time-timezone.mdx index 79d7b02e..2b04b03f 100644 --- a/agents/build/time-timezone.mdx +++ b/agents/build/time-timezone.mdx @@ -1,10 +1,10 @@ --- title: "Time & Timezone" -description: "Your agent knows the current date and time by default: how the timezone is chosen and how to opt out" +description: "Let your agent know the current date and time: the switch, how the timezone is chosen, and per-session overrides" icon: "clock" --- -Agents are time-aware out of the box: every session knows today's date and the current time in the session's timezone. You don't reference a variable or add anything to your prompt: "tomorrow morning" and "next Tuesday" ground correctly from the first turn, on every channel (voice, text, and phone). +An agent can know today's date and the current time in the session's timezone without you adding anything to the prompt. The switch is `context.current_time` in the agent's [configuration](/agents/build/configuration#current-date-and-time), the **Current date & time** toggle under the time zone in the Builder. It is off for new agents and on for agents created before the switch existed. With it on, "tomorrow morning" and "next Tuesday" ground correctly from the first turn, on every channel (voice, text, and phone). The default timezone is **UTC**. Change it for the agent in its @@ -15,7 +15,7 @@ Agents are time-aware out of the box: every session knows today's date and the c ## What the agent knows -Fish Audio injects two pieces of world context server-side: +With the switch on, Fish Audio injects two lines server-side: | When | What | Example | | ------------------ | ---------------------------- | ------------------------------------------------------------------ | @@ -29,7 +29,7 @@ The time is refreshed on every turn, so it stays accurate through long conversat system prompt's character limit. -Both facts also exist as [system variables](/agents/build/dynamic-variables#system-variables) for the cases where you want to template them yourself, for example into a webhook tool's URL: `{{system.today}}` is the date at session creation as ISO `YYYY-MM-DD`, and `{{system.timezone}}` is the resolved IANA name (`UTC` when nothing resolves). There is no `{{system.now}}`: variables render once, when the session is created, so a templated clock would freeze at the opening. The per-turn time above is the one to rely on. +Both facts also exist as [system variables](/agents/build/dynamic-variables#system-variables), available whether the switch is on or off, for the cases where you want to template them yourself, for example into a webhook tool's URL: `{{system.today}}` is the date at session creation as ISO `YYYY-MM-DD`, and `{{system.timezone}}` is the resolved IANA name (`UTC` when nothing resolves). There is no `{{system.now}}`: variables render once, when the session is created, so a templated clock would freeze at the opening. The per-turn time above is the one to rely on. ## Which timezone a session uses @@ -61,13 +61,11 @@ curl --request POST https://api.fish.audio/v1/agent/sessions \ agent's timezone for those. Calls that resolve nothing run in UTC. -## Turn it off +## Turn it on or off -Time awareness is on by default. Turn it off when the agent must not know the real date and time: a role-play agent set on a fictional date, a prompt that states its own date, or a test that must be reproducible. Off means neither the opening date line nor the per-turn time is injected. +**For the whole agent**, switch **Current date & time** in the Builder (**Configuration**, under the time zone) or set `context.current_time` through the [config API](/agents/build/configuration#current-date-and-time). This is the default for every session of the agent on every channel, and the only switch for phone calls, which the platform creates without a session request. Publish the agent for the change to reach live traffic. Turn it off again when the agent must not know the real date and time: a role-play agent set on a fictional date, a prompt that states its own date, or a test that must be reproducible. -**For the whole agent**, switch off **Current date & time** in the Builder (**Configuration**, next to the time zone) or set `conversation.world_context: false` through the [config API](/agents/build/configuration#time-awareness). This becomes the default for every session of the agent on every channel, and it is the only switch for phone calls, which the platform creates without a session request. Publish the agent for the change to reach live traffic. - -**For one session**, set `world_context` when creating it. An explicit value overrides the agent's setting in either direction: `false` withholds the date and time from a time-aware agent, `true` restores them for one session of an agent that has them off. +**For one session**, send `context.current_time` when creating it. An explicit value overrides the agent's setting in either direction: `false` withholds the date and time from an agent that has them on, `true` injects them for one session of an agent that has them off. The older `world_context` field (`worldContext` in the SDK) is still accepted as an alias. ```bash API (curl) @@ -76,17 +74,17 @@ curl --request POST https://api.fish.audio/v1/agent/sessions \ --header "Content-Type: application/json" \ --data '{ "agent_id": "YOUR_AGENT_ID", - "world_context": false + "context": { "current_time": false } }' ``` ```javascript JavaScript SDK import { AgentSession } from "@fishaudio/agent-client"; -// Public agent: the SDK forwards the opt-out in its creation request. +// Public agent: the SDK forwards the override in its creation request. const session = await AgentSession.start({ agentId: "YOUR_AGENT_ID", - worldContext: false, + context: { currentTime: false }, }); ``` @@ -99,7 +97,7 @@ const session = await AgentSession.start({ icon="server" href="/agents/deploy/authenticated-sessions" > - All session-creation parameters, including `timezone` and `world_context`. + All session-creation parameters, including `timezone` and `context`. `overrides`, `dynamic_variables`, `tool_events`, `timezone`, and - `world_context` belong in your backend's creation request. The SDK forwards + `context` belong in your backend's creation request. The SDK forwards these options (and its `language` shorthand for `overrides.language`) only in [public agent](/agents/deploy/public-agents) mode. @@ -135,7 +135,7 @@ More on what the SDK can do once connected is in the [Web SDK](/agents/deploy/we | `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; omit it to use the agent's configuration. | | `timezone` | string, optional | IANA timezone (like `Asia/Tokyo`) 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 device timezone as an IANA name. A hint, not a demand: it applies only when neither `timezone` nor the agent's configured timezone is set, and invalid values are ignored. The SDK fills it automatically in public-agent mode. From your backend, forward the value from your client. See the [resolution order](/agents/build/time-timezone). | -| `world_context` | boolean, optional | Whether the agent knows the current date and time. Omit it to follow the agent's [time awareness setting](/agents/build/configuration#time-awareness) (on by default). `false` withholds both from this session, `true` injects them even when the agent has them off. | +| `context` | object, optional | Per-session overrides of the agent's [context switches](/agents/build/configuration#context). `{ "current_time": false }` withholds the current date and time from this session, `true` injects them even when the agent has them off; omit a switch to follow the agent. `world_context` is a deprecated alias of `context.current_time`. | Unknown fields (top-level or inside `overrides`) are rejected with `422`. diff --git a/agents/deploy/web-sdk.mdx b/agents/deploy/web-sdk.mdx index 9abc3331..f49dde52 100644 --- a/agents/deploy/web-sdk.mdx +++ b/agents/deploy/web-sdk.mdx @@ -71,7 +71,7 @@ const session = await AgentSession.start({ sessionToken }); for `overrides.language` (`agentId` mode only). Omit it to use the agent's configured [speaking language](/agents/build/voice-language#speaking-language); any other value is rejected with `422` | | `toolEvents` | `boolean` | Whether tool lifecycle events reach this client (default `true`; `agentId` mode only, with `sessionToken` your backend sets `tool_events`) | | `timezone` | `string` | IANA timezone for the agent's sense of local time: the top of the [resolution order](/agents/build/time-timezone), overriding the agent's configured timezone. When omitted, the SDK still sends the browser timezone as a lower-priority hint (`client_timezone`), which applies only if the agent has no timezone configured | -| `worldContext` | `boolean` | Whether the agent knows the current date and time. Omit it to follow the agent's [time awareness setting](/agents/build/configuration#time-awareness). `false` withholds both for this session, `true` injects them even when the agent has them off (`agentId` mode only, with `sessionToken` your backend sets `world_context`) | +| `context` | `{ currentTime?: boolean }` | Per-session overrides of the agent's [context switches](/agents/build/configuration#context): `currentTime: false` withholds the current date and time, `true` injects them even when the agent has them off, omit it to follow the agent (`agentId` mode only, with `sessionToken` your backend sets `context`). `worldContext` is a deprecated alias of `context.currentTime` | | `endUserId` | `string` | Your identifier for the end user, stored on the session and echoed in [webhooks](/agents/monitor/webhooks) (`agentId` mode only; with `sessionToken` your backend sets `end_user_id`) | | `metadata` | `object` | Your own key-values, stored on the session record and returned verbatim (`agentId` mode only; with `sessionToken` your backend sets `metadata`) | | `microphone` | `boolean` | Capture the microphone on start (default `true`). `false` joins muted with no permission prompt, for text-first UIs; the first `setMicMuted(false)` captures it, so call that from a user gesture | diff --git a/agents/test/agent-tests.mdx b/agents/test/agent-tests.mdx index fcb9f92c..65893b28 100644 --- a/agents/test/agent-tests.mdx +++ b/agents/test/agent-tests.mdx @@ -217,7 +217,7 @@ Every Simulation field lives under `simulation`. An optional `conversation`, up | Required tool calls | `assertions.tool_calls`: `tool`, `params`, `min_calls`, `max_calls` | | Forbidden tools | `assertions.forbidden_tools` | | Ended by | `assertions.ended_by`: `agent`, `user`, `transfer`, or `any` | -| Current date and time | `world_context`: `true` or `false`, default `false` | +| Current date and time | `context.current_time`: `true` or `false`, default `false` | | Repeat | `repeat_count`, 1 to 20 | Tools are referenced by `id`, `name`, and `type`, as in Tool tests, and integration tools use the `:` ids that [List Test Tools](/api-reference/endpoint/agent/list-test-tools) returns. Parameter conditions (`when` on a mock entry, `params` on a required call) map a parameter name to `{"type": "exact" | "regex" | "any", "value": "..."}`.