riffer 0.56.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.
Files changed (88) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +19 -0
  4. data/README.md +1 -1
  5. data/docs/AGENTS.md +105 -50
  6. data/docs/AGENT_LIFECYCLE.md +1 -1
  7. data/docs/CONFIGURATION.md +7 -3
  8. data/docs/EVALS.md +2 -0
  9. data/docs/MCP.md +36 -0
  10. data/docs/MESSAGES.md +13 -0
  11. data/docs/OVERVIEW.md +7 -7
  12. data/docs/SERIALIZATION.md +12 -2
  13. data/docs/SKILLS.md +1 -1
  14. data/docs/STABILITY.md +1 -1
  15. data/docs/TOOLS.md +93 -37
  16. data/docs/TOOL_ADVANCED.md +7 -0
  17. data/docs/providers/AMAZON_BEDROCK.md +6 -2
  18. data/docs/providers/ANTHROPIC.md +35 -2
  19. data/docs/providers/AZURE_OPENAI.md +9 -3
  20. data/docs/providers/CUSTOM_PROVIDERS.md +19 -0
  21. data/docs/providers/GEMINI.md +8 -4
  22. data/docs/providers/GOOGLE_CLOUD.md +9 -4
  23. data/docs/providers/MOCK_PROVIDER.md +2 -0
  24. data/docs/providers/OPENAI.md +25 -3
  25. data/docs/providers/OPENROUTER.md +11 -3
  26. data/docs/providers/PROVIDERS.md +1 -1
  27. data/docs-site/index.html.erb +1 -1
  28. data/lib/riffer/agent/config.rb +21 -0
  29. data/lib/riffer/agent/context.rb +36 -18
  30. data/lib/riffer/agent/run.rb +54 -8
  31. data/lib/riffer/agent/serializer.rb +5 -0
  32. data/lib/riffer/agent/session.rb +1 -0
  33. data/lib/riffer/agent.rb +43 -0
  34. data/lib/riffer/config/mcp.rb +17 -0
  35. data/lib/riffer/config/pricing.rb +2 -2
  36. data/lib/riffer/config.rb +12 -1
  37. data/lib/riffer/evals/evaluator.rb +8 -1
  38. data/lib/riffer/evals/evaluator_runner.rb +1 -0
  39. data/lib/riffer/evals/judge.rb +2 -2
  40. data/lib/riffer/evals.rb +2 -0
  41. data/lib/riffer/mcp/search_tool.rb +1 -1
  42. data/lib/riffer/mcp.rb +7 -0
  43. data/lib/riffer/messages/tool.rb +6 -2
  44. data/lib/riffer/params/any_of.rb +5 -8
  45. data/lib/riffer/params/boolean.rb +1 -1
  46. data/lib/riffer/params/param.rb +96 -67
  47. data/lib/riffer/params.rb +50 -71
  48. data/lib/riffer/providers/anthropic_compatible/messages_api/stream.rb +3 -10
  49. data/lib/riffer/providers/anthropic_compatible/messages_api.rb +88 -12
  50. data/lib/riffer/providers/base.rb +43 -7
  51. data/lib/riffer/providers/deferred_tool_gateway/sink.rb +54 -0
  52. data/lib/riffer/providers/deferred_tool_gateway/tool.rb +17 -0
  53. data/lib/riffer/providers/deferred_tool_gateway.rb +150 -0
  54. data/lib/riffer/providers/gemini.rb +5 -5
  55. data/lib/riffer/providers/mock.rb +6 -0
  56. data/lib/riffer/providers/open_ai.rb +38 -10
  57. data/lib/riffer/skills/activate_tool.rb +1 -1
  58. data/lib/riffer/tool.rb +92 -2
  59. data/lib/riffer/tools/response.rb +11 -2
  60. data/lib/riffer/version.rb +1 -1
  61. data/sig/generated/riffer/agent/config.rbs +13 -1
  62. data/sig/generated/riffer/agent/context.rbs +16 -0
  63. data/sig/generated/riffer/agent/run.rbs +14 -2
  64. data/sig/generated/riffer/agent.rbs +13 -0
  65. data/sig/generated/riffer/config/mcp.rbs +7 -0
  66. data/sig/generated/riffer/config.rbs +5 -1
  67. data/sig/generated/riffer/evals/evaluator.rbs +4 -0
  68. data/sig/generated/riffer/evals.rbs +1 -0
  69. data/sig/generated/riffer/mcp.rbs +1 -0
  70. data/sig/generated/riffer/messages/tool.rbs +4 -2
  71. data/sig/generated/riffer/params/any_of.rbs +4 -4
  72. data/sig/generated/riffer/params/boolean.rbs +1 -1
  73. data/sig/generated/riffer/params/param.rbs +28 -14
  74. data/sig/generated/riffer/params.rbs +20 -20
  75. data/sig/generated/riffer/providers/anthropic_compatible/messages_api/stream.rbs +2 -5
  76. data/sig/generated/riffer/providers/anthropic_compatible/messages_api.rbs +34 -2
  77. data/sig/generated/riffer/providers/base.rbs +13 -0
  78. data/sig/generated/riffer/providers/deferred_tool_gateway/sink.rbs +23 -0
  79. data/sig/generated/riffer/providers/deferred_tool_gateway/tool.rbs +4 -0
  80. data/sig/generated/riffer/providers/deferred_tool_gateway.rbs +58 -0
  81. data/sig/generated/riffer/providers/mock.rbs +4 -0
  82. data/sig/generated/riffer/providers/open_ai.rbs +16 -4
  83. data/sig/generated/riffer/tool.rbs +48 -2
  84. data/sig/generated/riffer/tools/response.rbs +9 -2
  85. data/sig/manual/riffer/providers/deferred_tool_gateway.rbs +5 -0
  86. metadata +8 -3
  87. data/lib/riffer/tools/toolable.rb +0 -113
  88. data/sig/generated/riffer/tools/toolable.rbs +0 -66
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, String, description: "The city name"
19
- optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
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, 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"]
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, String, description: "The user's name"
78
- required :age, Integer, description: "The user's 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 `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))
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, Integer, default: 10, description: "Max results"
95
- optional :format, String, enum: ["json", "xml"], description: "Output 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 `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))
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
- | Ruby Type | JSON Schema Type |
109
- | -------------------------- | -------------------------------- |
110
- | `String` | `string` |
111
- | `Integer` | `integer` |
112
- | `Float` | `number` |
113
- | `Riffer::Params::Boolean` | `boolean` |
114
- | `TrueClass` / `FalseClass` | `boolean` |
115
- | `Array` | `array` |
116
- | `Hash` | `object` |
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
- `Riffer::Params::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
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 `Float` param accepts a whole number too, since JSON Schema's `number` covers integers — a model returning `120` for a `Float` is valid, and the validated value is coerced to `120.0`. `Integer` stays strict: `1.0` is rejected, matching JSON Schema's `integer`.
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 (`Hash` with block), typed arrays (`Array, of:`), arrays of arrays (`Array, of: [Integer]`), arrays of objects (`Array` with block), and either/or shapes (`Riffer::Params::AnyOf` with `variant`s). See the [structured output section in Agents](AGENTS.md#nested-objects) for full syntax.
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, Array, description: "Line items" do
133
- required :product_id, Integer
134
- required :quantity, Integer
135
- optional :notes, String
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, Hash, description: "Shipping address" do
138
- required :street, String
139
- required :city, String
140
- optional :zip, String
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
- Two keys are framework-managed and exposed as typed accessors:
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 it yourself.
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.
@@ -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.
@@ -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, String, description: "The S3 bucket name"
154
- optional :prefix, String, description: "Object prefix filter"
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`:
@@ -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, String, description: "The city name"
143
- optional :unit, String, description: "Temperature unit (celsius or fahrenheit)"
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")
@@ -226,6 +226,39 @@ Anthropic emits sources with `title` and `url` on the `WebSearchDone` event.
226
226
 
