@octavus/docs 0.0.8 → 1.0.0

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

@@ -1,13 +1,23 @@
 ---
 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 multiple types:
 
-## Tool Definition
+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))
+
+This page covers external tools. For provider tools, see [Provider Options](/docs/protocol/provider-options). For code execution capabilities, see [Skills](/docs/protocol/skills).
+
+## External Tools
+
+External tools are defined in the `tools:` section and implemented in your backend.
+
+## Defining Tools
 
 ```yaml
 tools:
@@ -22,30 +32,62 @@ tools:
 
 ### Tool Fields
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `description` | Yes | What the tool does (shown to LLM and optionally user) |
-| `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |
-| `parameters` | No | Input parameters the tool accepts |
+| Field         | Required | Description                                                  |
+| ------------- | -------- | ------------------------------------------------------------ |
+| `description` | Yes      | What the tool does (shown to LLM and optionally user)        |
+| `display`     | No       | How to show in UI: `hidden`, `name`, `description`, `stream` |
+| `parameters`  | No       | Input parameters the tool accepts                            |
 
 ### Display Modes
 
-| Mode | Behavior |
-|------|----------|
-| `hidden` | Tool runs silently, user doesn't see it |
-| `name` | Shows tool name while executing |
+| Mode          | Behavior                                    |
+| ------------- | ------------------------------------------- |
+| `hidden`      | Tool runs silently, user doesn't see it     |
+| `name`        | Shows tool name while executing             |
 | `description` | Shows description while executing (default) |
-| `stream` | Streams tool progress if available |
+| `stream`      | Streams tool progress if available          |
 
 ## Parameters
 
