riffer 0.55.0 → 0.57.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.release-please-manifest.json +1 -1
- data/CHANGELOG.md +37 -0
- data/README.md +3 -2
- data/UPGRADING.md +3 -0
- data/docs/AGENTS.md +105 -50
- data/docs/AGENT_LIFECYCLE.md +2 -2
- data/docs/CONFIGURATION.md +54 -3
- data/docs/EVALS.md +2 -0
- data/docs/GUARDRAILS.md +2 -0
- data/docs/MCP.md +36 -0
- data/docs/MESSAGES.md +125 -15
- data/docs/OVERVIEW.md +7 -7
- data/docs/SERIALIZATION.md +12 -2
- data/docs/SKILLS.md +1 -1
- data/docs/STABILITY.md +32 -0
- data/docs/STREAM_EVENTS.md +16 -0
- data/docs/TESTING.md +22 -1
- data/docs/TOOLS.md +93 -37
- data/docs/TOOL_ADVANCED.md +7 -0
- data/docs/providers/AMAZON_BEDROCK.md +7 -3
- data/docs/providers/ANTHROPIC.md +53 -16
- data/docs/providers/AZURE_OPENAI.md +9 -3
- data/docs/providers/CUSTOM_PROVIDERS.md +43 -0
- data/docs/providers/GEMINI.md +9 -5
- data/docs/providers/GOOGLE_CLOUD.md +10 -5
- data/docs/providers/MOCK_PROVIDER.md +4 -0
- data/docs/providers/OPENAI.md +28 -4
- data/docs/providers/OPENROUTER.md +11 -3
- data/docs/providers/PROVIDERS.md +1 -1
- data/docs-site/index.html.erb +1 -1
- data/docs-site/manifest.yml +3 -0
- data/lib/riffer/agent/config.rb +21 -0
- data/lib/riffer/agent/context.rb +36 -18
- data/lib/riffer/agent/run.rb +82 -21
- data/lib/riffer/agent/serializer.rb +5 -0
- data/lib/riffer/agent/session.rb +34 -10
- data/lib/riffer/agent.rb +43 -0
- data/lib/riffer/config/future.rb +53 -0
- data/lib/riffer/config/mcp.rb +17 -0
- data/lib/riffer/config/pricing.rb +5 -15
- data/lib/riffer/config.rb +28 -1
- data/lib/riffer/deprecation/event.rb +25 -0
- data/lib/riffer/deprecation.rb +60 -0
- data/lib/riffer/evals/evaluator.rb +8 -1
- data/lib/riffer/evals/evaluator_runner.rb +1 -0
- data/lib/riffer/evals/judge.rb +2 -2
- data/lib/riffer/evals.rb +2 -0
- data/lib/riffer/mcp/search_tool.rb +1 -1
- data/lib/riffer/mcp.rb +7 -0
- data/lib/riffer/messages/assistant/server_tool_part.rb +73 -0
- data/lib/riffer/messages/assistant/text_part.rb +52 -0
- data/lib/riffer/messages/assistant.rb +64 -17
- data/lib/riffer/messages/tool.rb +6 -2
- data/lib/riffer/params/any_of.rb +5 -8
- data/lib/riffer/params/boolean.rb +1 -1
- data/lib/riffer/params/param.rb +96 -67
- data/lib/riffer/params.rb +50 -71
- data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +28 -11
- data/lib/riffer/providers/anthropic_compatible/messages_api.rb +136 -38
- data/lib/riffer/providers/base.rb +57 -12
- data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
- data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
- data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
- data/lib/riffer/providers/gemini.rb +5 -5
- data/lib/riffer/providers/mock.rb +6 -0
- data/lib/riffer/providers/open_ai.rb +59 -26
- data/lib/riffer/skills/activate_tool.rb +1 -1
- data/lib/riffer/stream_events/server_tool_done.rb +21 -0
- data/lib/riffer/testing.rb +6 -0
- data/lib/riffer/tool.rb +92 -2
- data/lib/riffer/tools/response.rb +11 -2
- data/lib/riffer/version.rb +1 -1
- data/lib/riffer.rb +2 -0
- data/sig/generated/riffer/agent/config.rbs +13 -1
- data/sig/generated/riffer/agent/context.rbs +16 -0
- data/sig/generated/riffer/agent/run.rbs +19 -2
- data/sig/generated/riffer/agent/session.rbs +6 -0
- data/sig/generated/riffer/agent.rbs +13 -0
- data/sig/generated/riffer/config/future.rbs +29 -0
- data/sig/generated/riffer/config/mcp.rbs +7 -0
- data/sig/generated/riffer/config/pricing.rbs +0 -9
- data/sig/generated/riffer/config.rbs +13 -1
- data/sig/generated/riffer/deprecation/event.rbs +17 -0
- data/sig/generated/riffer/deprecation.rbs +27 -0
- data/sig/generated/riffer/evals/evaluator.rbs +4 -0
- data/sig/generated/riffer/evals.rbs +1 -0
- data/sig/generated/riffer/mcp.rbs +1 -0
- data/sig/generated/riffer/messages/assistant/server_tool_part.rbs +44 -0
- data/sig/generated/riffer/messages/assistant/text_part.rbs +35 -0
- data/sig/generated/riffer/messages/assistant.rbs +24 -11
- data/sig/generated/riffer/messages/tool.rbs +4 -2
- data/sig/generated/riffer/params/any_of.rbs +4 -4
- data/sig/generated/riffer/params/boolean.rbs +1 -1
- data/sig/generated/riffer/params/param.rbs +28 -14
- data/sig/generated/riffer/params.rbs +20 -20
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +12 -5
- data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +50 -9
- data/sig/generated/riffer/providers/base.rbs +18 -0
- data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
- data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
- data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
- data/sig/generated/riffer/providers/mock.rbs +4 -0
- data/sig/generated/riffer/providers/open_ai.rbs +23 -6
- data/sig/generated/riffer/stream_events/server_tool_done.rbs +15 -0
- data/sig/generated/riffer/testing.rbs +4 -0
- data/sig/generated/riffer/tool.rbs +48 -2
- data/sig/generated/riffer/tools/response.rbs +9 -2
- data/sig/generated/riffer.rbs +3 -0
- data/sig/manual/riffer/deprecation.rbs +5 -0
- data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
- metadata +23 -3
- data/lib/riffer/tools/toolable.rb +0 -113
- data/sig/generated/riffer/tools/toolable.rbs +0 -66
|
@@ -150,8 +150,8 @@ class S3ListTool < Riffer::Tool
|
|
|
150
150
|
description "Lists objects in an S3 bucket"
|
|
151
151
|
|
|
152
152
|
params do
|
|
153
|
-
required :bucket,
|
|
154
|
-
optional :prefix,
|
|
153
|
+
required :bucket, :string, description: "The S3 bucket name"
|
|
154
|
+
optional :prefix, :string, description: "Object prefix filter"
|
|
155
155
|
end
|
|
156
156
|
|
|
157
157
|
def call(context:, bucket:, prefix: nil)
|
|
@@ -166,6 +166,10 @@ class AWSAgent < Riffer::Agent
|
|
|
166
166
|
end
|
|
167
167
|
```
|
|
168
168
|
|
|
169
|
+
## Deferred Tools (experimental)
|
|
170
|
+
|
|
171
|
+
Converse has no native deferred loading, so an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) on Bedrock needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`; without it, building the agent raises `Riffer::ArgumentError`. Every request then has one extra tool in `tool_config.tools`, the [gateway](../TOOLS.md#the-gateway-strategy), and the model calls a loaded tool through it, so the tool list stays the same and a load keeps the [`cache_control`](#cache_control) prompt cache. Calls come back under the real tool's name.
|
|
172
|
+
|
|
169
173
|
## Reasoning Models
|
|
170
174
|
|
|
171
175
|
Claude models on Bedrock can think before they answer. Enable extended thinking through `additional_model_request_fields`:
|
|
@@ -195,7 +199,7 @@ The agent-level [`reasoning`](../AGENTS.md#reasoning) setting defaults to Claude
|
|
|
195
199
|
|
|
196
200
|
Riffer sends the reasoning back to Bedrock on every later turn. How much of it Claude uses depends on the model; some only use the reasoning from the current tool-calling turn. For tool calls, sending it back is required: when thinking is enabled, Claude needs its earlier reasoning back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
|
|
197
201
|
|
|
198
|
-
If you persist sessions, keep the
|
|
202
|
+
If you persist sessions, keep the reasoning when you store messages (see [Messages — Reasoning](../MESSAGES.md#reasoning)). If you drop it, later turns lose the model's earlier reasoning, and a tool-calling turn with thinking enabled may be rejected.
|
|
199
203
|
|
|
200
204
|
Only reasoning that Bedrock produced is sent back to Bedrock. A conversation that switches providers midway still works: reasoning from other providers is kept on the messages but left out of Bedrock requests.
|
|
201
205
|
|
data/docs/providers/ANTHROPIC.md
CHANGED
|
@@ -29,12 +29,12 @@ Riffer.configure do |config|
|
|
|
29
29
|
end
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
| Option | Default | Description
|
|
33
|
-
| ------------ | -------------------------------------- |
|
|
34
|
-
| `api_key` | required | Sent as `Authorization: Bearer <api_key>`
|
|
35
|
-
| `base_url` | `https://api.anthropic.com` | API origin; requests go to `<base_url>/v1/messages`
|
|
36
|
-
| `headers` | `{}` | Sent on every request; replaces riffer's headers of the same name
|
|
37
|
-
| `connection` | Faraday defaults, 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections]
|
|
32
|
+
| Option | Default | Description |
|
|
33
|
+
| ------------ | -------------------------------------- | ----------------------------------------------------------------- |
|
|
34
|
+
| `api_key` | required | Sent as `Authorization: Bearer <api_key>` |
|
|
35
|
+
| `base_url` | `https://api.anthropic.com` | API origin; requests go to `<base_url>/v1/messages` |
|
|
36
|
+
| `headers` | `{}` | Sent on every request; replaces riffer's headers of the same name |
|
|
37
|
+
| `connection` | Faraday defaults, 10s open / 600s read | Your own `Faraday::Connection`; see [Connections][connections] |
|
|
38
38
|
|
|
39
39
|
Timeouts, retries, proxies, beta headers and errors are covered in [Configuration → Connections][connections]. An API error becomes a `Riffer::APIError` whose message carries the Anthropic error type, e.g. `Anthropic API error (401): authentication_error: Invalid bearer token`. No requests are retried unless your connection adds retries.
|
|
40
40
|
|
|
@@ -139,8 +139,8 @@ class WeatherTool < Riffer::Tool
|
|
|
139
139
|
description "Gets the current weather for a location"
|
|
140
140
|
|
|
141
141
|
params do
|
|
142
|
-
required :city,
|
|
143
|
-
optional :unit,
|
|
142
|
+
required :city, :string, description: "The city name"
|
|
143
|
+
optional :unit, :string, description: "Temperature unit (celsius or fahrenheit)"
|
|
144
144
|
end
|
|
145
145
|
|
|
146
146
|
def call(context:, city:, unit: "celsius")
|
|
@@ -189,9 +189,11 @@ The reasoning is kept on the assistant message as [reasoning parts](../MESSAGES.
|
|
|
189
189
|
|
|
190
190
|
### Reasoning Replay
|
|
191
191
|
|
|
192
|
-
Riffer sends
|
|
192
|
+
Riffer sends every earlier turn back to Anthropic as the API returned it: the `thinking`, `redacted_thinking`, text, web search and `tool_use` blocks, in their original order and unchanged (see [Messages — Parts](../MESSAGES.md#parts)). Order matters because Claude signs each thinking block over everything before it, including earlier blocks of the same turn. A turn sent back in a different order loses that reasoning, or is rejected with a 400 on accounts that enforce the binding. For tool calls, sending the reasoning back is required: when thinking is enabled, Claude needs its earlier thinking blocks back to carry on after a tool result. You don't have to do anything; it happens as long as the assistant messages stay in the history.
|
|
193
193
|
|
|
194
|
-
If you persist sessions,
|
|
194
|
+
If you persist sessions, `to_h` keeps the web search results and the turn's block order (see [Messages — Parts](../MESSAGES.md#parts)). Dropping the reasoning loses the model's earlier thinking, and a tool-calling turn with thinking enabled may be rejected.
|
|
195
|
+
|
|
196
|
+
If you change a turn's text, drop that turn's reasoning yourself; see [Editing a turn](../MESSAGES.md#parts).
|
|
195
197
|
|
|
196
198
|
Only reasoning that this provider produced is sent back to Anthropic. A conversation that switches providers midway still works: reasoning from other providers (including OpenRouter's `anthropic-claude-v1` parts) is kept on the messages but left out of Anthropic requests.
|
|
197
199
|
|
|
@@ -222,16 +224,51 @@ end
|
|
|
222
224
|
|
|
223
225
|
Anthropic emits sources with `title` and `url` on the `WebSearchDone` event.
|
|
224
226
|
|
|
227
|
+
Each `server_tool_use` block and its result block (`web_search_tool_result`, or `code_execution_tool_result` when a newer web search version runs the search from code execution) is kept on the assistant message as a `ServerToolPart` (see [Messages — Parts](../MESSAGES.md#parts)), and a streamed one also arrives as a `ServerToolDone` event. With `generate`, text blocks with citations keep their block too; a streamed turn keeps the text without its citations. Later turns send them back in place, so Claude reuses the results instead of searching again.
|
|
228
|
+
|
|
229
|
+
### Paused turns
|
|
230
|
+
|
|
231
|
+
When a server tool loop reaches its iteration limit, Anthropic stops with `stop_reason: "pause_turn"`. Riffer sends the paused content back unchanged as the last message and continues the turn, up to 8 times per call, for `generate_text` and `stream_text` alike. If the response names a `container`, its id goes with the next request, so the turn keeps the same container and its files. You get one assistant message: every response's parts in order, the summed token usage and the last response's finish reason. A stream yields one `TextDone`, `FinishReasonDone` and `TokenUsageDone` for the whole turn.
|
|
232
|
+
|
|
233
|
+
A turn still paused after 8 continuations ends with finish reason `:other` (`finish_reason_raw` is `"pause_turn"`). Its last server tool call may have no result, and Anthropic rejects a request that adds a user message after it. Call `generate` or `stream` with no prompt to send the turn back and let Claude carry on.
|
|
234
|
+
|
|
235
|
+
A turn that stops on `max_tokens` is not continued.
|
|
236
|
+
|
|
237
|
+
## Deferred Tools
|
|
238
|
+
|
|
239
|
+
The provider supports [deferred tools](../AGENTS.md#deferred_tools-experimental) through the Messages API's own deferred loading, with no beta header and no tool search tool:
|
|
240
|
+
|
|
241
|
+
```ruby
|
|
242
|
+
class Assistant < Riffer::Agent
|
|
243
|
+
model 'anthropic/claude-haiku-5-5'
|
|
244
|
+
instructions "If you need a tool you don't have, use find_tools."
|
|
245
|
+
|
|
246
|
+
uses_tools [FindTools]
|
|
247
|
+
deferred_tools [ListEvents, CreateEvent]
|
|
248
|
+
end
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
- Every deferred tool is sent on every request with `defer_loading: true`, after the agent's other tools, whether it has been loaded or not. The `tools` array stays the same for the whole conversation, so a load doesn't break the prompt cache.
|
|
252
|
+
- A tool result that [loads tools](../TOOLS.md#loading-deferred-tools-experimental) is sent as `tool_reference` blocks only, one per loaded tool. From then on Claude sees those tools' definitions and calls them by their own names. A load that names a tool the agent no longer defers, for example in a restored history, leaves that tool out, since the API rejects a reference to a tool that isn't in the request.
|
|
253
|
+
|
|
254
|
+
Things to know:
|
|
255
|
+
|
|
256
|
+
- At least one tool in the request must not be deferred, or the API returns a 400 (`All tools cannot be deferred`). An agent needs a tool in `uses_tools` to load its deferred tools anyway.
|
|
257
|
+
- A deferred tool can't carry `cache_control` (400). Riffer never sets it on a tool; the top-level `model_options cache_control: {type: "ephemeral"}` works with deferred tools.
|
|
258
|
+
- Deferred loading needs Claude Haiku 4.5, Sonnet 4.5, Opus 4.5 or a later model. An older model gets the API's own error.
|
|
259
|
+
|
|
260
|
+
With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`, riffer sends the [gateway](../TOOLS.md#the-gateway-strategy) instead of loading them natively.
|
|
261
|
+
|
|
225
262
|
## Message Format
|
|
226
263
|
|
|
227
264
|
The provider converts Riffer messages to Anthropic format:
|
|
228
265
|
|
|
229
|
-
| Riffer Message | Anthropic Format
|
|
230
|
-
| -------------- |
|
|
231
|
-
| `System` | Added to `system` array as `{type: "text", text: ...}`
|
|
232
|
-
| `User` | `{role: "user", content: "..."}`
|
|
233
|
-
| `Assistant` | `{role: "assistant", content: [...]}
|
|
234
|
-
| `Tool` | `{role: "user", content: [{type: "tool_result", ...}]}`
|
|
266
|
+
| Riffer Message | Anthropic Format |
|
|
267
|
+
| -------------- | ------------------------------------------------------------------------ |
|
|
268
|
+
| `System` | Added to `system` array as `{type: "text", text: ...}` |
|
|
269
|
+
| `User` | `{role: "user", content: "..."}` |
|
|
270
|
+
| `Assistant` | `{role: "assistant", content: [...]}`, one block per part, in part order |
|
|
271
|
+
| `Tool` | `{role: "user", content: [{type: "tool_result", ...}]}` |
|
|
235
272
|
|
|
236
273
|
## Direct Provider Usage
|
|
237
274
|
|
|
@@ -133,9 +133,9 @@ class CalculatorTool < Riffer::Tool
|
|
|
133
133
|
description "Performs basic math operations"
|
|
134
134
|
|
|
135
135
|
params do
|
|
136
|
-
required :operation,
|
|
137
|
-
required :a,
|
|
138
|
-
required :b,
|
|
136
|
+
required :operation, :string, enum: ["add", "subtract", "multiply", "divide"]
|
|
137
|
+
required :a, :number, description: "First number"
|
|
138
|
+
required :b, :number, description: "Second number"
|
|
139
139
|
end
|
|
140
140
|
|
|
141
141
|
def call(context:, operation:, a:, b:)
|
|
@@ -155,6 +155,12 @@ class MathAgent < Riffer::Agent
|
|
|
155
155
|
end
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
+
## Deferred Tools (experimental)
|
|
159
|
+
|
|
160
|
+
[Deferred tools](../AGENTS.md#deferred_tools-experimental) load the same way as on the [OpenAI provider](OPENAI.md#deferred-tools-experimental), through `additional_tools` input items. Microsoft documents these items for the Azure OpenAI Responses API in [Use tool search with the Azure OpenAI Responses API](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/tool-search#add-tools-at-a-specific-point-in-the-input), but riffer hasn't been tested against Azure. Which deployments accept them is up to Azure, and one that doesn't returns Azure's own error.
|
|
161
|
+
|
|
162
|
+
With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`, riffer sends the [gateway](../TOOLS.md#the-gateway-strategy) instead of loading them natively.
|
|
163
|
+
|
|
158
164
|
## Direct Provider Usage
|
|
159
165
|
|
|
160
166
|
```ruby
|
|
@@ -233,6 +233,25 @@ def convert_tool(tool)
|
|
|
233
233
|
end
|
|
234
234
|
```
|
|
235
235
|
|
|
236
|
+
### Deferred tools (experimental)
|
|
237
|
+
|
|
238
|
+
The `supports_deferred_tools?` class method says whether your provider loads [deferred tools](../AGENTS.md#deferred_tools-experimental) natively. The default is false, and riffer raises `Riffer::ArgumentError` when an agent with deferred tools and the default `:native` [strategy](../AGENTS.md#deferred-tools-strategy-experimental) is built on your provider. A provider that returns true receives `options[:deferred_tools]`, every deferred tool whether loaded or not, next to `options[:tools]`, and works out what each tool result loaded from its `loaded_tools`.
|
|
239
|
+
|
|
240
|
+
An agent with `strategy: :gateway` works on your provider either way, through the [gateway](../TOOLS.md#the-gateway-strategy), with no code in your provider. It never sees `options[:deferred_tools]`, even if `supports_deferred_tools?` returns true. Instead, `build_request_params` receives:
|
|
241
|
+
|
|
242
|
+
- `options[:tools]` with `Riffer::Providers::DeferredToolGateway::Tool` on the end, on every request of an agent with deferred tools. It's an ordinary `Riffer::Tool` named `riffer_gateway`, so your tool conversion handles it, strict mode included.
|
|
243
|
+
- Messages where each call to a deferred tool is a call to the gateway, its result is named after the gateway, and a result that loaded tools has their descriptions appended to its content.
|
|
244
|
+
|
|
245
|
+
The model's calls to the gateway that you return from `extract_tool_calls`, or stream as `ToolCallDone` events, are turned back into calls to the real tools before they leave the provider, and the `ToolCallDelta` events you stream for them are dropped.
|
|
246
|
+
|
|
247
|
+
This hook is experimental too: `supports_deferred_tools?` and the `options[:deferred_tools]` it gates can change or be replaced in any minor release, for example by a capability in the [model catalog](../CATALOG.md) (see [Stability](../STABILITY.md#experimental-features)).
|
|
248
|
+
|
|
249
|
+
```ruby
|
|
250
|
+
def self.supports_deferred_tools?
|
|
251
|
+
true
|
|
252
|
+
end
|
|
253
|
+
```
|
|
254
|
+
|
|
236
255
|
## Stream Events
|
|
237
256
|
|
|
238
257
|
Use the appropriate stream event classes in `execute_stream`:
|
|
@@ -259,6 +278,9 @@ Riffer::StreamEvents::ToolCallDone.new(
|
|
|
259
278
|
Riffer::StreamEvents::ReasoningDelta.new("thinking...")
|
|
260
279
|
Riffer::StreamEvents::ReasoningDone.new(part)
|
|
261
280
|
|
|
281
|
+
# Server tool blocks (if supported); see the Ordered Parts section
|
|
282
|
+
Riffer::StreamEvents::ServerToolDone.new(server_tool_part)
|
|
283
|
+
|
|
262
284
|
# Web search (if supported)
|
|
263
285
|
Riffer::StreamEvents::WebSearchStatus.new("searching", query: "search query")
|
|
264
286
|
Riffer::StreamEvents::WebSearchDone.new(
|
|
@@ -343,6 +365,27 @@ yielder << Riffer::StreamEvents::ReasoningDone.new(part)
|
|
|
343
365
|
|
|
344
366
|
If your adapter surfaces reasoning text but cannot yet replay it, call `yield_reasoning_done(yielder, text)` instead. It wraps the text in a `:text` part with no `format`, which persists for display and is skipped on replay.
|
|
345
367
|
|
|
368
|
+
## Ordered Parts
|
|
369
|
+
|
|
370
|
+
By default the base class builds the assistant message's [parts](../MESSAGES.md#parts) from `extract_reasoning`, `extract_content` and `extract_tool_calls`, in that order. If your provider interleaves blocks in one turn and needs them back in that order, override `extract_parts` instead and return every block as a part, in response order:
|
|
371
|
+
|
|
372
|
+
```ruby
|
|
373
|
+
def extract_parts(response)
|
|
374
|
+
response.blocks.filter_map do |block|
|
|
375
|
+
case block.type
|
|
376
|
+
when "text" then Riffer::Messages::Assistant::TextPart.new(block.text)
|
|
377
|
+
when "thinking" then Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: block.text, signature: block.signature, format: "my-provider-v1")
|
|
378
|
+
when "tool_call" then Riffer::Messages::Assistant::ToolCall.new(call_id: block.id, name: block.name, arguments: block.arguments)
|
|
379
|
+
when "search" then Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, id: block.id, data: block.to_json, format: "my-provider-v1")
|
|
380
|
+
end
|
|
381
|
+
end
|
|
382
|
+
end
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
Then replay by walking `message.parts` rather than reading `content`, `tool_calls` and `reasoning` separately, and skip parts whose `format` you don't recognize.
|
|
386
|
+
|
|
387
|
+
For streaming, emit `ServerToolDone` for each server tool block, and keep text deltas, `ReasoningDone` and `ToolCallDone` in the order the blocks arrive. The agent loop builds the parts in that order.
|
|
388
|
+
|
|
346
389
|
## Reasoning Level
|
|
347
390
|
|
|
348
391
|
When an agent sets [`reasoning`](../AGENTS.md#reasoning), riffer resolves the level to `model_options` params before calling `build_request_params`, so your provider receives ordinary options and never sees the level itself. It uses the model's [catalog](../CATALOG.md#reasoning) entry under your registration key first, then your provider's default. Override the private `default_reasoning_options` to supply one:
|
data/docs/providers/GEMINI.md
CHANGED
|
@@ -132,8 +132,8 @@ end
|
|
|
132
132
|
|
|
133
133
|
```ruby
|
|
134
134
|
params = Riffer::Params.new
|
|
135
|
-
params.required(:sentiment,
|
|
136
|
-
params.required(:score,
|
|
135
|
+
params.required(:sentiment, :string)
|
|
136
|
+
params.required(:score, :number)
|
|
137
137
|
structured_output = Riffer::Agent::StructuredOutput.new(params)
|
|
138
138
|
|
|
139
139
|
response = provider.generate_text(
|
|
@@ -146,7 +146,7 @@ puts response.structured_output
|
|
|
146
146
|
|
|
147
147
|
Structured output is sent as `responseFormat`, which needs a gemini-3 model or later. gemini-2.x models ignore it and return prose.
|
|
148
148
|
|
|
149
|
-
The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up.
|
|
149
|
+
The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. An `:object` param needs a block and an `:array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
|
|
150
150
|
|
|
151
151
|
### Tool Calling
|
|
152
152
|
|
|
@@ -154,7 +154,7 @@ The schema is sent in strict form: every field is listed as required, and an opt
|
|
|
154
154
|
class WeatherTool < Riffer::Tool
|
|
155
155
|
description "Gets weather"
|
|
156
156
|
params do
|
|
157
|
-
required :city,
|
|
157
|
+
required :city, :string
|
|
158
158
|
end
|
|
159
159
|
def call(context:, city:)
|
|
160
160
|
text("Sunny in #{city}")
|
|
@@ -170,13 +170,17 @@ response = provider.generate_text(
|
|
|
170
170
|
|
|
171
171
|
Gemini's own call ids are short, so riffer gives each tool call its own `call_id` (`gemini_call_<hex>`) and appends Gemini's id when there is one. On later turns riffer sends that id back on the function call and its result, so Gemini can match results to parallel calls of the same tool.
|
|
172
172
|
|
|
173
|
+
### Deferred Tools (experimental)
|
|
174
|
+
|
|
175
|
+
Gemini has no native deferred loading, so an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) on Gemini needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`; without it, building the agent raises `Riffer::ArgumentError`. Every request then has one extra function in `functionDeclarations`, the [gateway](../TOOLS.md#the-gateway-strategy), and the model calls a loaded tool through it, so the declarations stay the same and a load keeps the prompt cache. Calls come back under the real tool's name.
|
|
176
|
+
|
|
173
177
|
### Thought Signatures
|
|
174
178
|
|
|
175
179
|
Gemini 3 models attach an opaque `thoughtSignature` to the first function call of each step, and to the last text part of an answer. A later request that sends a function call back without its signature is rejected with a 400.
|
|
176
180
|
|
|
177
181
|
Riffer keeps each signature on the assistant message as the `data` of an `:encrypted` [reasoning part](../MESSAGES.md#reasoning) tagged `format: "gemini-generate-content-v1"` (`Riffer::Providers::Gemini::REASONING_FORMAT`). A signature from a function call carries that tool call's `call_id` as its `id`; the text signature has no `id`. Streams emit them as `ReasoningDone` events. On later turns riffer puts each signature back on the part it came from. You don't have to do anything as long as the assistant messages stay in the history.
|
|
178
182
|
|
|
179
|
-
A function call that Gemini didn't sign, such as one another provider made before the conversation switched to Gemini, goes out with Gemini's placeholder signature (`skip_thought_signature_validator`), which Gemini accepts in place of a real one. That covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the
|
|
183
|
+
A function call that Gemini didn't sign, such as one another provider made before the conversation switched to Gemini, goes out with Gemini's placeholder signature (`skip_thought_signature_validator`), which Gemini accepts in place of a real one. That covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
|
|
180
184
|
|
|
181
185
|
### Web Search
|
|
182
186
|
|
|
@@ -224,8 +224,8 @@ end
|
|
|
224
224
|
|
|
225
225
|
```ruby
|
|
226
226
|
params = Riffer::Params.new
|
|
227
|
-
params.required(:sentiment,
|
|
228
|
-
params.required(:score,
|
|
227
|
+
params.required(:sentiment, :string)
|
|
228
|
+
params.required(:score, :number)
|
|
229
229
|
structured_output = Riffer::Agent::StructuredOutput.new(params)
|
|
230
230
|
|
|
231
231
|
response = provider.generate_text(
|
|
@@ -236,7 +236,7 @@ response = provider.generate_text(
|
|
|
236
236
|
puts response.structured_output
|
|
237
237
|
```
|
|
238
238
|
|
|
239
|
-
The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up.
|
|
239
|
+
The schema is sent in strict form: every field is listed as required, and an optional field is nullable, so the model can return `null` for a value it doesn't know instead of making one up. An `:object` param needs a block and an `:array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
|
|
240
240
|
|
|
241
241
|
### Tool Calling
|
|
242
242
|
|
|
@@ -244,7 +244,7 @@ The schema is sent in strict form: every field is listed as required, and an opt
|
|
|
244
244
|
class WeatherTool < Riffer::Tool
|
|
245
245
|
description "Gets weather"
|
|
246
246
|
params do
|
|
247
|
-
required :city,
|
|
247
|
+
required :city, :string
|
|
248
248
|
end
|
|
249
249
|
def call(context:, city:)
|
|
250
250
|
text("Sunny in #{city}")
|
|
@@ -260,13 +260,17 @@ response = provider.generate_text(
|
|
|
260
260
|
|
|
261
261
|
Riffer gives each tool call its own `call_id` (`gemini_call_<hex>`) and appends the model's id when there is one. On later turns riffer sends that id back on the function call and its result, so the model can match results to parallel calls of the same tool.
|
|
262
262
|
|
|
263
|
+
### Deferred Tools (experimental)
|
|
264
|
+
|
|
265
|
+
Gemini models have no native deferred loading, so on `google_cloud` an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), the same way as on [Gemini → Deferred Tools](GEMINI.md#deferred-tools-experimental). Claude models on `anthropic_vertex` load them natively.
|
|
266
|
+
|
|
263
267
|
### Thought Signatures
|
|
264
268
|
|
|
265
269
|
Gemini 3 models attach an opaque `thoughtSignature` to the first function call of each step, and to the last text part of an answer. A later request that sends a function call back without its signature is rejected with a 400.
|
|
266
270
|
|
|
267
271
|
Riffer keeps each signature on the assistant message as the `data` of an `:encrypted` [reasoning part](../MESSAGES.md#reasoning) tagged `format: "google-cloud-generate-content-v1"` (`Riffer::Providers::GoogleCloud::REASONING_FORMAT`). A signature from a function call carries that tool call's `call_id` as its `id`; the text signature has no `id`. Streams emit them as `ReasoningDone` events. On later turns riffer puts each signature back on the part it came from. You don't have to do anything as long as the assistant messages stay in the history.
|
|
268
272
|
|
|
269
|
-
A function call without an Agent Platform signature goes out with Google's placeholder signature (`skip_thought_signature_validator`), which Agent Platform accepts in place of a real one. That happens when the call came from another provider, or from the Gemini Developer API, whose signatures Agent Platform rejects. It covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the
|
|
273
|
+
A function call without an Agent Platform signature goes out with Google's placeholder signature (`skip_thought_signature_validator`), which Agent Platform accepts in place of a real one. That happens when the call came from another provider, or from the Gemini Developer API, whose signatures Agent Platform rejects. It covers the first call of each step when that call has no signature for this provider. Google warns that a call without its real signature may degrade the model's answer, so if you persist sessions, keep the reasoning when you store messages.
|
|
270
274
|
|
|
271
275
|
### Web Search
|
|
272
276
|
|
|
@@ -349,6 +353,7 @@ Claude models on Agent Platform behave as they do on the Anthropic provider:
|
|
|
349
353
|
- **Reasoning** is captured as [reasoning parts](../MESSAGES.md#reasoning) tagged `format: "anthropic-messages-v1"` and sent back on later turns, as described in [Anthropic → Reasoning Replay](ANTHROPIC.md#reasoning-replay). Thinking signatures are accepted by both APIs, so a conversation can move between `anthropic` and `anthropic_vertex`. The agent-level [`reasoning`](../AGENTS.md#reasoning) setting uses the Anthropic default; [catalog](../CATALOG.md#reasoning) entries go under `anthropic_vertex/...` keys.
|
|
350
354
|
- **Web search:** `web_search: true` (or a hash of options) adds the `web_search_20250305` server tool and streams `WebSearchStatus` / `WebSearchDone` events.
|
|
351
355
|
- **Structured output** is sent as a strict `output_config.format` JSON schema.
|
|
356
|
+
- **Deferred tools** are loaded natively, the same way as on [Anthropic → Deferred Tools](ANTHROPIC.md#deferred-tools).
|
|
352
357
|
- **Skills** are rendered with the XML skills adapter.
|
|
353
358
|
- **Tags:** only the reserved `user_id` tag is sent, as `metadata.user_id`.
|
|
354
359
|
- **Incomplete streams:** a stream that ends without a `message_stop` event raises `Riffer::IncompleteStreamError`.
|
|
@@ -96,6 +96,10 @@ provider.calls
|
|
|
96
96
|
expect(provider.calls.last[:messages].last[:content]).to eq("Hi")
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
+
Each message is recorded as its `to_h`, so an assistant message has `parts` rather than `content` (see [Messages — Parts](../MESSAGES.md#parts)).
|
|
100
|
+
|
|
101
|
+
The Mock provider loads [deferred tools](../AGENTS.md#deferred_tools-experimental) natively, so you can test them without a real provider. For an agent with deferred tools, each recorded call also has `deferred_tools:`, every deferred tool whether loaded or not. With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental) it doesn't load them natively: recorded calls have no `deferred_tools:`, the gateway is last in `tools:`, the messages are as the gateway sends them, and a stubbed call to the gateway (`Riffer::Providers::DeferredToolGateway::Tool.name`) comes back as a call to the real tool.
|
|
102
|
+
|
|
99
103
|
## Clearing State
|
|
100
104
|
|
|
101
105
|
Reset stubbed responses:
|
data/docs/providers/OPENAI.md
CHANGED
|
@@ -96,7 +96,7 @@ Each `reasoning` item in a Responses API output becomes [reasoning parts](../MES
|
|
|
96
96
|
|
|
97
97
|
The `:encrypted` part is always present, even when the response carried no `encrypted_content`, so the item's `id` is kept. When streaming, the parts are yielded as `ReasoningDone` events once the item completes; summary text still arrives as `ReasoningDelta` events before that.
|
|
98
98
|
|
|
99
|
-
On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the
|
|
99
|
+
On the next request, parts sharing an `id` go back as one `reasoning` item, ahead of the assistant's text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don't have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the reasoning when you store them.
|
|
100
100
|
|
|
101
101
|
With `store` left on (the API default), OpenAI can resolve a replayed item from its `id` alone. With `model_options store: false`, the item can only be replayed from its encrypted payload, so request it explicitly:
|
|
102
102
|
|
|
@@ -118,6 +118,8 @@ model_options web_search: true
|
|
|
118
118
|
model_options web_search: {search_context_size: "medium"}
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
+
With web search on, riffer also adds `"web_search_call.action.sources"` to the request's `include`, keeping any entries you pass, so `WebSearchDone` carries the sources OpenAI searched.
|
|
122
|
+
|
|
121
123
|
## Example
|
|
122
124
|
|
|
123
125
|
```ruby
|
|
@@ -160,9 +162,9 @@ class CalculatorTool < Riffer::Tool
|
|
|
160
162
|
description "Performs basic math operations"
|
|
161
163
|
|
|
162
164
|
params do
|
|
163
|
-
required :operation,
|
|
164
|
-
required :a,
|
|
165
|
-
required :b,
|
|
165
|
+
required :operation, :string, enum: ["add", "subtract", "multiply", "divide"]
|
|
166
|
+
required :a, :number, description: "First number"
|
|
167
|
+
required :b, :number, description: "Second number"
|
|
166
168
|
end
|
|
167
169
|
|
|
168
170
|
def call(context:, operation:, a:, b:)
|
|
@@ -182,6 +184,28 @@ class MathAgent < Riffer::Agent
|
|
|
182
184
|
end
|
|
183
185
|
```
|
|
184
186
|
|
|
187
|
+
## Deferred Tools (experimental)
|
|
188
|
+
|
|
189
|
+
The OpenAI provider loads [deferred tools](../AGENTS.md#deferred_tools-experimental) natively:
|
|
190
|
+
|
|
191
|
+
```ruby
|
|
192
|
+
class Assistant < Riffer::Agent
|
|
193
|
+
model 'openai/gpt-5.4-mini'
|
|
194
|
+
instructions "If you need a calendar tool you don't have, call connect_calendar first."
|
|
195
|
+
|
|
196
|
+
uses_tools [ConnectCalendar]
|
|
197
|
+
deferred_tools [ListEvents, CreateEvent]
|
|
198
|
+
end
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
A deferred tool is left out of the request's `tools`. When a tool [loads it](../TOOLS.md#loading-deferred-tools-experimental), its full definition is sent in an `additional_tools` input item placed right after that tool's `function_call_output`, and the model can call it from its next turn. `tools` stays the same for the whole conversation and earlier input items never change, so loading a tool keeps the prompt cache. The loading tool's own output is empty.
|
|
202
|
+
|
|
203
|
+
Riffer rebuilds the `additional_tools` items from the `loaded_tools` on the conversation's [tool messages](../MESSAGES.md#tool) on every request, so a restored session, or one started on another provider, loads the same tools. A tool loaded again is sent again, after each result that loaded it: without fresh definitions, a model that reloads a tool it already has can keep calling the loading tool instead of the loaded one.
|
|
204
|
+
|
|
205
|
+
OpenAI returns a call to a loaded tool with a `namespace` field, and rejects a later request that replays the call without it. That namespace is always the tool's own name as sent to OpenAI, so riffer adds it back to every replayed call to a deferred tool and never stores it. Tools, the session, callbacks and traces see an ordinary tool call.
|
|
206
|
+
|
|
207
|
+
With the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`, riffer sends the [gateway](../TOOLS.md#the-gateway-strategy) instead of loading them natively.
|
|
208
|
+
|
|
185
209
|
## Web Search
|
|
186
210
|
|
|
187
211
|
Web search allows the model to search the web for up-to-date information. When enabled, the provider injects the `web_search_preview` tool into the request.
|
|
@@ -151,9 +151,9 @@ Tools are converted to OpenAI Chat Completions function format. The provider han
|
|
|
151
151
|
class CalculatorTool < Riffer::Tool
|
|
152
152
|
description 'Performs basic math'
|
|
153
153
|
params do
|
|
154
|
-
required :operation,
|
|
155
|
-
required :a,
|
|
156
|
-
required :b,
|
|
154
|
+
required :operation, :string, enum: ['add', 'subtract', 'multiply', 'divide']
|
|
155
|
+
required :a, :number
|
|
156
|
+
required :b, :number
|
|
157
157
|
end
|
|
158
158
|
|
|
159
159
|
def call(context:, operation:, a:, b:)
|
|
@@ -173,6 +173,14 @@ class MathAgent < Riffer::Agent
|
|
|
173
173
|
end
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
+
## Deferred Tools (experimental)
|
|
177
|
+
|
|
178
|
+
OpenRouter has no native deferred loading, so an agent with [deferred tools](../AGENTS.md#deferred_tools-experimental) on OpenRouter needs the [gateway strategy](../AGENTS.md#deferred-tools-strategy-experimental), `deferred_tools [...], strategy: :gateway`; without it, building the agent raises `Riffer::ArgumentError`. Every request then has one extra function in `tools`, the [gateway](../TOOLS.md#the-gateway-strategy), and the model calls a loaded tool through it, so `tools` stays the same and a load keeps the prompt cache. Calls come back under the real tool's name.
|
|
179
|
+
|
|
180
|
+
The gateway is sent with `strict: true`, like every other tool. Its parameters are two required strings, `name` and `arguments` (the loaded tool's arguments, JSON-encoded), with no additional properties, so the schema is valid in strict mode; riffer checks the arguments against the real tool's `params` when it runs.
|
|
181
|
+
|
|
182
|
+
The tool list holding steady keeps the cache valid, but whether the next request reads it is up to OpenRouter's routing. A model served by several upstreams can have its requests spread across them, and they share no cache, so the turn after a load may miss. Pin one upstream with [`provider`](#provider-routing-preferences) (`provider: {order: ['coreweave'], allow_fallbacks: false}`) when cache hits matter.
|
|
183
|
+
|
|
176
184
|
## Reasoning Models
|
|
177
185
|
|
|
178
186
|
Reasoning models surface their thought process via OpenRouter's normalised `reasoning_details` field. Enable it with the `reasoning` option:
|
data/docs/providers/PROVIDERS.md
CHANGED
data/docs-site/index.html.erb
CHANGED
|
@@ -84,7 +84,7 @@
|
|
|
84
84
|
description <span class="s">'Current weather for a city'</span>
|
|
85
85
|
|
|
86
86
|
params <span class="k">do</span>
|
|
87
|
-
required :city,
|
|
87
|
+
required :city, :string, description: <span class="s">'City name'</span>
|
|
88
88
|
<span class="k">end</span>
|
|
89
89
|
|
|
90
90
|
<span class="k">def</span> call(context:, city:)
|
data/docs-site/manifest.yml
CHANGED
data/lib/riffer/agent/config.rb
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
class Riffer::Agent::Config
|
|
5
5
|
DEFAULT_MAX_STEPS = 16 #: Integer
|
|
6
6
|
STRUCTURED_OUTPUT_STRATEGIES = %i[native prompted].freeze #: Array[Symbol]
|
|
7
|
+
DEFERRED_TOOLS_STRATEGIES = %i[native gateway].freeze #: Array[Symbol]
|
|
7
8
|
|
|
8
9
|
REASONING_LEVELS = %i[off low medium high xhigh max].freeze #: Array[Symbol]
|
|
9
10
|
|
|
@@ -18,6 +19,8 @@ class Riffer::Agent::Config
|
|
|
18
19
|
attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
|
|
19
20
|
attr_reader :reasoning #: Symbol? # @dynamic reasoning
|
|
20
21
|
attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
|
|
22
|
+
attr_accessor :deferred_tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic deferred_tools_config, deferred_tools_config=
|
|
23
|
+
attr_reader :deferred_tools_strategy #: Symbol # @dynamic deferred_tools_strategy
|
|
21
24
|
attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
|
|
22
25
|
attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
|
|
23
26
|
attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
|
|
@@ -33,6 +36,8 @@ class Riffer::Agent::Config
|
|
|
33
36
|
# ?max_steps: Numeric?,
|
|
34
37
|
# ?reasoning: (Symbol | String)?,
|
|
35
38
|
# ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
|
|
39
|
+
# ?deferred_tools_config: (Array[singleton(Riffer::Tool)] | Proc)?,
|
|
40
|
+
# ?deferred_tools_strategy: Symbol,
|
|
36
41
|
# ?mcp_configs: Array[Hash[Symbol, untyped]],
|
|
37
42
|
# ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
|
|
38
43
|
# ?skills_config: Riffer::Skills::Config?,
|
|
@@ -48,6 +53,8 @@ class Riffer::Agent::Config
|
|
|
48
53
|
max_steps: DEFAULT_MAX_STEPS,
|
|
49
54
|
reasoning: nil,
|
|
50
55
|
tools_config: nil,
|
|
56
|
+
deferred_tools_config: nil,
|
|
57
|
+
deferred_tools_strategy: :native,
|
|
51
58
|
mcp_configs: [],
|
|
52
59
|
tool_runtime: nil,
|
|
53
60
|
skills_config: nil,
|
|
@@ -56,6 +63,7 @@ class Riffer::Agent::Config
|
|
|
56
63
|
@model_options = model_options
|
|
57
64
|
@max_steps = max_steps
|
|
58
65
|
@tools_config = tools_config
|
|
66
|
+
@deferred_tools_config = deferred_tools_config
|
|
59
67
|
@mcp_configs = mcp_configs
|
|
60
68
|
@skills_config = skills_config
|
|
61
69
|
@guardrails = guardrails
|
|
@@ -64,6 +72,7 @@ class Riffer::Agent::Config
|
|
|
64
72
|
self.instructions = instructions
|
|
65
73
|
self.structured_output = structured_output
|
|
66
74
|
self.structured_output_strategy = structured_output_strategy
|
|
75
|
+
self.deferred_tools_strategy = deferred_tools_strategy
|
|
67
76
|
self.reasoning = reasoning
|
|
68
77
|
self.tool_runtime = tool_runtime if tool_runtime
|
|
69
78
|
end
|
|
@@ -95,6 +104,17 @@ class Riffer::Agent::Config
|
|
|
95
104
|
@structured_output_strategy = value
|
|
96
105
|
end
|
|
97
106
|
|
|
107
|
+
#--
|
|
108
|
+
#: (Symbol) -> Symbol
|
|
109
|
+
def deferred_tools_strategy=(value)
|
|
110
|
+
unless DEFERRED_TOOLS_STRATEGIES.include?(value)
|
|
111
|
+
raise Riffer::ArgumentError,
|
|
112
|
+
"deferred_tools_strategy must be one of #{DEFERRED_TOOLS_STRATEGIES.inspect}, got #{value.inspect}"
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
@deferred_tools_strategy = value
|
|
116
|
+
end
|
|
117
|
+
|
|
98
118
|
#--
|
|
99
119
|
#: ((Symbol | String)?) -> Symbol?
|
|
100
120
|
def reasoning=(value)
|
|
@@ -189,6 +209,7 @@ class Riffer::Agent::Config
|
|
|
189
209
|
@mcp_configs = Riffer::Helpers::DeepDup.call(source.mcp_configs)
|
|
190
210
|
@guardrails = Riffer::Helpers::DeepDup.call(source.guardrails)
|
|
191
211
|
@tools_config = Riffer::Helpers::DeepDup.call(source.tools_config)
|
|
212
|
+
@deferred_tools_config = Riffer::Helpers::DeepDup.call(source.deferred_tools_config)
|
|
192
213
|
@skills_config = source.skills_config&.dup
|
|
193
214
|
@structured_output = source.structured_output&.dup
|
|
194
215
|
end
|
data/lib/riffer/agent/context.rb
CHANGED
|
@@ -15,12 +15,14 @@ class Riffer::Agent::Context
|
|
|
15
15
|
raise Riffer::ArgumentError,
|
|
16
16
|
"Reserved keys cannot be passed in context: #{reserved.join(', ')}"
|
|
17
17
|
end
|
|
18
|
+
warn_deferred_tools_key if data.key?(:deferred_tools)
|
|
18
19
|
|
|
19
20
|
@data = data.dup
|
|
20
21
|
@data[:skills] = nil
|
|
21
22
|
@data[:token_usage] = nil
|
|
22
23
|
@data[:mcp_progressive_tools] = nil
|
|
23
24
|
@data[:discovered_tools] = nil
|
|
25
|
+
@deferred_tools = nil
|
|
24
26
|
end
|
|
25
27
|
|
|
26
28
|
#--
|
|
@@ -71,15 +73,7 @@ class Riffer::Agent::Context
|
|
|
71
73
|
#--
|
|
72
74
|
#: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
|
|
73
75
|
def mcp_progressive_tools=(value)
|
|
74
|
-
|
|
75
|
-
value.is_a?(Array) &&
|
|
76
|
-
value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool }
|
|
77
|
-
)
|
|
78
|
-
unless valid
|
|
79
|
-
raise Riffer::ArgumentError,
|
|
80
|
-
"mcp_progressive_tools must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
|
|
81
|
-
end
|
|
82
|
-
@data[:mcp_progressive_tools] = value
|
|
76
|
+
@data[:mcp_progressive_tools] = validate_tool_classes(:mcp_progressive_tools, value)
|
|
83
77
|
end
|
|
84
78
|
|
|
85
79
|
#--
|
|
@@ -91,15 +85,15 @@ class Riffer::Agent::Context
|
|
|
91
85
|
#--
|
|
92
86
|
#: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
|
|
93
87
|
def discovered_tools=(value)
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
@
|
|
88
|
+
@data[:discovered_tools] = validate_tool_classes(:discovered_tools, value)
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
attr_reader :deferred_tools #: Array[singleton(Riffer::Tool)]? # @dynamic deferred_tools
|
|
92
|
+
|
|
93
|
+
#--
|
|
94
|
+
#: (Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
|
|
95
|
+
def deferred_tools=(value)
|
|
96
|
+
@deferred_tools = validate_tool_classes(:deferred_tools, value)
|
|
103
97
|
end
|
|
104
98
|
|
|
105
99
|
#--
|
|
@@ -120,4 +114,28 @@ class Riffer::Agent::Context
|
|
|
120
114
|
def to_h
|
|
121
115
|
@data.dup
|
|
122
116
|
end
|
|
117
|
+
|
|
118
|
+
private
|
|
119
|
+
|
|
120
|
+
#--
|
|
121
|
+
#: (Symbol, Array[singleton(Riffer::Tool)]?) -> Array[singleton(Riffer::Tool)]?
|
|
122
|
+
def validate_tool_classes(name, value)
|
|
123
|
+
valid = value.nil? || (value.is_a?(Array) && value.all? { |tool| tool.is_a?(Class) && tool < Riffer::Tool })
|
|
124
|
+
unless valid
|
|
125
|
+
raise Riffer::ArgumentError,
|
|
126
|
+
"#{name} must be an Array of Riffer::Tool subclasses or nil, got #{value.class}"
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
value
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
#--
|
|
133
|
+
#: () -> void
|
|
134
|
+
def warn_deferred_tools_key
|
|
135
|
+
Riffer::Deprecation.warn(
|
|
136
|
+
id: :context_deferred_tools_key,
|
|
137
|
+
message: "Passing :deferred_tools in context: is deprecated; a future breaking release reserves the key " \
|
|
138
|
+
"for the agent's deferred tools (context.deferred_tools). Rename the key.",
|
|
139
|
+
)
|
|
140
|
+
end
|
|
123
141
|
end
|