Skip to content

Commit cbf93ec

Browse files
committed
docs(offloader): update retrieval tool docs to reflect Python parity
The Python SDK now supports the same targeted retrieval parameters (pattern, line_range, context_lines) as TypeScript. Remove the SDK-specific tabs for the feature description and show unified examples.
1 parent f81be71 commit cbf93ec

2 files changed

Lines changed: 35 additions & 45 deletions

File tree

site/src/content/docs/user-guide/concepts/plugins/context-offloader.mdx

Lines changed: 35 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -245,25 +245,33 @@ agent = Agent(plugins=[
245245

246246
The plugin includes a `retrieve_offloaded_content` tool that lets the agent fetch offloaded content by reference, returning it in its native format — text as a string, JSON as a JSON block, images as image blocks, and documents as document blocks. This tool is registered by default.
247247

248+
The retrieval tool supports targeted retrieval through optional parameters, so the agent can search and filter offloaded content without loading it entirely back into context.
249+
250+
**Parameters:**
251+
248252
<Tabs>
249253
<Tab label="Python">
250254

251-
The inline guidance in offloaded results tells the agent to use its available tools to selectively access the data it needs, and mentions `retrieve_offloaded_content` as a fallback.
255+
| Parameter | Type | Description |
256+
|-----------|------|-------------|
257+
| `reference` | `str` | *(required)* Storage reference from the offloaded result |
258+
| `pattern` | `str` | Regex or keyword to grep for |
259+
| `line_range` | `dict` with `start` and `end` keys | 1-indexed inclusive line span to retrieve |
260+
| `context_lines` | `int` | Lines of context around pattern matches (default: 5) |
252261

253262
</Tab>
254263
<Tab label="TypeScript">
255264

256-
In the TypeScript SDK, the retrieval tool supports targeted retrieval through optional parameters, so the agent can search and filter offloaded content without loading it entirely back into context.
257-
258-
**Parameters:**
259-
260265
| Parameter | Type | Description |
261266
|-----------|------|-------------|
262267
| `reference` | `string` | *(required)* Storage reference from the offloaded result |
263268
| `pattern` | `string` | Regex or keyword to grep for |
264269
| `line_range` | `{ start: number; end: number }` | 1-indexed inclusive line span to retrieve |
265270
| `context_lines` | `number` | Lines of context around pattern matches (default: 5) |
266271

272+
</Tab>
273+
</Tabs>
274+
267275
**Retrieval modes:**
268276

269277
- **Pattern search** — Provide `pattern` to grep for regex/keyword matches with configurable `context_lines`
@@ -274,51 +282,18 @@ In the TypeScript SDK, the retrieval tool supports targeted retrieval through op
274282

275283
Results include line numbers to enable follow-up queries. Large result sets are truncated with guidance to narrow the search. Binary content cannot be searched — pattern and line range parameters return an error for binary references.
276284

277-
</Tab>
278-
</Tabs>
279-
280285
### Retrieval examples
281286

282-
<Tabs>
283-
<Tab label="Python">
284-
285-
**1. Tool result gets offloaded (replaces original result inline)**
286-
287-
```
288-
[Offloaded: 1 blocks, ~10,000 tokens]
289-
Tool result was offloaded to external storage due to size.
290-
Use the preview below to answer if possible.
291-
Use retrieve_offloaded_content to fetch the full content by reference.
292-
293-
{"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"},{"id":3,"name":"Charlie","rol
294-
295-
[Stored references:]
296-
mem_1_tool-123_0 (json, 42,000 bytes)
297-
```
298-
299-
**2. Agent retrieves full content**
300-
301-
Input: `{ reference: "mem_1_tool-123_0" }`
302-
303-
The tool returns the full offloaded content in its native format.
304-
305-
```
306-
{"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"},{"id":3,"name":"Charlie","role":"user"}, ...]}
307-
```
308-
309-
</Tab>
310-
<Tab label="TypeScript">
311-
312287
**1. Tool result gets offloaded (replaces original result inline)**
313288

314289
```
315290
[Offloaded: 1 blocks, ~10,000 tokens]
316291
Tool result was offloaded to external storage due to size.
317-
Use the preview below to answer if possible.
318-
Use retrieve_offloaded_content with a reference and either:
292+
Use the preview below if it answers your question.
293+
If you need more detail, use retrieve_offloaded_content with a reference and:
319294
- pattern: regex or keyword to find matching lines with context
320295
- line_range: { start, end } to read a specific span of lines
321-
Only retrieve the full content (omit pattern/line_range) as a last resort.
296+
Retrieve full content (omit pattern/line_range) as a last resort.
322297
323298
{"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"},{"id":3,"name":"Charlie","rol
324299
@@ -345,8 +320,25 @@ Input: `{ reference: "mem_1_tool-123_0", pattern: "admin", context_lines: 2 }`
345320
51| ]
346321
```
347322

348-
</Tab>
349-
</Tabs>
323+
**3. Agent retrieves a line range**
324+
325+
Input: `{ reference: "mem_1_tool-123_0", line_range: { start: 45, end: 55 } }`
326+
327+
```
328+
[Lines 45-55 of 120]
329+
330+
45| { "id": 14, "name": "Carol", "role": "user" },
331+
46| { "id": 15, "name": "Dana", "role": "user" },
332+
47| { "id": 16, "name": "Eve", "role": "admin" },
333+
48| { "id": 17, "name": "Frank", "role": "user" },
334+
49| { "id": 18, "name": "Grace", "role": "user" },
335+
50| { "id": 19, "name": "Hank", "role": "member" },
336+
51| { "id": 20, "name": "Ivy", "role": "user" },
337+
52| { "id": 21, "name": "Jack", "role": "user" },
338+
53| { "id": 22, "name": "Kate", "role": "user" },
339+
54| { "id": 23, "name": "Leo", "role": "user" },
340+
55| { "id": 24, "name": "Mia", "role": "user" },
341+
```
350342

351343
### Using other tools for retrieval
352344

strands-py/tests/strands/vended_plugins/context_offloader/test_search.py

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
"""Tests for the search module."""
22

3-
import pytest
4-
53
from strands.vended_plugins.context_offloader.search import is_searchable_content, search_content
64

75

0 commit comments

Comments
 (0)