diff --git a/skills/create-agent-tui/README.md b/skills/create-agent-tui/README.md index a7a2e34..50a03a3 100644 --- a/skills/create-agent-tui/README.md +++ b/skills/create-agent-tui/README.md @@ -118,6 +118,7 @@ The skill presents an interactive checklist when invoked. You pick what you need | Web Search | on | Real-time web search via `openrouter:web_search` | | Datetime | on | Current date/time via `openrouter:datetime` | | Image Generation | off | Generate images via `openrouter:image_generation` | +| Advisor | off | Consult a stronger model mid-generation via `openrouter:advisor` | ### User-defined tools (your code, executed locally) diff --git a/skills/create-agent-tui/SKILL.md b/skills/create-agent-tui/SKILL.md index bbec2f0..09b8812 100644 --- a/skills/create-agent-tui/SKILL.md +++ b/skills/create-agent-tui/SKILL.md @@ -42,9 +42,12 @@ Present this as a multi-select checklist. Items marked **ON** are pre-selected d | Web Search | `openrouter:web_search` | ON | engine, max_results, domain filtering | | Datetime | `openrouter:datetime` | ON | timezone | | Image Generation | `openrouter:image_generation` | OFF | model, quality, size, format | +| Advisor | `openrouter:advisor` | OFF | model, instructions, tools, forward_transcript, named advisors | Server tools go in the `tools` array alongside user-defined tools. No client code needed — OpenRouter executes them. +**Advisor** lets the agent consult a stronger model mid-generation — before committing to an approach, when stuck, or before declaring done. Pass `parameters.model` to pin an advisor model, or let the executor choose per call. Supports `instructions`, `forward_transcript`, sub-agent `tools`, and named advisor profiles via `parameters.advisors`. Docs: [openrouter.ai/docs/guides/features/server-tools/advisor](https://openrouter.ai/docs/guides/features/server-tools/advisor). + ### User-Defined Tools (client-side, generated into src/tools/) | Tool | Default | Description | @@ -347,6 +350,9 @@ export const tools = [ // Server tools — executed by OpenRouter, no client implementation needed serverTool({ type: 'openrouter:web_search' }), serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }), + + // Advisor — consult a stronger model mid-generation (off by default, add when needed) + // serverTool({ type: 'openrouter:advisor', parameters: { model: '~anthropic/claude-opus-latest' } }), ]; ``` diff --git a/skills/create-agent-tui/sample/src/tools/index.ts b/skills/create-agent-tui/sample/src/tools/index.ts index cd3528e..69f774d 100644 --- a/skills/create-agent-tui/sample/src/tools/index.ts +++ b/skills/create-agent-tui/sample/src/tools/index.ts @@ -18,4 +18,7 @@ export const tools = [ serverTool({ type: 'openrouter:web_search' }), serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }), + + // Advisor — consult a stronger model mid-generation (uncomment to enable) + // serverTool({ type: 'openrouter:advisor', parameters: { model: '~anthropic/claude-opus-latest' } }), ]; diff --git a/skills/create-headless-agent/README.md b/skills/create-headless-agent/README.md index 25d663a..c5536ee 100644 --- a/skills/create-headless-agent/README.md +++ b/skills/create-headless-agent/README.md @@ -58,6 +58,7 @@ The skill presents an interactive checklist when invoked: | Web Fetch | on | Fetch text content from a URL via `openrouter:web_fetch` | | Datetime | on | Current date/time via `openrouter:datetime` | | Image Generation | off | Generate images via `openrouter:image_generation` | +| Advisor | off | Consult a stronger model mid-generation via `openrouter:advisor` | ### User-defined tools (your code, executed locally) @@ -127,7 +128,7 @@ my-agent/ agent.test.ts Example test (bun:test) ``` -Server tools (`openrouter:web_search`, `openrouter:web_fetch`, `openrouter:datetime`) are wired in `tools/index.ts` and execute on OpenRouter's side — no client code. +Server tools (`openrouter:web_search`, `openrouter:web_fetch`, `openrouter:datetime`, `openrouter:advisor`) are wired in `tools/index.ts` and execute on OpenRouter's side — no client code. ## Sample diff --git a/skills/create-headless-agent/SKILL.md b/skills/create-headless-agent/SKILL.md index cae0caf..5351caa 100644 --- a/skills/create-headless-agent/SKILL.md +++ b/skills/create-headless-agent/SKILL.md @@ -47,9 +47,12 @@ Present this as a multi-select checklist. Items marked **ON** are pre-selected d | Web Fetch | `openrouter:web_fetch` | ON | | Datetime | `openrouter:datetime` | ON | | Image Generation | `openrouter:image_generation` | OFF | +| Advisor | `openrouter:advisor` | OFF | Server tools go in the `tools` array alongside user-defined tools. No client code needed — OpenRouter executes them. Docs: [openrouter.ai/docs/guides/features/server-tools](https://openrouter.ai/docs/guides/features/server-tools/overview). +**Advisor** lets the agent consult a stronger model mid-generation — before committing to an approach, when stuck, or before declaring done. Pass `parameters.model` to pin an advisor model, or let the executor choose per call. Supports `instructions`, `forward_transcript`, sub-agent `tools`, and named advisor profiles via `parameters.advisors`. Docs: [openrouter.ai/docs/guides/features/server-tools/advisor](https://openrouter.ai/docs/guides/features/server-tools/advisor). + ### User-Defined Tools (client-side, generated into src/tools/) | Tool | Default | Description | @@ -355,6 +358,9 @@ export const tools = [ serverTool({ type: 'openrouter:web_search' }), serverTool({ type: 'openrouter:web_fetch' }), serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }), + + // Advisor — consult a stronger model mid-generation (off by default, add when needed) + // serverTool({ type: 'openrouter:advisor', parameters: { model: '~anthropic/claude-opus-latest' } }), ] as const; ``` diff --git a/skills/create-headless-agent/sample/src/tools/index.ts b/skills/create-headless-agent/sample/src/tools/index.ts index a78113e..3d87ca0 100644 --- a/skills/create-headless-agent/sample/src/tools/index.ts +++ b/skills/create-headless-agent/sample/src/tools/index.ts @@ -23,4 +23,7 @@ export const tools = [ serverTool({ type: 'openrouter:web_search' }), serverTool({ type: 'openrouter:web_fetch' }), serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }), + + // Advisor — consult a stronger model mid-generation (uncomment to enable) + // serverTool({ type: 'openrouter:advisor', parameters: { model: '~anthropic/claude-opus-latest' } }), ] as const; diff --git a/skills/openrouter-typescript-sdk/SKILL.md b/skills/openrouter-typescript-sdk/SKILL.md index 7fc11cb..d316ff9 100644 --- a/skills/openrouter-typescript-sdk/SKILL.md +++ b/skills/openrouter-typescript-sdk/SKILL.md @@ -498,6 +498,93 @@ const manualTool = tool({ }); ``` +#### Server Tools +OpenRouter provides built-in server tools that execute on OpenRouter's side — no client implementation needed. Use `serverTool()` to add them to the `tools` array alongside regular tools: + +```typescript +import { serverTool } from '@openrouter/agent'; + +const result = client.callModel({ + model: 'openai/gpt-5-nano', + input: 'Research the latest on quantum computing', + tools: [ + serverTool({ type: 'openrouter:web_search' }), + serverTool({ type: 'openrouter:web_fetch' }), + serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }), + serverTool({ type: 'openrouter:image_generation' }), + serverTool({ type: 'openrouter:advisor', parameters: { model: '~anthropic/claude-opus-latest' } }), + ] +}); +``` + +Available server tools: `openrouter:web_search`, `openrouter:web_fetch`, `openrouter:datetime`, `openrouter:image_generation`, `openrouter:advisor`. Docs: [openrouter.ai/docs/guides/features/server-tools](https://openrouter.ai/docs/guides/features/server-tools/overview). + +#### Advisor Tool + +The `openrouter:advisor` server tool lets a model consult a stronger advisor model mid-generation. The model invokes it with a `prompt` when it hits a decision point, is stuck, or wants validation before proceeding. + +```typescript +// Basic — pin an advisor model +serverTool({ + type: 'openrouter:advisor', + parameters: { model: '~anthropic/claude-opus-latest' } +}) + +// With instructions and sub-agent tools +serverTool({ + type: 'openrouter:advisor', + parameters: { + model: '~anthropic/claude-opus-latest', + instructions: 'You are a senior staff engineer. Be decisive.', + tools: [{ type: 'openrouter:web_search' }], + forward_transcript: false, + } +}) + +// Named advisor profiles — the model selects by name per call +serverTool({ + type: 'openrouter:advisor', + parameters: { + advisors: [ + { + name: 'reviewer', + model: '~anthropic/claude-opus-latest', + instructions: 'You are a critical code reviewer. Find the flaws.', + }, + { + name: 'architect', + model: '~openai/gpt-latest', + instructions: 'You are a systems architect. Think about scale.', + }, + ] + } +}) +``` + +**Parameters** (`parameters` object on the tool entry): + +| Field | Default | Description | +|-------|---------|-------------| +| `model` | Outer request model | Advisor model to consult (any OpenRouter model) | +| `advisors` | None | Roster of named advisor profiles — model selects by `name` per call | +| `instructions` | None | System instructions for the advisor | +| `tools` | None | Tools available to the advisor sub-agent (e.g. `openrouter:web_search`) | +| `forward_transcript` | `false` | Forward full parent conversation to the advisor | +| `max_tool_calls` | Provider default | Max tool-calling steps for the advisor (1–25) | +| `max_completion_tokens` | Provider default | Max output tokens for the advisor call | +| `reasoning` | Provider default | Reasoning config (`{ effort, max_tokens }`) | +| `temperature` | Provider default | Sampling temperature (0–2) | + +**Tool-call arguments** (passed by the model when invoking): + +| Argument | Description | +|----------|-------------| +| `prompt` | What the model wants advice on (required unless `forward_transcript` is `true`) | +| `name` | Which named advisor profile to consult (only when `advisors` roster is configured) | +| `model` | Advisor model override (only honored when neither the profile nor definition fixes one) | + +Docs: [openrouter.ai/docs/guides/features/server-tools/advisor](https://openrouter.ai/docs/guides/features/server-tools/advisor). + --- ## Multi-Turn Conversations with Stop Conditions