227
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
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
+
229
262
  ## Message Format
230
263
 
231
264
  The provider converts Riffer messages to Anthropic format:
@@ -133,9 +133,9 @@ class CalculatorTool < Riffer::Tool
133
133
  description "Performs basic math operations"
134
134
 
135
135
  params do
136
- required :operation, String, enum: ["add", "subtract", "multiply", "divide"]
137
- required :a, Float, description: "First number"
138
- required :b, Float, description: "Second number"
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`:
@@ -132,8 +132,8 @@ end
132
132
 
133
133
  ```ruby
134
134
  params = Riffer::Params.new
135
- params.required(:sentiment, String)
136
- params.required(:score, Float)
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. A `Hash` param needs a block and an `Array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
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, String
157
+ required :city, :string
158
158
  end
159
159
  def call(context:, city:)
160
160
  text("Sunny in #{city}")
@@ -170,6 +170,10 @@ 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.
@@ -224,8 +224,8 @@ end
224
224
 
225
225
  ```ruby
226
226
  params = Riffer::Params.new
227
- params.required(:sentiment, String)
228
- params.required(:score, Float)
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. A `Hash` param needs a block and an `Array` param a block or `of:` (see [Structured Output Limitations](../AGENTS.md#limitations)).
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, String
247
+ required :city, :string
248
248
  end
249
249
  def call(context:, city:)
250
250
  text("Sunny in #{city}")
@@ -260,6 +260,10 @@ 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.
@@ -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`.
@@ -98,6 +98,8 @@ expect(provider.calls.last[:messages].last[:content]).to eq("Hi")
98
98
 
99
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
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
+
101
103
  ## Clearing State
102
104
 
103
105
  Reset stubbed responses:
@@ -162,9 +162,9 @@ class CalculatorTool < Riffer::Tool
162
162
  description "Performs basic math operations"
163
163
 
164
164
  params do
165
- required :operation, String, enum: ["add", "subtract", "multiply", "divide"]
166
- required :a, Float, description: "First number"
167
- required :b, Float, description: "Second number"
165
+ required :operation, :string, enum: ["add", "subtract", "multiply", "divide"]
166
+ required :a, :number, description: "First number"
167
+ required :b, :number, description: "Second number"
168
168
  end
169
169
 
170
170
  def call(context:, operation:, a:, b:)
@@ -184,6 +184,28 @@ class MathAgent < Riffer::Agent
184
184
  end
185
185
  ```
186
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
+
187
209
  ## Web Search
188
210
 
189
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, String, enum: ['add', 'subtract', 'multiply', 'divide']
155
- required :a, Float
156
- required :b, Float
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:
@@ -149,7 +149,7 @@ Providers convert tools to their native format:
149
149
  class WeatherTool < Riffer::Tool
150
150
  description "Gets weather"
151
151
  params do
152
- required :city, String
152
+ required :city, :string
153
153
  end
154
154
  def call(context:, city:)
155
155
  text("Sunny in #{city}")
@@ -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, <span class="c">String</span>, description: <span class="s">'City name'</span>
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:)
@@ -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