@octavus/docs 0.0.7 → 0.0.9

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

@@ -0,0 +1,280 @@
+---
+title: HTTP Transport
+description: Using HTTP/SSE for streaming with Octavus in Next.js, Express, and other frameworks.
+---
+
+# HTTP Transport
+
+The HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.
+
+## When to Use HTTP Transport
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Next.js, Remix, or similar frameworks | ✅ Use HTTP |
+| Standard web apps without special requirements | ✅ Use HTTP |
+| Serverless deployments (Vercel, etc.) | ✅ Use HTTP |
+| Need custom real-time events | Consider [Socket Transport](/docs/client-sdk/socket-transport) |
+
+## Basic Setup
+
+### Client
+
+```tsx
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, error, send, stop } = useOctavusChat({ transport });
+
+  const sendMessage = async (text: string) => {
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
+  };
+
+  // ... render chat
+}
+```
+
+### Server (Next.js API Route)
+
+```typescript
+// app/api/trigger/route.ts
+import { OctavusClient, toSSEStream } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+export async function POST(request: Request) {
+  const { sessionId, triggerName, input } = await request.json();
+
+  const session = client.agentSessions.attach(sessionId, {
+    tools: {
+      'get-user-account': async (args) => {
+        return { name: 'Demo User', plan: 'pro' };
+      },
+    },
+  });
+
+  // trigger() returns parsed events, toSSEStream() converts to SSE format
+  const events = session.trigger(triggerName, input);
+
+  return new Response(toSSEStream(events), {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}
+```
+
+## Session Creation
+
+Sessions should be created server-side before rendering the chat. There are two patterns:
+
+### Pattern 1: Create Session on Page Load
+
+```tsx
+// app/chat/page.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Chat } from '@/components/Chat';
+
+export default function ChatPage() {
+  const [sessionId, setSessionId] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch('/api/sessions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        agentId: 'your-agent-id',
+        input: { COMPANY_NAME: 'Acme Corp' },
+      }),
+    })
+      .then(res => res.json())
+      .then(data => setSessionId(data.sessionId));
+  }, []);
+
+  if (!sessionId) {
+    return <LoadingSpinner />;
+  }
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+### Pattern 2: Server-Side Session Creation (App Router)
+
+```tsx
+// app/chat/page.tsx
+import { octavus } from '@/lib/octavus';
+import { Chat } from '@/components/Chat';
+
+export default async function ChatPage() {
+  // Create session server-side
+  const sessionId = await octavus.agentSessions.create('your-agent-id', {
+    COMPANY_NAME: 'Acme Corp',
+  });
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+This pattern is cleaner as the session is ready before the component renders.
+
+## Error Handling
+
+Handle errors in both the transport and the hook:
+
+```tsx
+const { messages, status, error, send } = useOctavusChat({
+  transport,
+  onError: (err) => {
+    console.error('Stream error:', err);
+    // Show toast, update UI, etc.
+  },
+});
+
+// Also check error state
+if (error) {
+  return <ErrorMessage error={error} />;
+}
+```
+
+## Stop Streaming
+
+Allow users to cancel ongoing streams:
+
+```tsx
+const { send, stop, status } = useOctavusChat({ transport });
+
+return (
+  <button
+    onClick={status === 'streaming' ? stop : () => sendMessage()}
+    disabled={status === 'streaming' && !inputValue}
+  >
+    {status === 'streaming' ? 'Stop' : 'Send'}
+  </button>
+);
+```
+
+## Express Server
+
+For non-Next.js backends:
+
+```typescript
+import express from 'express';
+import { OctavusClient, toSSEStream } from '@octavus/server-sdk';
+
+const app = express();
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+app.post('/api/trigger', async (req, res) => {
+  const { sessionId, triggerName, input } = req.body;
+
+  const session = client.agentSessions.attach(sessionId, {
+    tools: {
+      // Your tool handlers
+    },
+  });
+
+  const events = session.trigger(triggerName, input);
+  const stream = toSSEStream(events);
+
+  // Set SSE headers
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  // Pipe the stream to the response
+  const reader = stream.getReader();
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+  } finally {
+    reader.releaseLock();
+    res.end();
+  }
+});
+```
+
+## Transport Options
+
+```typescript
+interface HttpTransportOptions {
+  // Function that makes the HTTP request
+  triggerRequest: (
+    triggerName: string,
+    input?: Record<string, unknown>
+  ) => Promise<Response>;
+}
+```
+
+## Protocol
+
+### Request Format
+
+The `triggerRequest` function should send a POST request with:
+
+```json
+{
+  "sessionId": "sess_abc123",
+  "triggerName": "user-message",
+  "input": {
+    "USER_MESSAGE": "Hello"
+  }
+}
+```
+
+### Response Format
+
+The server responds with an SSE stream:
+
+```
+data: {"type":"start","messageId":"msg_xyz"}
+
+data: {"type":"text-delta","id":"msg_xyz","delta":"Hello"}
+
+data: {"type":"text-delta","id":"msg_xyz","delta":" there!"}
+
+data: {"type":"finish","finishReason":"stop"}
+
+data: [DONE]
+```
+
+See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list of event types.
+
+## Next Steps
+
+- [Quick Start](/docs/getting-started/quickstart) — Complete Next.js integration guide
+- [Messages](/docs/client-sdk/messages) — Working with message state
+- [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
+

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

@@ -138,4 +138,5 @@ Variables are replaced with their values at runtime. If a variable is not provid
 - [Tools](/docs/protocol/tools) — External capabilities
 - [Handlers](/docs/protocol/handlers) — Execution blocks
 - [Agent Config](/docs/protocol/agent-config) — Model and settings
+- [Provider Options](/docs/protocol/provider-options) — Provider-specific features
 

package/content/04-protocol/03-triggers.md

@@ -117,11 +117,19 @@ function Chat({ sessionId }: { sessionId: string }) {
 ### From Server SDK
 
 ```typescript
-const { stream } = session.trigger('user-message', {
+// trigger() returns an async generator of events
+const events = session.trigger('user-message', {
   USER_MESSAGE: 'Help me with billing',
 });
 
-const { stream } = session.trigger('request-human');
+// Iterate events directly
+for await (const event of events) {
+  console.log(event);
+}
+
+// Or convert to SSE for HTTP responses
+import { toSSEStream } from '@octavus/server-sdk';
+return new Response(toSSEStream(events), { headers: { 'Content-Type': 'text/event-stream' } });
 ```
 
 ## Handlers

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

@@ -1,13 +1,22 @@
 ---
 title: Tools
-description: Defining external tools agents can use.
+description: Defining external tools implemented in your backend.
 ---
 
 # Tools
 
-Tools extend what agents can do. They're defined in the protocol and implemented in your backend.
+Tools extend what agents can do. Octavus supports two types:
 
-## Tool Definition
+1. **External Tools** — Defined in the protocol, implemented in your backend
+2. **Provider Tools** — Built-in tools executed server-side by the provider (e.g., Anthropic's web search)
+
+This page covers external tools. For provider tools, see [Provider Options](/docs/protocol/provider-options).
+
+## External Tools
+
+External tools are defined in the `tools:` section and implemented in your backend.
+
+## Defining Tools
 
 ```yaml
 tools:

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

@@ -28,6 +28,7 @@ agent:
 | `maxSteps` | No | Maximum agentic steps (default: 10) |
 | `temperature` | No | Model temperature (0-2) |
 | `thinking` | No | Extended reasoning level |
+| `anthropic` | No | Anthropic-specific options (tools, skills) |
 
 ## Models
 
@@ -129,6 +130,28 @@ agent:
 - `0.8 - 1.2`: Creative, varied responses
 - `> 1.2`: Very creative (may be inconsistent)
 
+## Provider Options
+
+Enable provider-specific features like Anthropic's built-in tools and skills:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  anthropic:
+    tools:
+      web-search:
+        display: description
+        description: Searching the web
+    skills:
+      pdf:
+        type: anthropic
+        description: Processing PDF
+```
+
+Provider options are validated against the model—using `anthropic:` with a non-Anthropic model will fail validation.
+
+See [Provider Options](/docs/protocol/provider-options) for full documentation.
+
 ## Thread-Specific Config
 
 Override config for named threads:
@@ -163,12 +186,12 @@ tools:
     description: Look up user account
     parameters:
       userId: { type: string }
-  
+
   search-docs:
     description: Search help documentation
     parameters:
       query: { type: string }
-  
+
   create-support-ticket:
     description: Create a support ticket
     parameters:
@@ -188,6 +211,16 @@ agent:
   agentic: true
   maxSteps: 10
   thinking: medium
+  # Anthropic-specific options
+  anthropic:
+    tools:
+      web-search:
+        display: description
+        description: Searching the web
+    skills:
+      pdf:
+        type: anthropic
+        description: Processing PDF
 
 triggers:
   user-message:
@@ -202,7 +235,7 @@ handlers:
       prompt: user-message
       input: [USER_MESSAGE]
       display: hidden
-    
+
     Respond:
       type: next-message
 ```

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

@@ -0,0 +1,275 @@
+---
+title: Provider Options
+description: Configuring provider-specific tools and features.
+---
+
+# Provider Options
+
+Provider options let you enable provider-specific features like Anthropic's built-in tools and skills. These features run server-side on the provider's infrastructure.
+
+## Anthropic Options
+
+Configure Anthropic-specific features when using `anthropic/*` models:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  anthropic:
+    # Provider tools (server-side)
+    tools:
+      web-search:
+        display: description
+        description: Searching the web
+      code-execution:
+        display: description
+        description: Running code
+
+    # Skills (knowledge packages)
+    skills:
+      pdf:
+        type: anthropic
+        display: description
+        description: Processing PDF document
+```
+
+> **Note**: Provider options are validated against the model provider. Using `anthropic:` options with non-Anthropic models will result in a validation error.
+
+## Provider Tools
+
+Provider tools are executed server-side by the provider (Anthropic). Unlike external tools that you implement, provider tools are built-in capabilities.
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `web-search` | Search the web for current information |
+| `code-execution` | Execute Python/Bash in a sandboxed container |
+
+### Tool Configuration
+
+```yaml
+anthropic:
+  tools:
+    web-search:
+      display: description      # How to show in UI
+      description: Searching... # Custom display text
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `display` | No | `hidden`, `name`, `description`, or `stream` (default: `description`) |
+| `description` | No | Custom text shown to users during execution |
+
+### Web Search
+
+Allows the agent to search the web for current information:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  anthropic:
+    tools:
+      web-search:
+        display: description
+        description: Looking up current information
+```
+
+Use cases:
+- Current events and news
+- Real-time data (prices, weather)
+- Fact verification
+- Documentation lookups
+
+### Code Execution
+
+Enables Python and Bash execution in a sandboxed container:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  anthropic:
+    tools:
+      code-execution:
+        display: description
+        description: Running analysis
+```
+
+Use cases:
+- Data analysis and calculations
+- File processing
+- Chart generation
+- Script execution
+
+> **Note**: Code execution is automatically enabled when skills are configured (skills require the container environment).
+
+## Skills
+
+Skills are knowledge packages that give the agent specialized capabilities. They're loaded into the code execution container at `/skills/{skill-id}/`.
+
+### Skill Configuration
+
+```yaml
+anthropic:
+  skills:
+    pdf:
+      type: anthropic          # 'anthropic' or 'custom'
+      version: latest          # Optional version
+      display: description
+      description: Processing PDF
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | `anthropic` (built-in) or `custom` (uploaded) |
+| `version` | No | Skill version (default: `latest`) |
+| `display` | No | `hidden`, `name`, `description`, or `stream` (default: `description`) |
+| `description` | No | Custom text shown to users |
+
+### Built-in Skills
+
+Anthropic provides several built-in skills:
+
+| Skill ID | Purpose |
+|----------|---------|
+| `pdf` | PDF manipulation, text extraction, form filling |
+| `xlsx` | Excel spreadsheet operations and analysis |
+| `docx` | Word document creation and editing |
+| `pptx` | PowerPoint presentation creation |
+
+### Using Skills
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  anthropic:
+    skills:
+      pdf:
+        type: anthropic
+        description: Processing your PDF
+      xlsx:
+        type: anthropic
+        description: Analyzing spreadsheet
+```
+
+When skills are configured:
+1. Code execution is automatically enabled
+2. Skill files are loaded into the container
+3. The agent can read skill instructions and execute scripts
+
+### Custom Skills
+
+You can create and upload custom skills to Anthropic:
+
+```yaml
+anthropic:
+  skills:
+    my-custom-skill:
+      type: custom
+      version: latest
+      description: Running custom analysis
+```
+
+Custom skills follow the [Agent Skills standard](https://agentskills.io) and contain:
+- `SKILL.md` with instructions and metadata
+- Optional `scripts/`, `references/`, and `assets/` directories
+
+## Display Modes
+
+Both tools and skills support display modes:
+
+| Mode | Behavior |
+|------|----------|
+| `hidden` | Not shown to users |
+| `name` | Shows the tool/skill name |
+| `description` | Shows the description (default) |
+| `stream` | Streams progress if available |
+
+## Full Example
+
+```yaml
+input:
+  COMPANY_NAME: { type: string }
+  USER_ID: { type: string, optional: true }
+
+tools:
+  get-user-account:
+    description: Looking up your account
+    parameters:
+      userId: { type: string }
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  input: [COMPANY_NAME, USER_ID]
+  tools: [get-user-account]  # External tools
+  agentic: true
+  thinking: medium
+
+  # Anthropic-specific options
+  anthropic:
+    # Provider tools (server-side)
+    tools:
+      web-search:
+        display: description
+        description: Searching the web
+      code-execution:
+        display: description
+        description: Running code
+
+    # Skills (knowledge packages)
+    skills:
+      pdf:
+        type: anthropic
+        display: description
+        description: Processing PDF document
+      xlsx:
+        type: anthropic
+        display: description
+        description: Analyzing spreadsheet
+
+triggers:
+  user-message:
+    input:
+      USER_MESSAGE: { type: string }
+
+handlers:
+  user-message:
+    Add message:
+      type: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+      display: hidden
+
+    Respond:
+      type: next-message
+```
+
+## Validation
+
+The protocol validator enforces:
+
+1. **Model match**: Provider options must match the model provider
+   - `anthropic:` options require `anthropic/*` model
+   - Using mismatched options results in a validation error
+
+2. **Valid tool types**: Only recognized tools are accepted
+   - `web-search` and `code-execution` for Anthropic
+
+3. **Valid skill types**: Only `anthropic` or `custom` are accepted
+
+### Error Example
+
+```yaml
+# This will fail validation
+agent:
+  model: openai/gpt-4o  # OpenAI model
+  anthropic:            # Anthropic options - mismatch!
+    tools:
+      web-search: {}
+```
+
+Error: `"anthropic" options require an anthropic model. Current model provider: "openai"`
+