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
data/docs/MESSAGES.md
CHANGED
|
@@ -57,7 +57,7 @@ msg = Riffer::Messages::Assistant.new("", tool_calls: [
|
|
|
57
57
|
{id: "call_123", call_id: "call_123", name: "weather_tool", arguments: '{"city":"Tokyo"}'}
|
|
58
58
|
])
|
|
59
59
|
msg.tool_calls # => [{id: "call_123", ...}]
|
|
60
|
-
msg.to_h # => {role:
|
|
60
|
+
msg.to_h # => {role: :assistant, parts: [{part: :tool_call, ...}]}
|
|
61
61
|
|
|
62
62
|
# Accessing token usage data (when available from provider)
|
|
63
63
|
if msg.token_usage
|
|
@@ -134,7 +134,7 @@ The `to_h` representation includes `structured_output` only when present:
|
|
|
134
134
|
|
|
135
135
|
```ruby
|
|
136
136
|
msg = Riffer::Messages::Assistant.new('{"sentiment":"positive"}', structured_output: {sentiment: "positive"})
|
|
137
|
-
msg.to_h # => {role: :assistant,
|
|
137
|
+
msg.to_h # => {role: :assistant, parts: [{part: :text, text: '{"sentiment":"positive"}'}], structured_output: {sentiment: "positive"}}
|
|
138
138
|
```
|
|
139
139
|
|
|
140
140
|
#### Reasoning
|
|
@@ -170,13 +170,14 @@ A `type` outside the three values raises `Riffer::ArgumentError`. `format` is a
|
|
|
170
170
|
|
|
171
171
|
`reasoning?` is true when the message carries any part. `reasoning_text` joins the `text` of the `:text` and `:summary` parts with blank lines, skipping `:encrypted` parts, and is `nil` when there is nothing to join. The run's final assistant message projects its parts onto `response.reasoning` (see [Agent Lifecycle — Response Attributes](AGENT_LIFECYCLE.md#response-attributes)).
|
|
172
172
|
|
|
173
|
-
Parts round-trip through `to_h` / `from_hash` like every other message field, so an application that persists sessions can store and replay them.
|
|
173
|
+
Parts round-trip through `to_h` / `from_hash` like every other message field, so an application that persists sessions can store and replay them. `to_h` writes each reasoning part as a [`parts`](#parts) entry tagged `part: :reasoning`, and each part omits the fields it doesn't carry:
|
|
174
174
|
|
|
175
175
|
```ruby
|
|
176
176
|
msg.to_h
|
|
177
|
-
# => {role: :assistant,
|
|
178
|
-
# {type: :summary, text: "The user wants the answer.", format: "mock-v1"},
|
|
179
|
-
# {type: :encrypted, data: "b3BhcXVl", format: "mock-v1"}
|
|
177
|
+
# => {role: :assistant, parts: [
|
|
178
|
+
# {part: :reasoning, type: :summary, text: "The user wants the answer.", format: "mock-v1"},
|
|
179
|
+
# {part: :reasoning, type: :encrypted, data: "b3BhcXVl", format: "mock-v1"},
|
|
180
|
+
# {part: :text, text: "42"}
|
|
180
181
|
# ]}
|
|
181
182
|
|
|
182
183
|
Riffer::Messages::Base.from_hash(msg.to_h).reasoning # => [ReasoningPart, ReasoningPart]
|
|
@@ -184,14 +185,108 @@ Riffer::Messages::Base.from_hash(msg.to_h).reasoning # => [ReasoningPart, Reaso
|
|
|
184
185
|
|
|
185
186
|
**The replay contract.** A provider adapter replays only the parts whose `format` it recognizes and silently skips the rest, so history that travelled through another provider is never rejected. A part with no `format` is never replayed; adapters that surface reasoning text but cannot yet send it back emit their parts that way, so the text is kept for display without risking a rejected request. Parts are never reordered, merged, or edited — riffer treats them as opaque, because the provider's signature covers their exact bytes.
|
|
186
187
|
|
|
187
|
-
An application that would rather not store
|
|
188
|
+
An application that would rather not store reasoning can drop the reasoning entries of `parts` when it serializes:
|
|
188
189
|
|
|
189
190
|
```ruby
|
|
190
|
-
msg.to_h
|
|
191
|
+
hash = msg.to_h
|
|
192
|
+
hash[:parts] = hash[:parts].reject { |part| part[:part] == :reasoning }
|
|
191
193
|
```
|
|
192
194
|
|
|
193
195
|
To drop parts from the in-memory session mid-run instead, `Session#update(id:, reasoning: [])` rewrites the message in place; it needs [message ids](#ids) enabled to address it.
|
|
194
196
|
|
|
197
|
+
#### Parts
|
|
198
|
+
|
|
199
|
+
`parts` is the assistant turn in the order the provider produced it. `content`, `tool_calls` and `reasoning` are views over it. Some providers interleave reasoning, server-side tools and text in one turn, and Anthropic needs the turn back in that order: Claude signs each thinking block over every block before it. Sending earlier turns back unchanged also keeps the model's own reasoning and search results, and keeps the prompt cache warm, since the history doesn't change between requests.
|
|
200
|
+
|
|
201
|
+
A part is one of:
|
|
202
|
+
|
|
203
|
+
| Class | Holds |
|
|
204
|
+
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
205
|
+
| `TextPart` | One stretch of answer text (`text`). `data` keeps the provider's block when it carries more than the text, such as Anthropic citations |
|
|
206
|
+
| `ReasoningPart` | A thinking block (see [Reasoning](#reasoning)) |
|
|
207
|
+
| `ToolCall` | A function call riffer runs (see [Tool Calls](#tool-calls)) |
|
|
208
|
+
| `ServerToolPart` | A call (`kind: :call`) or result (`kind: :result`) of a tool the provider ran itself, such as web search |
|
|
209
|
+
|
|
210
|
+
`TextPart` carries:
|
|
211
|
+
|
|
212
|
+
| Field | Type | Description |
|
|
213
|
+
| -------- | --------- | ------------------------------------------------------------------------------------------------------ |
|
|
214
|
+
| `text` | `String` | The answer text |
|
|
215
|
+
| `data` | `String?` | The provider's whole block as JSON, kept when it carries more than the text (e.g. Anthropic citations) |
|
|
216
|
+
| `format` | `String?` | The wire format of `data`, owned by the adapter that produced it |
|
|
217
|
+
|
|
218
|
+
`ServerToolPart` carries:
|
|
219
|
+
|
|
220
|
+
| Field | Type | Description |
|
|
221
|
+
| -------- | --------- | --------------------------------------------------------------------------------------------- |
|
|
222
|
+
| `name` | `String` | The tool's name (e.g. `"web_search"`) |
|
|
223
|
+
| `kind` | `Symbol` | `:call` or `:result` |
|
|
224
|
+
| `data` | `String` | The provider's block as JSON, unchanged |
|
|
225
|
+
| `id` | `String?` | The provider's identifier, shared by a call and its result |
|
|
226
|
+
| `format` | `String?` | The wire format, owned by the adapter that produced the part (e.g. `"anthropic-messages-v1"`) |
|
|
227
|
+
|
|
228
|
+
A `kind` outside `:call` and `:result` raises `Riffer::ArgumentError`.
|
|
229
|
+
|
|
230
|
+
```ruby
|
|
231
|
+
msg = Riffer::Messages::Assistant.new(parts: [
|
|
232
|
+
Riffer::Messages::Assistant::TextPart.new("Let me check. "),
|
|
233
|
+
Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, id: "srvtoolu_1", data: "{...}", format: "anthropic-messages-v1"),
|
|
234
|
+
Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :result, id: "srvtoolu_1", data: "{...}", format: "anthropic-messages-v1"),
|
|
235
|
+
Riffer::Messages::Assistant::ReasoningPart.new(type: :text, text: "", signature: "CAQS...", format: "anthropic-messages-v1"),
|
|
236
|
+
Riffer::Messages::Assistant::TextPart.new("The latest stable Ruby version is 4.0.9.")
|
|
237
|
+
])
|
|
238
|
+
|
|
239
|
+
msg.content # => "Let me check. The latest stable Ruby version is 4.0.9."
|
|
240
|
+
msg.reasoning # => [ReasoningPart]
|
|
241
|
+
msg.reasoning? # => true; server tool parts don't count as reasoning
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
- `content` joins the text parts with no separator.
|
|
245
|
+
- `Assistant.new(content, tool_calls:, reasoning:)` builds the parts in a fixed order: reasoning, then `content` as one text part (none when empty), then tool calls.
|
|
246
|
+
- Passing `parts:` together with `content`, `tool_calls:` or `reasoning:` raises `Riffer::ArgumentError`.
|
|
247
|
+
- `ServerToolPart#data` holds the provider's block as JSON, unchanged. It follows the same replay contract as reasoning: only the adapter that recognizes its `format` sends it back, and other adapters skip it. The same goes for a `TextPart` that carries `data`; other adapters send its `text`.
|
|
248
|
+
|
|
249
|
+
`to_h` writes the turn as a `parts` key, so it keeps the order, the server tool parts and the `data` of text parts. Each entry is the part's own hash plus a `part` tag (`:text`, `:reasoning`, `:tool_call` or `:server_tool`). It doesn't write `content`, `tool_calls` or `reasoning`; read those from the message:
|
|
250
|
+
|
|
251
|
+
```ruby
|
|
252
|
+
msg.to_h
|
|
253
|
+
# => {role: :assistant, parts: [
|
|
254
|
+
# {part: :text, text: "Let me check. "},
|
|
255
|
+
# {part: :server_tool, name: "web_search", kind: :call, data: "{...}", id: "srvtoolu_1", format: "anthropic-messages-v1"},
|
|
256
|
+
# ...
|
|
257
|
+
# ]}
|
|
258
|
+
|
|
259
|
+
{content: msg.content, tool_calls: msg.tool_calls.map(&:to_h), reasoning: msg.reasoning.map(&:to_h)}
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
`from_hash` reads this shape and the older one with `content`, `tool_calls` and `reasoning` keys, so stored sessions still load. Rebuilt from the older shape, the turn is in the fixed order, without server tool parts or the `data` of text parts. A hash with `parts` and a non-nil `content`, or a non-empty `tool_calls` or `reasoning`, raises `Riffer::ArgumentError`.
|
|
263
|
+
|
|
264
|
+
**Editing a turn.** Riffer sends the parts back as they are. When you change a turn's text (in an output guardrail, or with `Session#update`), keeping the rest of the turn consistent is up to you:
|
|
265
|
+
|
|
266
|
+
- Drop that turn's reasoning parts. They were signed over the old text, so Anthropic would reject them or drop them silently, and they may still hold the text you removed.
|
|
267
|
+
- Keep server tool parts and tool calls, so the model doesn't search again and tool results keep their call.
|
|
268
|
+
- Put the new text after the last server tool part and before the first tool call.
|
|
269
|
+
|
|
270
|
+
```ruby
|
|
271
|
+
def redact(message, text)
|
|
272
|
+
kept = message.parts.reject do |part|
|
|
273
|
+
part.is_a?(Riffer::Messages::Assistant::ReasoningPart) || part.is_a?(Riffer::Messages::Assistant::TextPart)
|
|
274
|
+
end
|
|
275
|
+
index = kept.index { |part| part.is_a?(Riffer::Messages::Assistant::ToolCall) } || kept.length
|
|
276
|
+
parts = kept.insert(index, Riffer::Messages::Assistant::TextPart.new(text))
|
|
277
|
+
|
|
278
|
+
Riffer::Messages::Assistant.new(
|
|
279
|
+
parts: parts,
|
|
280
|
+
id: message.id,
|
|
281
|
+
token_usage: message.token_usage,
|
|
282
|
+
finish_reason: message.finish_reason,
|
|
283
|
+
finish_reason_raw: message.finish_reason_raw
|
|
284
|
+
)
|
|
285
|
+
end
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`Assistant.new(text)` and `Session#update(id:, content:)` don't follow these rules. They rebuild the turn in the fixed order, which keeps the reasoning and drops server tool parts. Use `Session#update(id:, parts:)` to replace the parts as given.
|
|
289
|
+
|
|
195
290
|
### Tool
|
|
196
291
|
|
|
197
292
|
Tool messages contain the results of tool executions:
|
|
@@ -221,6 +316,19 @@ msg.error # => "API rate limit exceeded"
|
|
|
221
316
|
msg.error_type # => :execution_error
|
|
222
317
|
```
|
|
223
318
|
|
|
319
|
+
A tool result that [loaded deferred tools](TOOLS.md#loading-deferred-tools-experimental) records their names in `loaded_tools` (`[]` otherwise). `to_h` includes the key only when it isn't empty, and `from_hash` reads it back, so the loaded set travels with the history:
|
|
320
|
+
|
|
321
|
+
```ruby
|
|
322
|
+
msg = Riffer::Messages::Tool.new(
|
|
323
|
+
"",
|
|
324
|
+
tool_call_id: "call_456",
|
|
325
|
+
name: "connect_calendar",
|
|
326
|
+
loaded_tools: ["list_events", "create_event"]
|
|
327
|
+
)
|
|
328
|
+
msg.loaded_tools # => ["list_events", "create_event"]
|
|
329
|
+
msg.to_h # => {role: :tool, content: "", tool_call_id: "call_456", name: "connect_calendar", loaded_tools: ["list_events", "create_event"]}
|
|
330
|
+
```
|
|
331
|
+
|
|
224
332
|
## File Parts
|
|
225
333
|
|
|
226
334
|
`Riffer::Messages::User::FilePart` represents a file attachment (image or document) that can be included with user messages.
|
|
@@ -360,12 +468,14 @@ Without this step, the same model can receive different input depending on the p
|
|
|
360
468
|
|
|
361
469
|
### Merge rules
|
|
362
470
|
|
|
363
|
-
| Message type | Content | Auxiliary data
|
|
364
|
-
| ------------ | -------------------- |
|
|
365
|
-
| `System` | Joined with `"\n\n"` | —
|
|
366
|
-
| `User` | Joined with `"\n\n"` | `files` arrays concatenated
|
|
367
|
-
| `Assistant` | Joined with `"\n\n"` | `tool_calls` arrays concatenated | Yes |
|
|
368
|
-
| `Tool` | — | —
|
|
471
|
+
| Message type | Content | Auxiliary data | Merged? |
|
|
472
|
+
| ------------ | -------------------- | ------------------------------------------------ | ---------------------------------------- |
|
|
473
|
+
| `System` | Joined with `"\n\n"` | — | Yes |
|
|
474
|
+
| `User` | Joined with `"\n\n"` | `files` arrays concatenated | Yes |
|
|
475
|
+
| `Assistant` | Joined with `"\n\n"` | `tool_calls` and `reasoning` arrays concatenated | Yes |
|
|
476
|
+
| `Tool` | — | — | Never (each has a unique `tool_call_id`) |
|
|
477
|
+
|
|
478
|
+
When either assistant message has [parts](#parts) its fields can't rebuild, the merged message concatenates the two `parts` lists instead, with a `"\n\n"` text part between the texts.
|
|
369
479
|
|
|
370
480
|
### Example
|
|
371
481
|
|
|
@@ -434,7 +544,7 @@ class Riffer::Messages::Base
|
|
|
434
544
|
end
|
|
435
545
|
```
|
|
436
546
|
|
|
437
|
-
Subclasses implement `role` and optionally extend `to_h` with additional fields.
|
|
547
|
+
Subclasses implement `role` and optionally extend `to_h` with additional fields. `Assistant` writes `parts` in place of `content`.
|
|
438
548
|
|
|
439
549
|
## Editing history after the fact
|
|
440
550
|
|
data/docs/OVERVIEW.md
CHANGED
|
@@ -26,7 +26,7 @@ class WeatherTool < Riffer::Tool
|
|
|
26
26
|
description "Gets the weather for a city"
|
|
27
27
|
|
|
28
28
|
params do
|
|
29
|
-
required :city,
|
|
29
|
+
required :city, :string, description: "The city name"
|
|
30
30
|
end
|
|
31
31
|
|
|
32
32
|
def call(context:, city:)
|
|
@@ -39,17 +39,17 @@ See [Tools](TOOLS.md) for details.
|
|
|
39
39
|
|
|
40
40
|
### Structured Output
|
|
41
41
|
|
|
42
|
-
Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated. Schemas support nested objects (`
|
|
42
|
+
Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated. Schemas support nested objects (`:object`), typed arrays (`:array, of:`), arrays of arrays (`:array, of: [:integer]`), arrays of objects (`:array` with block), and either/or shapes (`:any_of`):
|
|
43
43
|
|
|
44
44
|
```ruby
|
|
45
45
|
class SentimentAgent < Riffer::Agent
|
|
46
46
|
model 'openai/gpt-5-mini'
|
|
47
47
|
structured_output do
|
|
48
|
-
required :sentiment,
|
|
49
|
-
required :score,
|
|
50
|
-
required :entities,
|
|
51
|
-
required :name,
|
|
52
|
-
required :type,
|
|
48
|
+
required :sentiment, :string
|
|
49
|
+
required :score, :number
|
|
50
|
+
required :entities, :array, description: "Named entities" do
|
|
51
|
+
required :name, :string
|
|
52
|
+
required :type, :string, enum: ["person", "place", "org"]
|
|
53
53
|
end
|
|
54
54
|
end
|
|
55
55
|
end
|
data/docs/SERIALIZATION.md
CHANGED
|
@@ -47,13 +47,15 @@ The session is used **as-is**: the rebuilt agent does not prepend anything to it
|
|
|
47
47
|
structured_output: { type: "object", … }, # JSON Schema, or null
|
|
48
48
|
structured_output_strategy: :native, # :native or :prompted ("native"/"prompted" over JSON)
|
|
49
49
|
reasoning: :low, # reasoning level, or null
|
|
50
|
-
tools: [ { name:, description:, parameters_schema:, timeout: }, … ]
|
|
50
|
+
tools: [ { name:, description:, parameters_schema:, timeout: }, … ],
|
|
51
|
+
deferred_tools: [ { name:, description:, parameters_schema:, timeout: }, … ], # [] when the agent has none
|
|
52
|
+
deferred_tools_strategy: :native # :native or :gateway ("native"/"gateway" over JSON)
|
|
51
53
|
}
|
|
52
54
|
```
|
|
53
55
|
|
|
54
56
|
### Resolved snapshot
|
|
55
57
|
|
|
56
|
-
`to_h` reads the agent's **resolved** state, not its raw configuration. By the time you call it, `Agent.new` has already evaluated any `Proc`-based `model`, `instructions`, or `
|
|
58
|
+
`to_h` reads the agent's **resolved** state, not its raw configuration. By the time you call it, `Agent.new` has already evaluated any `Proc`-based `model`, `instructions`, `uses_tools`, or `deferred_tools` against the agent's own context — so the hash carries plain strings and data, never Procs. The receiver's `context:` drives runtime behavior (tool dispatch); it does **not** re-evaluate baked-in fields.
|
|
57
59
|
|
|
58
60
|
### Structured output
|
|
59
61
|
|
|
@@ -61,6 +63,14 @@ Structured output crosses as **provider-neutral JSON Schema** (`Riffer::Params#t
|
|
|
61
63
|
|
|
62
64
|
`structured_output_strategy` carries the [strategy](AGENTS.md#structured-output-strategy-experimental) the agent was configured with, so a `:prompted` agent rebuilds as `:prompted`. A hash without the key decodes as `:native`.
|
|
63
65
|
|
|
66
|
+
### Deferred tools
|
|
67
|
+
|
|
68
|
+
`deferred_tools` carries the agent's [deferred tools](AGENTS.md#deferred_tools-experimental) as the same descriptors as `tools`, and `from_h` resolves them through the same `tool_resolver:`. A hash without the key, such as one saved by an earlier release, decodes as deferring nothing. An earlier release ignores the key, so it rebuilds an agent that has deferred tools without them; load agents with deferred tools only on a release that supports them.
|
|
69
|
+
|
|
70
|
+
`deferred_tools_strategy` carries the [strategy](AGENTS.md#deferred-tools-strategy-experimental) the agent was configured with, so a `:gateway` agent rebuilds as `:gateway`. A hash without the key decodes as `:native`.
|
|
71
|
+
|
|
72
|
+
Which deferred tools are loaded isn't part of the hash: riffer works it out from the `loaded_tools` on the conversation's [tool messages](MESSAGES.md#tool). Pass the restored history as `session:` and the loaded tools stay loaded. Riffer matches loads by tool name, so this works with body-less shells too.
|
|
73
|
+
|
|
64
74
|
## Reconstructing tools
|
|
65
75
|
|
|
66
76
|
Tools cross as `{name, description, parameters_schema, timeout}` descriptors — never code. How a descriptor becomes a runnable tool is controlled by the `tool_resolver:` you pass to `from_h`. The two common shapes:
|
data/docs/SKILLS.md
CHANGED
data/docs/STABILITY.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Stability
|
|
2
|
+
|
|
3
|
+
This page covers which parts of Riffer you can depend on, how changes to them are announced, and how breaking releases work. Riffer is not at 1.0 yet; the [roadmap](https://github.com/janeapp/riffer/issues/528) tracks the path there.
|
|
4
|
+
|
|
5
|
+
## Public API
|
|
6
|
+
|
|
7
|
+
The public API is everything documented in these guides. You can build on it, and it changes only in the ways this page describes.
|
|
8
|
+
|
|
9
|
+
Everything else is internal, even when Ruby lets you reach it. That includes classes, methods and constants that appear in the [API reference](https://riffer.ai/api/) but not in a guide. Internal code can change in any release without notice. At 1.0, every public constant will be documented and everything else marked private.
|
|
10
|
+
|
|
11
|
+
## Experimental features
|
|
12
|
+
|
|
13
|
+
Experimental features are labelled _experimental_ in the guides, like the [prompted structured output strategy](AGENTS.md#structured-output-strategy-experimental). They can change in any minor release, and the [CHANGELOG](https://github.com/janeapp/riffer/blob/main/CHANGELOG.md) notes each change.
|
|
14
|
+
|
|
15
|
+
## Deprecations
|
|
16
|
+
|
|
17
|
+
A breaking change to the public API lands first as a new API or an [opt-in flag](CONFIGURATION.md#future-flags), and the old way prints a deprecation warning. The warning says the old way will be removed in a future version, and it appears for at least one release before that happens.
|
|
18
|
+
|
|
19
|
+
## Breaking releases
|
|
20
|
+
|
|
21
|
+
Before 1.0, any minor release can include breaking changes, but never without notice: an earlier release deprecates what's changing first, so you'll see the warnings before anything breaks. Each breaking release comes with an upgrade guide in [UPGRADING.md](https://github.com/janeapp/riffer/blob/main/UPGRADING.md), and the CHANGELOG lists its changes under **⚠ BREAKING CHANGES**.
|
|
22
|
+
|
|
23
|
+
After 1.0, breaking changes ship only in major versions.
|
|
24
|
+
|
|
25
|
+
## Saved formats
|
|
26
|
+
|
|
27
|
+
Saved formats are the data Riffer produces for you to store and load later, such as [serialized agents](SERIALIZATION.md) and [messages persisted with `to_h`](MESSAGES.md#parts).
|
|
28
|
+
|
|
29
|
+
- Riffer can read a new format at least one release before it starts writing it, so a deploy that runs a release alongside the one before it keeps working.
|
|
30
|
+
- Anything saved by a 1.x release loads in every later 1.x release.
|
|
31
|
+
|
|
32
|
+
See [Serialization → Versioning](SERIALIZATION.md#versioning) for how agent data records its format version.
|
data/docs/STREAM_EVENTS.md
CHANGED
|
@@ -55,6 +55,8 @@ event.to_h # => {role: :assistant, content: "Hello, how can I help you?"}
|
|
|
55
55
|
|
|
56
56
|
Fires once per model response, after its last `TextDelta`, and contains the response's full text: every text block the provider returned, concatenated in order, so it always equals the joined `TextDelta` contents. A response that carries no text (for example, only tool calls) emits no `TextDone`.
|
|
57
57
|
|
|
58
|
+
The agent loop builds the message's [text parts](MESSAGES.md#parts) from the `TextDelta` events: the deltas between two other parts (reasoning, a tool call, a server tool block) form one text part. An adapter that sends no deltas gets one text part, from `TextDone`, at the end of the turn.
|
|
59
|
+
|
|
58
60
|
### ToolCallDelta
|
|
59
61
|
|
|
60
62
|
Emitted when tool call arguments are being streamed:
|
|
@@ -156,6 +158,20 @@ event.to_h # => {role: :assistant, query: "Ruby language", sources: [...]}
|
|
|
156
158
|
|
|
157
159
|
Contains the search query and an array of source hashes with `title` and `url` keys.
|
|
158
160
|
|
|
161
|
+
### ServerToolDone
|
|
162
|
+
|
|
163
|
+
Emitted when a block from a tool the provider ran itself (such as web search) is complete. It carries the block for replay; use `WebSearchStatus` and `WebSearchDone` to show progress.
|
|
164
|
+
|
|
165
|
+
```ruby
|
|
166
|
+
part = Riffer::Messages::Assistant::ServerToolPart.new(name: "web_search", kind: :call, data: "{...}", format: "anthropic-messages-v1")
|
|
167
|
+
event = Riffer::StreamEvents::ServerToolDone.new(part)
|
|
168
|
+
event.role # => :assistant
|
|
169
|
+
event.part # => the ServerToolPart
|
|
170
|
+
event.to_h # => {role: :assistant, part: {name: "web_search", kind: :call, data: "{...}", format: "anthropic-messages-v1"}}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The agent loop adds `part` to the assistant message's [parts](MESSAGES.md#parts). Only Anthropic emits it today.
|
|
174
|
+
|
|
159
175
|
### GuardrailTripwire
|
|
160
176
|
|
|
161
177
|
Emitted when a guardrail blocks execution during streaming:
|
data/docs/TESTING.md
CHANGED
|
@@ -16,7 +16,7 @@ require 'riffer/testing/rspec'
|
|
|
16
16
|
require 'riffer/testing/minitest'
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
Either one adds `stub_agent` and `
|
|
19
|
+
Either one adds `stub_agent`, `stub_tool` and `allow_deprecations` to every example and cleans up after each one. Neither RSpec nor minitest is a riffer dependency; the adapter files are only loaded when you require them yourself.
|
|
20
20
|
|
|
21
21
|
## Stubbing a tool
|
|
22
22
|
|
|
@@ -110,6 +110,27 @@ end
|
|
|
110
110
|
|
|
111
111
|
Tracking lives on `Riffer::Testing` itself, so `Riffer::Testing.stub_tool(...)` outside an example and `stub_tool(...)` inside one share one list. Tracking is not synchronized — stub from a single-threaded test, before concurrent lookups begin.
|
|
112
112
|
|
|
113
|
+
## Deprecations
|
|
114
|
+
|
|
115
|
+
Make your suite fail when it hits a deprecated riffer call, so you find each one before an upgrade removes it:
|
|
116
|
+
|
|
117
|
+
```ruby
|
|
118
|
+
# test/test_helper.rb
|
|
119
|
+
Riffer.config.deprecations = :raise
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Every deprecated call then raises `Riffer::DeprecationError`, naming the line that made it. A test that uses a deprecated call on purpose wraps it in `allow_deprecations`:
|
|
123
|
+
|
|
124
|
+
```ruby
|
|
125
|
+
it 'still reads legacy pricing' do
|
|
126
|
+
allow_deprecations { Riffer.config.pricing.set('openai/gpt-5', input: 1.0, output: 2.0) }
|
|
127
|
+
|
|
128
|
+
# ...
|
|
129
|
+
end
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`allow_deprecations` silences deprecations until the block returns or raises, and returns the block's value. It applies to the current thread or fiber and to threads and fibers started inside the block; other threads keep reporting. It is also available as `Riffer::Testing.allow_deprecations` outside an example. See [Configuration — Deprecations](CONFIGURATION.md#deprecations) for the other modes.
|
|
133
|
+
|
|
113
134
|
## When a stub leaks
|
|
114
135
|
|
|
115
136
|
Stubbing an identifier that is already taken raises `Riffer::DuplicateIdentifierError`:
|
data/docs/TOOLS.md
CHANGED
|
@@ -15,8 +15,8 @@ class WeatherTool < Riffer::Tool
|
|
|
15
15
|
description "Gets the current weather for a city"
|
|
16
16
|
|
|
17
17
|
params do
|
|
18
|
-
required :city,
|
|
19
|
-
optional :units,
|
|
18
|
+
required :city, :string, description: "The city name"
|
|
19
|
+
optional :units, :string, default: "celsius", enum: ["celsius", "fahrenheit"]
|
|
20
20
|
end
|
|
21
21
|
|
|
22
22
|
def call(context:, city:, units: nil)
|
|
@@ -58,10 +58,10 @@ Defines the tool's parameters using a DSL:
|
|
|
58
58
|
```ruby
|
|
59
59
|
class CreateOrderTool < Riffer::Tool
|
|
60
60
|
params do
|
|
61
|
-
required :product_id,
|
|
62
|
-
required :quantity,
|
|
63
|
-
optional :notes,
|
|
64
|
-
optional :priority,
|
|
61
|
+
required :product_id, :integer, description: "The product ID"
|
|
62
|
+
required :quantity, :integer, description: "Number of items"
|
|
63
|
+
optional :notes, :string, description: "Order notes"
|
|
64
|
+
optional :priority, :string, default: "normal", enum: ["low", "normal", "high"]
|
|
65
65
|
end
|
|
66
66
|
end
|
|
67
67
|
```
|
|
@@ -74,16 +74,16 @@ Defines a required parameter:
|
|
|
74
74
|
|
|
75
75
|
```ruby
|
|
76
76
|
params do
|
|
77
|
-
required :name,
|
|
78
|
-
required :age,
|
|
77
|
+
required :name, :string, description: "The user's name"
|
|
78
|
+
required :age, :integer, description: "The user's age"
|
|
79
79
|
end
|
|
80
80
|
```
|
|
81
81
|
|
|
82
82
|
Options:
|
|
83
83
|
|
|
84
84
|
- `description` - Human-readable description for the LLM
|
|
85
|
-
- `enum` - Array of allowed values (for the innermost items of an `
|
|
86
|
-
- `format` - String format such as `"date"` or `"email"` (for the innermost `
|
|
85
|
+
- `enum` - Array of allowed values (for the innermost items of an `:array` with `of:`)
|
|
86
|
+
- `format` - String format such as `"date"` or `"email"` (for the innermost `:string` items of an `:array`; see [Formats](AGENTS.md#formats))
|
|
87
87
|
|
|
88
88
|
### optional
|
|
89
89
|
|
|
@@ -91,8 +91,8 @@ Defines an optional parameter:
|
|
|
91
91
|
|
|
92
92
|
```ruby
|
|
93
93
|
params do
|
|
94
|
-
optional :limit,
|
|
95
|
-
optional :format,
|
|
94
|
+
optional :limit, :integer, default: 10, description: "Max results"
|
|
95
|
+
optional :format, :string, enum: ["json", "xml"], description: "Output format"
|
|
96
96
|
end
|
|
97
97
|
```
|
|
98
98
|
|
|
@@ -100,44 +100,43 @@ Options:
|
|
|
100
100
|
|
|
101
101
|
- `description` - Human-readable description
|
|
102
102
|
- `default` - Default value when not provided
|
|
103
|
-
- `enum` - Array of allowed values (for the innermost items of an `
|
|
104
|
-
- `format` - String format such as `"date"` or `"email"` (for the innermost `
|
|
103
|
+
- `enum` - Array of allowed values (for the innermost items of an `:array` with `of:`)
|
|
104
|
+
- `format` - String format such as `"date"` or `"email"` (for the innermost `:string` items of an `:array`; see [Formats](AGENTS.md#formats))
|
|
105
105
|
|
|
106
106
|
### Supported Types
|
|
107
107
|
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `Riffer::Params::Boolean`
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `Riffer::Params::AnyOf` | `anyOf` of objects or primitives |
|
|
108
|
+
| Type | JSON Schema type | Validated value | Deprecated class |
|
|
109
|
+
| ---------- | -------------------------------- | --------------------------------- | ---------------------------------------------------- |
|
|
110
|
+
| `:string` | `string` | `String` | `String` |
|
|
111
|
+
| `:integer` | `integer` | `Integer` | `Integer` |
|
|
112
|
+
| `:number` | `number` | `Float` | `Float` |
|
|
113
|
+
| `:boolean` | `boolean` | `true` or `false` | `Riffer::Params::Boolean`, `TrueClass`, `FalseClass` |
|
|
114
|
+
| `:array` | `array` | `Array` | `Array` |
|
|
115
|
+
| `:object` | `object` | `Hash` with symbol keys | `Hash` |
|
|
116
|
+
| `:any_of` | `anyOf` of objects or primitives | The value of the matching variant | `Riffer::Params::AnyOf` |
|
|
118
117
|
|
|
119
|
-
`
|
|
118
|
+
`required`, `optional`, `of:` and `variant` still accept the deprecated Ruby classes, and each line that uses one reports a [deprecation](CONFIGURATION.md#deprecations). They won't be removed before 1 December 2026.
|
|
120
119
|
|
|
121
|
-
A `
|
|
120
|
+
A `:number` param accepts a whole number too, since JSON Schema's `number` covers integers — a model returning `120` for a `:number` is valid, and the validated value is coerced to `120.0`. `:integer` stays strict: `1.0` is rejected, matching JSON Schema's `integer`.
|
|
122
121
|
|
|
123
122
|
### Nested Parameters
|
|
124
123
|
|
|
125
|
-
Tool params support the same nested DSL as structured output — nested objects (`
|
|
124
|
+
Tool params support the same nested DSL as structured output — nested objects (`:object` with block), typed arrays (`:array, of:`), arrays of arrays (`:array, of: [:integer]`), arrays of objects (`:array` with block), and either/or shapes (`:any_of` with `variant`s). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
|
|
126
125
|
|
|
127
126
|
```ruby
|
|
128
127
|
class CreateOrderTool < Riffer::Tool
|
|
129
128
|
description "Creates an order"
|
|
130
129
|
|
|
131
130
|
params do
|
|
132
|
-
required :items,
|
|
133
|
-
required :product_id,
|
|
134
|
-
required :quantity,
|
|
135
|
-
optional :notes,
|
|
131
|
+
required :items, :array, description: "Line items" do
|
|
132
|
+
required :product_id, :integer
|
|
133
|
+
required :quantity, :integer
|
|
134
|
+
optional :notes, :string
|
|
136
135
|
end
|
|
137
|
-
required :shipping,
|
|
138
|
-
required :street,
|
|
139
|
-
required :city,
|
|
140
|
-
optional :zip,
|
|
136
|
+
required :shipping, :object, description: "Shipping address" do
|
|
137
|
+
required :street, :string
|
|
138
|
+
required :city, :string
|
|
139
|
+
optional :zip, :string
|
|
141
140
|
end
|
|
142
141
|
end
|
|
143
142
|
|
|
@@ -222,10 +221,13 @@ end
|
|
|
222
221
|
MyAgent.new(context: {user_id: 123}).generate("Show my orders")
|
|
223
222
|
```
|
|
224
223
|
|
|
225
|
-
|
|
224
|
+
Three keys are framework-managed and exposed as typed accessors:
|
|
226
225
|
|
|
227
226
|
- `context.skills` — the resolved `Riffer::Skills::Context` when the agent has skills configured, otherwise `nil`.
|
|
228
227
|
- `context.token_usage` — the cumulative `Riffer::Providers::TokenUsage` across every run on the agent, or `nil` before the first response.
|
|
228
|
+
- `context.deferred_tools` — the agent's [deferred tools](#loading-deferred-tools-experimental), loaded or not (`[]` when it has none).
|
|
229
|
+
|
|
230
|
+
Passing your own `:deferred_tools` key in `context:` is deprecated: it still works, and `context[:deferred_tools]` returns your value, but it prints a [deprecation warning](STABILITY.md#deprecations), and a future breaking release reserves the key. Rename it.
|
|
229
231
|
|
|
230
232
|
## Response Objects
|
|
231
233
|
|
|
@@ -295,7 +297,7 @@ error("Service unavailable", type: :service_error)
|
|
|
295
297
|
error("Rate limit exceeded", type: :rate_limit)
|
|
296
298
|
```
|
|
297
299
|
|
|
298
|
-
If no type is specified, it defaults to `:execution_error`. Riffer reserves `:unhandled_error` for unrescued exceptions — don't set
|
|
300
|
+
If no type is specified, it defaults to `:execution_error`. Riffer reserves `:unhandled_error` for unrescued exceptions, and `:invalid_tool_load` and `:tool_not_loaded` for [deferred tools](#loading-deferred-tools-experimental) — don't set them yourself.
|
|
299
301
|
|
|
300
302
|
### Using Riffer::Tools::Response Directly
|
|
301
303
|
|
|
@@ -305,6 +307,7 @@ The shorthand methods delegate to `Riffer::Tools::Response`. You can also use th
|
|
|
305
307
|
Riffer::Tools::Response.text("Hello")
|
|
306
308
|
Riffer::Tools::Response.json({data: [1, 2, 3]})
|
|
307
309
|
Riffer::Tools::Response.error("Failed", type: :custom_error)
|
|
310
|
+
Riffer::Tools::Response.load_tools([ListEvents])
|
|
308
311
|
```
|
|
309
312
|
|
|
310
313
|
### Response Methods
|
|
@@ -327,3 +330,56 @@ error_response.exception # => nil
|
|
|
327
330
|
```
|
|
328
331
|
|
|
329
332
|
`exception` holds the rescued exception on the `:unhandled_error` responses Riffer builds. It never appears in serialized output, so it is not visible to the LLM.
|
|
333
|
+
|
|
334
|
+
## Loading deferred tools (experimental)
|
|
335
|
+
|
|
336
|
+
An agent can hold tools back with [`deferred_tools`](AGENTS.md#deferred_tools-experimental). Any of its own tools loads them by returning `load_tools(tools)`, and `context.deferred_tools` lists the tools it can choose from. A search tool, a browse tool or a "connect your calendar" tool is an ordinary tool:
|
|
337
|
+
|
|
338
|
+
```ruby
|
|
339
|
+
class FindTools < Riffer::Tool
|
|
340
|
+
description "Find more tools for a task. Describe what you need to do in a few words."
|
|
341
|
+
params { required :query, :string }
|
|
342
|
+
|
|
343
|
+
def call(context:, query:)
|
|
344
|
+
words = query.downcase.split
|
|
345
|
+
matches = context.deferred_tools.select { |tool| words.any? { |w| tool.description.downcase.include?(w) } }
|
|
346
|
+
load_tools(matches.first(5))
|
|
347
|
+
end
|
|
348
|
+
end
|
|
349
|
+
|
|
350
|
+
class ConnectCalendar < Riffer::Tool
|
|
351
|
+
description "Connect the user's calendar. Calendar tools become available afterwards."
|
|
352
|
+
|
|
353
|
+
def call(context:)
|
|
354
|
+
Calendars.connect!(context[:user])
|
|
355
|
+
load_tools([ListEvents, CreateEvent])
|
|
356
|
+
end
|
|
357
|
+
end
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
How a load reaches the model depends on the agent's [strategy](AGENTS.md#deferred-tools-strategy-experimental). By default [Anthropic](providers/ANTHROPIC.md#deferred-tools), [OpenAI](providers/OPENAI.md#deferred-tools-experimental) and [Azure OpenAI](providers/AZURE_OPENAI.md#deferred-tools-experimental) load deferred tools natively; with `strategy: :gateway`, any provider goes through the [gateway](#the-gateway-strategy).
|
|
361
|
+
|
|
362
|
+
A load takes effect from the model's next turn. The model made every call in a turn before it saw any of that turn's results, so a call to a tool loaded in the same turn is refused like any other unloaded call; the model calls it again once it has seen the load.
|
|
363
|
+
|
|
364
|
+
- A load can't carry text as well, because Anthropic rejects a tool result that mixes loaded tools with text. `load_tools` takes no text, and the response's `content` is `""`.
|
|
365
|
+
- `load_tools([])` is a successful load of nothing.
|
|
366
|
+
- Loading a tool that isn't one of the agent's deferred tools, including one in `uses_tools`, returns an `:invalid_tool_load` error to the model instead, and nothing in that load is loaded.
|
|
367
|
+
- Loading a tool that's already loaded succeeds and changes nothing: the tool is loaded once, and stays loaded for the rest of the conversation. Tools can't be unloaded.
|
|
368
|
+
- A call to a deferred tool that hasn't been loaded isn't run. The model gets an error result of type `:tool_not_loaded` (`Tool 'list_events' has not been loaded`). Riffer checks this itself, before the [tool runtime](TOOL_ADVANCED.md#tool-runtime) sees the call, so a custom runtime can't run an unloaded tool by mistake. That includes a call forced by a provider's own `tool_choice` passed through `model_options`, and an unloaded call already in a restored history.
|
|
369
|
+
|
|
370
|
+
`response.loaded_tools` returns the tools a response loads, and is `[]` on every other response. Riffer records the loaded tools' names on the [tool message](MESSAGES.md#tool) as `loaded_tools`.
|
|
371
|
+
|
|
372
|
+
Loading puts the loaded tools' full schemas into the conversation, and every load is an extra round trip to the model, so load a handful of tools at a time rather than dozens.
|
|
373
|
+
|
|
374
|
+
### The gateway strategy
|
|
375
|
+
|
|
376
|
+
With `deferred_tools [...], strategy: :gateway`, riffer doesn't use the provider's native loading, so it works on every provider, custom ones included. Adding a loaded tool to the request's tools partway through a conversation would break the prompt cache on every load, so riffer keeps the tool list fixed and sends one extra tool instead, `Riffer::Providers::DeferredToolGateway::Tool`, the gateway, named `riffer_gateway`:
|
|
377
|
+
|
|
378
|
+
- Every request with deferred tools carries the gateway after the agent's other tools, before any load and after it. Its name, description and schema never change, and the deferred tools themselves are never in the tool list, so the tool list is the same for the whole conversation.
|
|
379
|
+
- The gateway takes two required string parameters and nothing else: `name`, the loaded tool's name, and `arguments`, the loaded tool's arguments as a JSON-encoded object (`"{\"query\":\"red shoes\",\"limit\":5}"`). Strings rather than a free-form object keep the schema valid for providers that send tools in strict mode, such as OpenRouter. Riffer still validates the arguments against the real tool's `params` when the tool runs.
|
|
380
|
+
- A tool result that loads tools is sent to the model with an instruction to call them through the gateway, by its wire name, appended to its content, followed by the loaded tools as one JSON array of `name`, `description` and `parameters`. The text is the same every time it is sent, so the earlier conversation doesn't change and the cache holds. Only the request carries it: the tool message in the session keeps its own content. A load that names a tool the agent no longer defers, for example in a restored history, describes nothing for that tool.
|
|
381
|
+
- The model's call to the gateway comes back as a call to the real tool, named by `name` with `arguments` as its arguments, before the provider returns. The session, [`on_message` callbacks](AGENT_LIFECYCLE.md#on_message), the tool runtime, the `:tool_not_loaded` check and [traces](TRACING.md) all see the real tool. A streamed gateway call yields only its `ToolCallDone`, under the real tool's name: its `ToolCallDelta` events carry pieces of the gateway's own arguments, so riffer drops them.
|
|
382
|
+
- On later requests, a call to a deferred tool in the history is sent back as a gateway call, and its result under the gateway's name, keeping its `tool_call_id`, so the provider never sees a call to a tool missing from the tool list.
|
|
383
|
+
- A gateway call riffer can't read, because its arguments aren't a JSON object with a string `name` and a string `arguments` or its `name` isn't one of the agent's deferred tools, stays a call to the gateway, which no agent has as a tool, so the model gets an `:unknown_tool` error result and can try again.
|
|
384
|
+
|
|
385
|
+
An agent with the gateway strategy can't have a tool of its own with the gateway's name, in `uses_tools` or `deferred_tools`: building it raises `Riffer::ArgumentError`. Like the rest of deferred tools, the gateway is experimental, and its name, description and the text it adds to a load can change in any minor release.
|
data/docs/TOOL_ADVANCED.md
CHANGED
|
@@ -104,6 +104,13 @@ A tool never raises into the agent loop — every `StandardError` raised during
|
|
|
104
104
|
| `Riffer::ToolExecutionError` | `:execution_error` | the exception message |
|
|
105
105
|
| Any other `StandardError` | `:unhandled_error` | `Error executing tool: <ExceptionClass>: <message>` |
|
|
106
106
|
|
|
107
|
+
Riffer also returns two errors of its own for [deferred tools](TOOLS.md#loading-deferred-tools-experimental). The first replaces the loading tool's result; the second is returned without running the call:
|
|
108
|
+
|
|
109
|
+
| Failure | Error type | Response content |
|
|
110
|
+
| ------------------------------------------- | -------------------- | ------------------------------------------------------------------------ |
|
|
111
|
+
| A tool loads a tool that isn't deferred | `:invalid_tool_load` | `Cannot load <names>: only this agent's deferred tools can be loaded` |
|
|
112
|
+
| A call to a deferred tool not yet loaded | `:tool_not_loaded` | `Tool '<name>' has not been loaded` |
|
|
113
|
+
|
|
107
114
|
An `:unhandled_error` response also carries the rescued exception on `response.exception` — never serialized, so it stays out of the message history — and its `execute_tool` span records the exception with an `ERROR` status (see [Tracing](TRACING.md)).
|
|
108
115
|
|
|
109
116
|
`NotImplementedError` is not rescued: an unimplemented `#call` raises out of the run.
|