+Tool calls are always objects where each parameter name maps to a value. The LLM generates: `{ param1: value1, param2: value2, ... }`
+
 ### Parameter Fields
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
-| `description` | No | Describes what this parameter is for |
-| `optional` | No | If true, parameter is not required (default: false) |
+| Field         | Required | Description                                                                      |
+| ------------- | -------- | -------------------------------------------------------------------------------- |
+| `type`        | Yes      | Data type: `string`, `number`, `integer`, `boolean`, `unknown`, or a custom type |
+| `description` | No       | Describes what this parameter is for                                             |
+| `optional`    | No       | If true, parameter is not required (default: false)                              |
+
+> **Tip**: You can use [custom types](/docs/protocol/types) for complex parameters like `type: ProductFilter` or `type: SearchOptions`.
+
+### Array Parameters
+
+For array parameters, define a [top-level array type](/docs/protocol/types#top-level-array-types) and use it:
+
+```yaml
+types:
+  CartItem:
+    productId:
+      type: string
+    quantity:
+      type: integer
+
+  CartItemList:
+    type: array
+    items:
+      type: CartItem
+
+tools:
+  add-to-cart:
+    description: Add items to cart
+    parameters:
+      items:
+        type: CartItemList
+        description: Items to add
+```
+
+The tool receives: `{ items: [{ productId: "...", quantity: 1 }, ...] }`
 
 ### Optional Parameters
 
@@ -91,14 +133,14 @@ tools:
     description: Create a support ticket
     parameters:
       summary: { type: string }
-      priority: { type: string }  # low, medium, high, urgent
+      priority: { type: string } # low, medium, high, urgent
 
 agent:
   model: anthropic/claude-sonnet-4-5
   system: system
   tools:
     - get-user-account
-    - create-support-ticket  # LLM can decide when to call these
+    - create-support-ticket # LLM can decide when to call these
   agentic: true
 ```
 
@@ -111,8 +153,8 @@ The LLM decides when to call tools based on the conversation:
 ```yaml
 agent:
   tools: [get-user-account, create-support-ticket]
-  agentic: true  # Allow multiple tool calls
-  maxSteps: 10   # Max tool call cycles
+  agentic: true # Allow multiple tool calls
+  maxSteps: 10 # Max tool call cycles
 ```
 
 ### Deterministic (Block-Based)
@@ -124,12 +166,12 @@ handlers:
   request-human:
     # Always create a ticket when escalating
     Create support ticket:
-      type: tool-call
+      block: tool-call
       tool: create-support-ticket
       input:
-        summary: SUMMARY  # From variable
-        priority: medium  # Literal value
-      output: TICKET      # Store result
+        summary: SUMMARY # From variable
+        priority: medium # Literal value
+      output: TICKET # Store result
 ```
 
 ## Tool Results
@@ -140,6 +182,7 @@ Tool results are stored in variables. Reference the variable in prompts:
 
 ```markdown
 <!-- prompts/ticket-directive.md -->
+
 A support ticket has been created:
 {{TICKET}}
 
@@ -168,14 +211,14 @@ Store tool results for later use:
 handlers:
   request-human:
     Get account:
-      type: tool-call
+      block: tool-call
       tool: get-user-account
       input:
         userId: USER_ID
-      output: ACCOUNT  # Result stored here
+      output: ACCOUNT # Result stored here
 
     Create ticket:
-      type: tool-call
+      block: tool-call
       tool: create-support-ticket
       input:
         summary: SUMMARY

package/content/04-protocol/05-skills.md

@@ -0,0 +1,304 @@
+---
+title: Skills
+description: Using Octavus skills for code execution and specialized capabilities.
+---
+
+# Skills
+
+Skills are knowledge packages that enable agents to execute code and generate files in isolated sandbox environments. Unlike external tools (which you implement in your backend), skills are self-contained packages with documentation and scripts that run in secure sandboxes.
+
+## Overview
+
+Octavus Skills provide **provider-agnostic** code execution. They work with any LLM provider (Anthropic, OpenAI, Google) by using explicit tool calls and system prompt injection.
+
+### How Skills Work
+
+1. **Skill Definition**: Skills are defined in the protocol's `skills:` section
+2. **Skill Resolution**: Skills are resolved from available sources (see below)
+3. **Sandbox Execution**: When a skill is used, code runs in an isolated sandbox environment
+4. **File Generation**: Files saved to `/output/` are automatically captured and made available for download
+
+### Skill Sources
+
+Skills come from two sources, visible in the Skills tab of your organization:
+
+| Source      | Badge in UI | Visibility                     | Example            |
+| ----------- | ----------- | ------------------------------ | ------------------ |
+| **Octavus** | `Octavus`   | Available to all organizations | `qr-code`          |
+| **Custom**  | None        | Private to your organization   | `my-company-skill` |
+
+When you reference a skill in your protocol, Octavus resolves it from your available skills. If you create a custom skill with the same name as an Octavus skill, your custom skill takes precedence.
+
+## Defining Skills
+
+Define skills in the protocol's `skills:` section:
+
+```yaml
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+  data-analysis:
+    display: description
+    description: Analyzing data and generating reports
+```
+
+### Skill Fields
+
+| Field         | Required | Description                                                                           |
+| ------------- | -------- | ------------------------------------------------------------------------------------- |
+| `display`     | No       | How to show in UI: `hidden`, `name`, `description`, `stream` (default: `description`) |
+| `description` | No       | Custom description shown to users (overrides skill's built-in description)            |
+
+### Display Modes
+
+| Mode          | Behavior                                    |
+| ------------- | ------------------------------------------- |
+| `hidden`      | Skill usage not shown to users              |
+| `name`        | Shows skill name while executing            |
+| `description` | Shows description while executing (default) |
+| `stream`      | Streams progress if available               |
+
+## Enabling Skills
+
+After defining skills in the `skills:` section, specify which skills are available for the chat thread in `agent.skills`:
+
+```yaml
+# All skills available to this agent (defined once at protocol level)
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+
+# Skills available for this chat thread
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  tools: [get-user-account]
+  skills: [qr-code] # Skills available for this thread
+  agentic: true
+```
+
+## Skill Tools
+
+When skills are enabled, the LLM has access to these tools:
+
+| Tool                 | Purpose                                 |
+| -------------------- | --------------------------------------- |
+| `octavus_skill_read` | Read skill documentation (SKILL.md)     |
+| `octavus_skill_list` | List available scripts in a skill       |
+| `octavus_skill_run`  | Execute a pre-built script from a skill |
+| `octavus_code_run`   | Execute arbitrary Python/Bash code      |
+| `octavus_file_write` | Create files in the sandbox             |
+| `octavus_file_read`  | Read files from the sandbox             |
+
+The LLM learns about available skills through system prompt injection and can use these tools to interact with skills.
+
+## Example: QR Code Generation
+
+```yaml
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  skills: [qr-code]
+  agentic: true
+
+handlers:
+  user-message:
+    Add message:
+      block: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+
+    Respond:
+      block: next-message
+```
+
+When a user asks "Create a QR code for octavus.ai", the LLM will:
+
+1. Recognize the task matches the `qr-code` skill
+2. Call `octavus_skill_read` to learn how to use the skill
+3. Execute code (via `octavus_code_run` or `octavus_skill_run`) to generate the QR code
+4. Save the image to `/output/` in the sandbox
+5. The file is automatically captured and made available for download
+
+## File Output
+
+Files saved to `/output/` in the sandbox are automatically:
+
+1. **Captured** after code execution
+2. **Uploaded** to S3 storage
+3. **Made available** via presigned URLs
+4. **Included** in the message as file parts
+
+Files persist across page refreshes and are stored in the session's message history.
+
+## Skill Format
+
+Skills follow the [Agent Skills](https://agentskills.io) open standard:
+
+- `SKILL.md` - Required skill documentation with YAML frontmatter
+- `scripts/` - Optional executable code (Python/Bash)
+- `references/` - Optional documentation loaded as needed
+- `assets/` - Optional files used in outputs (templates, images)
+
+### SKILL.md Format
+
+````yaml
+---
+name: qr-code
+description: >
+  Generate QR codes from text, URLs, or data. Use when the user needs to create
+  a QR code for any purpose - sharing links, contact information, WiFi credentials,
+  or any text data that should be scannable.
+version: 1.0.0
+license: MIT
+author: Octavus Team
+---
+
+# QR Code Generator
+
+## Overview
+
+This skill creates QR codes from text data using Python...
+
+## Quick Start
+
+Generate a QR code with Python:
+
+```python
+import qrcode
+import os
+
+output_dir = os.environ.get('OUTPUT_DIR', '/output')
+# ... code to generate QR code ...
+````
+
+## Scripts Reference
+
+### scripts/generate.py
+
+Main script for generating QR codes...
+
+````
+
+## Best Practices
+
+### 1. Clear Descriptions
+
+Provide clear, purpose-driven descriptions:
+
+```yaml
+skills:
+  # Good - clear purpose
+  qr-code:
+    description: Generating QR codes for URLs, contact info, or any text data
+
+  # Avoid - vague
+  utility:
+    description: Does stuff
+````
+
+### 2. When to Use Skills vs Tools
+
+| Use Skills When          | Use Tools When               |
+| ------------------------ | ---------------------------- |
+| Code execution needed    | Simple API calls             |
+| File generation          | Database queries             |
+| Complex calculations     | External service integration |
+| Data processing          | Authentication required      |
+| Provider-agnostic needed | Backend-specific logic       |
+
+### 3. Skill Selection
+
+Define all skills available to this agent in the `skills:` section. Then specify which skills are available for the chat thread in `agent.skills`:
+
+```yaml
+# All skills available to this agent (defined once at protocol level)
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+  data-analysis:
+    display: description
+    description: Analyzing data
+  pdf-processor:
+    display: description
+    description: Processing PDFs
+
+# Skills available for this chat thread
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  skills: [qr-code, data-analysis] # Skills available for this thread
+```
+
+### 4. Display Modes
+
+Choose appropriate display modes based on user experience:
+
+```yaml
+skills:
+  # Background processing - hide from user
+  data-analysis:
+    display: hidden
+
+  # User-facing generation - show description
+  qr-code:
+    display: description
+
+  # Interactive progress - stream updates
+  report-generation:
+    display: stream
+```
+
+## Comparison: Skills vs Tools vs Provider Options
+
+| Feature            | Octavus Skills    | External Tools      | Provider Tools/Skills |
+| ------------------ | ----------------- | ------------------- | --------------------- |
+| **Execution**      | Isolated sandbox  | Your backend        | Provider servers      |
+| **Provider**       | Any (agnostic)    | N/A                 | Provider-specific     |
+| **Code Execution** | Yes               | No                  | Yes (provider tools)  |
+| **File Output**    | Yes               | No                  | Yes (provider skills) |
+| **Implementation** | Skill packages    | Your code           | Built-in              |
+| **Cost**           | Sandbox + LLM API | Your infrastructure | Included in API       |
+
+## Uploading Custom Skills
+
+You can upload custom skills to your organization:
+
+1. Create a skill following the [Agent Skills](https://agentskills.io) format
+2. Package it as a `.skill` bundle (ZIP file)
+3. Upload via the platform UI
+4. Reference by slug in your protocol
+
+```yaml
+skills:
+  custom-analysis:
+    display: description
+    description: Custom analysis tool
+
+agent:
+  skills: [custom-analysis]
+```
+
+## Security
+
+Skills run in isolated sandbox environments:
+
+- **No network access** (unless explicitly configured)
+- **No persistent storage** (sandbox destroyed after execution)
+- **File output only** via `/output/` directory
+- **Time limits** enforced (5-minute default timeout)
+
+## Next Steps
+
+- [Agent Config](/docs/protocol/agent-config) — Configuring skills in agent settings
+- [Provider Options](/docs/protocol/provider-options) — Anthropic's built-in skills
+- [Skills Advanced Guide](/docs/protocol/skills-advanced) — Best practices and advanced patterns