@octavus/docs 0.0.8 → 0.0.9

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/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"`
+