Tools

Tools extend what agents can do. In Octavus, tools can execute either on your server or on the client side.

Server Tools vs Client Tools

When the Server SDK encounters a tool call:

1. Handler exists → Execute on server, continue automatically
2. No handler → Forward to client via client-tool-request event

For client-side tool handling, see Client Tools.

Why Server Tools

Server-side tools give you full control:

• ✅ Full data access — Query your database directly
• ✅ Your authentication — Use your existing auth context
• ✅ No data exposure — Sensitive data never leaves your infrastructure
• ✅ Custom logic — Any complexity you need

Defining Tool Handlers

Tool handlers are async functions that receive arguments and return results:

Using Tools in Sessions

Pass tool handlers when attaching to a session:

Tool Handler Signature

Arguments

Arguments are passed as a Record<string, unknown>. Type-check as needed:

Return Values

Return any JSON-serializable value. The result is:

1. Sent back to the LLM as context
2. Stored in session state
3. Optionally stored in a variable for protocol use

Error Handling

Throw errors for failures. They're captured and sent to the LLM:

The LLM receives the error message and can respond appropriately (e.g., "I couldn't find that account").

Tool Execution Flow

When the LLM calls a tool:

Accessing Request Context

For request-specific data (auth, headers), create handlers dynamically:

Best Practices

1. Validate Arguments

2. Handle Timeouts

3. Log Tool Calls