@octavus/docs 2.12.0 → 2.14.0

package/content/01-getting-started/02-quickstart.md

@@ -17,7 +17,7 @@ This guide will walk you through integrating Octavus into your application in un
 
 Before integrating with SDKs, use **Agent Preview** to test your agent directly in the platform:
 
-1. Open your agent in the platform at `octavus.ai/agents/[agentId]`
+1. Open your agent in the platform at `octavus.ai/platform/agents/[agentId]`
 2. Click the **Preview** tab
 3. Configure session inputs and tool mock responses
 4. Start a conversation to test agent behavior
@@ -81,7 +81,7 @@ There are two ways to create and manage agents:
 **Option 1: Platform UI (Recommended for getting started)**
 
 1. Go to [octavus.ai](https://octavus.ai) and create an agent in the web editor
-2. Copy the agent ID from the URL (e.g., `octavus.ai/agents/clxyz123abc456`)
+2. Copy the agent ID from the URL (e.g., `octavus.ai/platform/agents/clxyz123abc456`)
 3. Add it to your `.env.local`: `OCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456`
 
 **Option 2: Local Development with CLI**

package/content/02-server-sdk/02-sessions.md

@@ -121,6 +121,7 @@ interface TriggerRequest {
   type: 'trigger';
   triggerName: string;
   input?: Record<string, unknown>;
+  rollbackAfterMessageId?: string | null; // For retry: truncate messages after this ID
 }
 
 // Continue after client-side tool handling

package/content/02-server-sdk/06-workers.md

@@ -142,7 +142,7 @@ try {
   if (error instanceof WorkerError) {
     console.error('Worker failed:', error.message);
     if (error.sessionId) {
-      console.error(`Debug: ${client.baseUrl}/sessions/${error.sessionId}`);
+      console.error(`Debug: ${client.baseUrl}/platform/sessions/${error.sessionId}`);
     }
   }
 }
@@ -355,7 +355,7 @@ try {
   if (error instanceof WorkerError) {
     console.error('Failed:', error.message);
     if (error.sessionId) {
-      console.error(`Debug: ${client.baseUrl}/sessions/${error.sessionId}`);
+      console.error(`Debug: ${client.baseUrl}/platform/sessions/${error.sessionId}`);
     }
   }
 }

package/content/03-client-sdk/01-overview.md

@@ -183,6 +183,21 @@ const { stop } = useOctavusChat({ transport });
 stop();
 ```
 
+### Retry Last Trigger
+
+Re-execute the last trigger from the same starting point. Messages are rolled back to the state before the trigger, the user message is re-added (if any), and the agent re-executes. Already-uploaded files are reused without re-uploading.
+
+```tsx
+const { retry, canRetry } = useOctavusChat({ transport });
+
+// Retry after an error, cancellation, or unsatisfactory result
+if (canRetry) {
+  await retry();
+}
+```
+
+`canRetry` is `true` when a trigger has been sent and the chat is not currently streaming or awaiting input.
+
 ## Hook Reference (React)
 
 ### useOctavusChat
@@ -234,6 +249,8 @@ interface UseOctavusChatReturn {
     options?: { userMessage?: UserMessageInput },
   ) => Promise<void>;
   stop: () => void;
+  retry: () => Promise<void>; // Retry last trigger from same starting point
+  canRetry: boolean; // Whether retry() can be called
 
   // Connection management (socket transport only - undefined for HTTP)
   connect: (() => Promise<void>) | undefined;

package/content/03-client-sdk/06-http-transport.md

@@ -271,6 +271,7 @@ interface TriggerRequest {
   type: 'trigger';
   triggerName: string;
   input?: Record<string, unknown>;
+  rollbackAfterMessageId?: string | null; // For retry: truncate messages after this ID
 }
 
 // Continue after client-side tool handling

package/content/03-client-sdk/09-error-handling.md

@@ -124,6 +124,21 @@ if (isProviderError(error) && error.provider) {
 }
 ```
 
+## Retrying After Errors
+
+Use `retry()` to re-execute the last trigger from the same starting point. Messages are rolled back, the user message is re-added (if any), and the agent re-executes. Files are reused without re-uploading.
+
+```tsx
+const { error, canRetry, retry } = useOctavusChat({ transport });
+
+// Retry after any error
+if (canRetry) {
+  await retry();
+}
+```
+
+`retry()` also works after stopping (cancellation) or when the result is unsatisfactory — not just errors.
+
 ## Building Error UI
 
 ```tsx
@@ -135,7 +150,7 @@ import {
 } from '@octavus/react';
 
 function Chat() {
-  const { error, status } = useOctavusChat({ transport });
+  const { error, status, retry, canRetry } = useOctavusChat({ transport });
 
   return (
     <div>
@@ -149,7 +164,11 @@ function Chat() {
               Please try again in {error.retryAfter} seconds
             </p>
           )}
-          {error.retryable && <button className="mt-3 text-red-700 underline">Try again</button>}
+          {canRetry && (
+            <button className="mt-3 text-red-700 underline" onClick={() => void retry()}>
+              Retry
+            </button>
+          )}
         </div>
       )}
     </div>
@@ -197,12 +216,17 @@ useOctavusChat({
 The hook exposes error state directly:
 
 ```typescript
-const { error, status } = useOctavusChat({ transport });
+const { error, status, retry, canRetry } = useOctavusChat({ transport });
 
 // status is 'error' when an error occurred
 // error contains the OctavusError object
 
-// Clear error by sending a new message
+// Option 1: Retry the same trigger (rolls back messages, re-executes)
+if (canRetry) {
+  await retry();
+}
+
+// Option 2: Send a new message (clears the error)
 await send('user-message', { USER_MESSAGE: 'Try again' });
 ```
 

package/content/04-protocol/01-overview.md

@@ -81,6 +81,7 @@ agent:
   tools: [get-user-account]
   skills: [qr-code] # Enable skills
   imageModel: google/gemini-2.5-flash-image # Enable image generation
+  webSearch: true # Enable web search
   agentic: true # Allow multiple tool calls
   thinking: medium # Extended reasoning
 

package/content/04-protocol/04-tools.md

@@ -8,10 +8,11 @@ description: Defining external tools implemented in your backend.
 Tools extend what agents can do. Octavus supports multiple types:
 
 1. **External Tools** — Defined in the protocol, implemented in your backend (this page)
-2. **Provider Tools** — Built-in tools executed server-side by the provider (e.g., Anthropic's web search)
-3. **Skills** — Code execution and knowledge packages (see [Skills](/docs/protocol/skills))
+2. **Built-in Tools** — Provider-agnostic tools managed by Octavus (web search, image generation)
+3. **Provider Tools** — Provider-specific tools executed by the provider (e.g., Anthropic's code execution)
+4. **Skills** — Code execution and knowledge packages (see [Skills](/docs/protocol/skills))
 
-This page covers external tools. For provider tools, see [Provider Options](/docs/protocol/provider-options). For code execution capabilities, see [Skills](/docs/protocol/skills).
+This page covers external tools. Built-in tools are enabled via agent config — see [Web Search](/docs/protocol/agent-config#web-search) and [Image Generation](/docs/protocol/agent-config#image-generation). For provider-specific tools, see [Provider Options](/docs/protocol/provider-options). For code execution, see [Skills](/docs/protocol/skills).
 
 ## External Tools
 

package/content/04-protocol/07-agent-config.md

@@ -30,6 +30,7 @@ agent:
 | `references`     | No       | List of references the LLM can fetch on demand            |
 | `sandboxTimeout` | No       | Skill sandbox timeout in ms (default: 5 min, max: 1 hour) |
 | `imageModel`     | No       | Image generation model (enables agentic image generation) |
+| `webSearch`      | No       | Enable built-in web search tool (provider-agnostic)       |
 | `agentic`        | No       | Allow multiple tool call cycles                           |
 | `maxSteps`       | No       | Maximum agentic steps (default: 10)                       |
 | `temperature`    | No       | Model temperature (0-2)                                   |
@@ -285,6 +286,28 @@ Use `generate-image` block (see [Handlers](/docs/protocol/handlers#generate-imag
 - Building prompt engineering pipelines
 - Images are generated at specific handler steps
 
+## Web Search
+
+Enable the LLM to search the web for current information:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  webSearch: true
+  agentic: true
+```
+
+When `webSearch` is enabled, the `octavus_web_search` tool becomes available. The LLM can decide when to search the web based on the conversation. Search results include source URLs that are emitted as citations in the UI.
+
+This is a **provider-agnostic** built-in tool — it works with any LLM provider (Anthropic, Google, OpenAI, etc.). For Anthropic's own web search implementation, see [Provider Options](/docs/protocol/provider-options).
+
+Use cases:
+
+- Current events and real-time data
+- Fact verification and documentation lookups
+- Any information that may have changed since the model's training
+
 ## Temperature
 
 Control response randomness:
@@ -341,9 +364,10 @@ handlers:
       skills: [data-analysis] # Thread-specific skills
       references: [escalation-policy] # Thread-specific references
       imageModel: google/gemini-2.5-flash-image # Thread-specific image model
+      webSearch: true # Thread-specific web search
 ```
 
-Each thread can have its own skills, references, and image model. Skills must be defined in the protocol's `skills:` section. References must exist in the agent's `references/` directory. Workers use this same pattern since they don't have a global `agent:` section.
+Each thread can have its own skills, references, image model, and web search setting. Skills must be defined in the protocol's `skills:` section. References must exist in the agent's `references/` directory. Workers use this same pattern since they don't have a global `agent:` section.
 
 ## Full Example
 
@@ -392,6 +416,7 @@ agent:
     - create-support-ticket
   skills: [qr-code] # Octavus skills
   references: [support-policies] # On-demand context
+  webSearch: true # Built-in web search
   agentic: true
   maxSteps: 10
   thinking: medium

package/content/04-protocol/08-provider-options.md

@@ -65,7 +65,7 @@ anthropic:
 
 ### Web Search
 
-Allows the agent to search the web for current information:
+Allows the agent to search the web using Anthropic's built-in web search:
 
 ```yaml
 agent:
@@ -77,12 +77,7 @@ agent:
         description: Looking up current information
 ```
 
-Use cases:
-
-- Current events and news
-- Real-time data (prices, weather)
-- Fact verification
-- Documentation lookups
+> **Tip**: Octavus also provides a **provider-agnostic** web search via `webSearch: true` in the agent config. This works with any LLM provider and is the recommended approach for multi-provider agents. See [Web Search](/docs/protocol/agent-config#web-search) for details.
 
 ### Code Execution
 

package/content/04-protocol/11-workers.md

@@ -228,6 +228,7 @@ All LLM configuration goes here:
 | `tools`       | Tools available in this thread                    |
 | `skills`      | Octavus skills available in this thread           |
 | `imageModel`  | Image generation model                            |
+| `webSearch`   | Enable built-in web search tool                   |
 | `thinking`    | Extended reasoning level                          |
 | `temperature` | Model temperature                                 |
 | `maxSteps`    | Maximum tool call cycles (enables agentic if > 1) |
@@ -362,9 +363,9 @@ steps:
 output: CONVERSATION_SUMMARY
 ```
 
-## Skills and Image Generation
+## Skills, Image Generation, and Web Search
 
-Workers can use Octavus skills and image generation, configured per-thread via `start-thread`:
+Workers can use Octavus skills, image generation, and web search, configured per-thread via `start-thread`:
 
 ```yaml
 skills:
@@ -380,6 +381,7 @@ steps:
     system: system
     skills: [qr-code]
     imageModel: google/gemini-2.5-flash-image
+    webSearch: true
     maxSteps: 10
 ```
 

package/content/05-api-reference/02-sessions.md

@@ -35,7 +35,7 @@ POST /api/agent-sessions
 | `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |
 | `input`   | object | No       | Input variables for the agent         |
 
-> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.
+> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/platform/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.
 
 ### Response
 
@@ -258,11 +258,12 @@ POST /api/agent-sessions/:sessionId/trigger
 }
 ```
 
-| Field         | Type   | Required | Description                                    |
-| ------------- | ------ | -------- | ---------------------------------------------- |
-| `triggerName` | string | Yes      | Name of the trigger to execute                 |
-| `input`       | object | No       | Input variables for the trigger                |
-| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |
+| Field                    | Type           | Required | Description                                                                                        |
+| ------------------------ | -------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `triggerName`            | string         | Yes      | Name of the trigger to execute                                                                     |
+| `input`                  | object         | No       | Input variables for the trigger                                                                    |
+| `toolResults`            | array          | No       | Tool results for continuation (handled by SDK)                                                     |
+| `rollbackAfterMessageId` | string \| null | No       | For retry: ID of the last message to keep. Messages after this are removed. `null` = truncate all. |
 
 ### Response