AgentX-Dev 3.4.2__tar.gz → 3.5.0__tar.gz

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 (74) hide show
  1. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/CHANGELOG.md +851 -787
  2. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/LICENSE +21 -21
  3. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/PKG-INFO +38 -1
  4. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/README.md +1197 -1160
  5. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Agents/Agent.py +10 -2
  6. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/ChatModel.py +2274 -2274
  7. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Compiler.py +308 -308
  8. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/DefaultTools.py +2120 -2053
  9. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Media.py +864 -864
  10. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Planner.py +271 -271
  11. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Runner/AgentRun.py +2983 -2870
  12. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Runner/AsyncAgentRun.py +1179 -1061
  13. agentx_dev-3.5.0/agentx_dev/Runner/Persistence.py +860 -0
  14. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Splitters.py +306 -306
  15. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Supervisor.py +622 -104
  16. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/VectorStores/__init__.py +43 -43
  17. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/VectorStores/chroma_store.py +171 -171
  18. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/VectorStores/pg_store.py +237 -237
  19. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/__init__.py +238 -236
  20. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev.egg-info/PKG-INFO +38 -1
  21. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev.egg-info/SOURCES.txt +1 -0
  22. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/pyproject.toml +79 -79
  23. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/AGENTX.md +0 -0
  24. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/CONTRIBUTING.md +0 -0
  25. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/MANIFEST.in +0 -0
  26. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Agents/__init__.py +0 -0
  27. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/AsyncTools.py +0 -0
  28. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/AutoSetup.py +0 -0
  29. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Cache.py +0 -0
  30. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Config.py +0 -0
  31. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Embeddings.py +0 -0
  32. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Evals.py +0 -0
  33. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Handoffs.py +0 -0
  34. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Loader.py +0 -0
  35. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/MCP.py +0 -0
  36. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Memory.py +0 -0
  37. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Observability.py +0 -0
  38. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Runner/__init__.py +0 -0
  39. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Runner/promptTemplate.yaml +0 -0
  40. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Session.py +0 -0
  41. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Streaming.py +0 -0
  42. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/Tools.py +0 -0
  43. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/VectorStores/qdrant_store.py +0 -0
  44. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/WebTools.py +0 -0
  45. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/resources/__init__.py +0 -0
  46. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev/resources/promptTemplate.yaml +0 -0
  47. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev.egg-info/dependency_links.txt +0 -0
  48. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev.egg-info/requires.txt +0 -0
  49. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/agentx_dev.egg-info/top_level.txt +0 -0
  50. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/README.md +0 -0
  51. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/agentic_rag_demo.py +0 -0
  52. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/async_example.py +0 -0
  53. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/async_quickstart.py +0 -0
  54. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/auto_features_example.py +0 -0
  55. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/caching_example.py +0 -0
  56. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/chatbot_example.py +0 -0
  57. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/complete_example.py +0 -0
  58. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/concurrent_example.py +0 -0
  59. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/concurrent_tool_example.py +0 -0
  60. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/file_agent_demo.py +0 -0
  61. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/function_calling_demo.py +0 -0
  62. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/mcp_demo.py +0 -0
  63. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/mcp_github_triage_demo.py +0 -0
  64. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/observability_example.py +0 -0
  65. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/orchestration_demo.py +0 -0
  66. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/planner_example.py +0 -0
  67. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/robust_link_scraper.py +0 -0
  68. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/supervisor_codebase_analysis_demo.py +0 -0
  69. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/supervisor_example.py +0 -0
  70. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/sync_quickstart.py +0 -0
  71. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/v3_1_1_features_demo.py +0 -0
  72. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/v3_1_comprehensive_demo.py +0 -0
  73. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/examples/v3_1_features_demo.py +0 -0
  74. {agentx_dev-3.4.2 → agentx_dev-3.5.0}/setup.cfg +0 -0
@@ -1,787 +1,851 @@
1
- # Changelog
2
-
3
- All notable changes to `agentx-dev` are documented here. Format loosely
4
- follows [Keep a Changelog](https://keepachangelog.com/); versioning is
5
- [Semver](https://semver.org/).
6
-
7
- ## [3.4.2] - 2026-09-19
8
-
9
- `media=` everywhere, CSV / text / Excel attachments, and structured output
10
- on models that need the Responses API. Non-breaking.
11
-
12
- ### Added
13
-
14
- - **`media=` on chat models and structured output.** `llm.invoke`,
15
- `llm.ainvoke`, and `with_structured_output(...).invoke` / `.ainvoke` take
16
- `media=[...]` (paths, URLs, `Media`, part dicts), appended to the last
17
- user turn, matching the agent runner. Media inside `content` lists
18
- already worked; this adds the argument.
19
- - **CSV, text files, and Excel in `media=`.** Text-like files (CSV, TSV,
20
- TXT, Markdown, JSON, XML, YAML, HTML) are read as text -- exactly as
21
- written, UTF-8 or Windows-1252, CRLF normalised -- and spreadsheets
22
- (.xlsx / .xls / .ods) are converted with pandas (`dtype=object`, so
23
- cell values aren't re-inferred) to one CSV block per sheet. Both reach
24
- GPT (chat and Responses) and Claude as a labelled text block, which
25
- every model accepts. New `Media.text()` / `Media.spreadsheet()`; a
26
- 100,000-character cap (`max_chars=`, `truncate=True`). pandas and
27
- openpyxl are now core dependencies, so spreadsheets work after a plain
28
- `pip install agentx-dev` (`[excel]` still works). Date cells without a
29
- time are written as dates, not `... 00:00:00`.
30
- - **Media docs section.** Its own nav group: Overview & flow, With chat
31
- models, With agents, Reference (constructors, per-provider wire
32
- formats, errors). `docs/guides/media.md` is now a pointer to it.
33
-
34
- ### Fixed
35
-
36
- - **`with_structured_output` on models that need the Responses API.**
37
- Structured output forces a single tool; if the Responses API rejects a
38
- forced tool choice for the model, `GPT` retries with
39
- `tool_choice="required"` (the same tool when there is only one), then
40
- `"auto"`, remembering it per model. `StructuredOutputRunnable` also
41
- accepts a JSON text answer that validates against the schema.
42
- - **`.txt` media failed on Claude.** 3.4.0 stored text files as base64
43
- documents, which Anthropic only accepts for PDFs. Text files now go
44
- out as text; older base64 text parts in saved histories are decoded
45
- on the way out.
46
- - **Unsupported files reached the provider.** `Media.document()`
47
- accepted any file type -- including CSV, which Windows' own type table
48
- labels `application/vnd.ms-excel` -- and sent it as an attachment
49
- neither provider accepts. Word, PowerPoint and archives now raise
50
- `ValueError` with the fix before any request; a text file or
51
- spreadsheet by URL raises too, since only PDFs can be fetched by URL.
52
- - **Misleading WARNING on recovered calls.** The retry wrapper logged
53
- every non-retryable 400 at WARNING before the caller could recover, so a
54
- call that switched to the Responses API and succeeded still printed the
55
- original "Function tools with reasoning_effort are not supported" text.
56
- Now DEBUG; recoveries log their own WARNING and real failures log ERROR.
57
-
58
- ## [3.4.1] - 2026-09-18
59
-
60
- Tool calls on OpenAI models that require the Responses API.
61
-
62
- ### Fixed
63
-
64
- - **Tool calls failed on models that need the Responses API.** Some
65
- OpenAI models (e.g. `gpt-6-astra`) reject function tools combined with
66
- reasoning on `/v1/chat/completions`, and the error's suggested fix --
67
- `reasoning_effort='none'` -- is itself rejected by those models, so
68
- 3.4.0's parameter adaptation had nowhere to go. `GPT` now switches a
69
- model's tool calls to `/v1/responses` when the provider says to,
70
- retries, and remembers it (WARNING-logged). History is translated only
71
- at the wire (`function_call` / `function_call_output` items paired by
72
- `call_id`), so agents, `tool_calls`, and completions are unchanged.
73
- Learned parameter fixes carry across endpoints (`reasoning.effort` maps
74
- to `reasoning_effort`). Requests are sent with `store=False`, matching
75
- chat completions. Plain text calls and streaming stay on chat
76
- completions.
77
- - Requests chat completions can't express (a document URL) go to the
78
- Responses API, which accepts `file_url`, instead of raising.
79
-
80
- ### Added
81
-
82
- - `GPT(use_responses_api=None | True | False)`: automatic (default),
83
- always, or never.
84
-
85
- ## [3.4.0] - 2026-09-18
86
-
87
- Media input for GPT and Claude, models that adapt to each generation's
88
- parameter support, and workspace-rooted paths. Non-breaking; two
89
- defaults changed -- see docs/guides/upgrading.md.
90
-
91
- ### Added
92
-
93
- - **Media input for GPT and Claude.** New `Media` type
94
- (`Media.image()`, `.document()`, `.audio()`, `.from_path()`,
95
- `.from_url()`, `.from_bytes()`) and a `media=[...]` argument on
96
- `AgentRunner.invoke` / `stream` and `AsyncAgentRunner.ainvoke` /
97
- `astream`. Items can be paths, URLs, `Media`, or content-part dicts
98
- in either provider's native shape; each model renders them in its
99
- own wire format (OpenAI `image_url` / `file` / `input_audio`,
100
- Anthropic `image` / `document`). Unsupported combinations -- audio to
101
- Claude, a document URL to GPT -- raise `ValueError` before any
102
- request. Media is stored as plain JSON dicts, so `completion.history`
103
- and `Session.save()` keep working. Guide: docs/guides/media.md.
104
-
105
- - **Models adapt to per-generation parameter support.** `GPT` and
106
- `Claude` read a parameter-compatibility 400 (which names the
107
- parameter and, for enums, the allowed values), make the smallest
108
- change it asks for, retry, and remember it per model: an unsupported
109
- `reasoning_effort` moves to the nearest supported value, `max_tokens`
110
- becomes `max_completion_tokens` on reasoning models (up front for
111
- known families), parameters a model lacks are dropped, and Claude's
112
- `max_tokens` is clamped to the model's cap. Logged at WARNING; other
113
- 400s raise unchanged. `adapt_params=False` opts out.
114
-
115
- - **`Claude` gains `top_p`, `top_k`, `thinking`, `stop_sequences`.**
116
-
117
- ### Changed
118
-
119
- - `Claude(temperature=)` defaults to `None` (not sent; the API default is
120
- the old 1.0). Always sending it conflicted with `top_p` on newer models
121
- and with extended thinking.
122
- - `GPT(reasoning_effort=)` accepts any string, not just
123
- `none | low | medium | high`, so `minimal` and `xhigh` are expressible.
124
-
125
- ### Fixed
126
-
127
- - **`reasoning_effort="none"` crashed on models that don't take it**
128
- ("Unsupported value: 'reasoning_effort' does not support 'none' with
129
- this model"). The models docs even recommended `"none"` as a fix for
130
- tool-calling conflicts; that advice is gone.
131
- - **Workspace-rooted paths resolved to the drive root.** With a workspace
132
- set, `/bruce.jpeg` became `C:\bruce.jpeg` on Windows (a leading slash
133
- with no drive means the current drive's root) and the sandbox rejected
134
- it. A leading slash now means the workspace root; the re-rooted path
135
- is still sandbox-checked, so traversal is rejected as before.
136
- - **`run_python` ran in the host process's directory, not the
137
- workspace.** It passed no `cwd`, so `open("bruce.jpeg")` looked
138
- wherever the program was launched from. It now starts in the workspace,
139
- matching `run_shell`.
140
- - **Message-list input stringified media into the prompt.** A user turn
141
- whose content was a list (text + image) went through `str()`, so an
142
- attached image reached the model as base64 text. Text and media are
143
- now split, and earlier turns keep their list content.
144
- - **Claude returned the wrong block with extended thinking.** It read
145
- `response.content[0].text`; with thinking the first block is a
146
- `thinking` block. Text blocks are now joined.
147
- - `GPT.Initialize` / `stream_text` / `astream_text` now run messages
148
- through the same OpenAI translator as `call_with_tools`.
149
-
150
- ## [3.3.1] - 2026-09-09
151
-
152
- Correctness fixes in the agent loop, found by driving it with a
153
- scripted model rather than reading it. No API changes; every fix
154
- replaces a silent wrong answer or a runaway cost with correct
155
- behaviour. Nine regression tests ship with them
156
- (`tests/test_agent_loop_flaws.py`).
157
-
158
- ### Fixed
159
-
160
- - **Native binding had no loop-level spiral guard.** The repeat breaker
161
- sat after the native branch's `continue`, so `bind_tools_natively`
162
- runs never reached it: a model stuck re-issuing one call burned the
163
- full `max_iterations` (20 LLM turns where text mode stopped at 3) and
164
- returned the "hit max_iterations" recap quoting the dup-guard's own
165
- warning text instead of the data.
166
-
167
- - **`respond` batched with real tool calls dropped them.** A model that
168
- emitted "do X, and here is my answer" in one turn had X silently
169
- discarded -- never dispatched, never in `completion.tool_calls`, no
170
- error. The batch now runs and the answer defers one turn.
171
-
172
- - **`completion.history` could not be replayed as `chat_history`.** The
173
- copy filter kept only truthy `{role, content}`, which dropped every
174
- tool-calling assistant turn (`content=""`), stripped `tool_call_id`
175
- off `role="tool"` messages, and replayed a stored system prompt on top
176
- of the fresh one -- so a follow-up call sent two system messages, zero
177
- assistant turns, and an orphaned tool message providers reject. Fixed
178
- in both runners.
179
-
180
- - **A sync `AgentRunner` silently ignored async tools.** `known_tools`
181
- unioned only the two sync registry tables while the registry accepted,
182
- listed and prompt-advertised async ones, so calling one fell through
183
- to implicit-final and returned `action_input` as the answer with an
184
- empty `tool_calls` list. Now unions all four, matching the async
185
- runner; the sync dispatcher already returns a clear `ToolError`, so
186
- the silent wrong answer became an actionable one.
187
-
188
- - **`AsyncAgentRunner` regressed the function-calling message shape.**
189
- It appended its FC turn as raw JSON text with no `tool_calls` block
190
- and never set `_last_function_call_id`, so observations went back as
191
- `role="user"` -- text-mode shape while in FC mode, losing provider
192
- correlation and the cached prefix.
193
-
194
- - **A `BaseException` from a specialist orphaned its siblings.**
195
- `CancelledError` and `KeyboardInterrupt` are not `Exception`, so
196
- `_run_subtask`'s handler never saw them; `t.result()` re-raised and
197
- left sibling tasks running unowned, with in-flight LLM calls still
198
- billing. The scheduler now owns its tasks in a `try`/`finally`, which
199
- also covers a consumer that stops iterating `astream` early.
200
-
201
- - **The tool cache collided on tool name.** It is a process-wide
202
- singleton keyed on `(tool_name, args)` with no record of which
203
- implementation ran, so two runners whose tools merely share a name --
204
- `search`, `fetch`, `query`, routine across Supervisor specialists --
205
- served each other's results and the second function never ran. Keys
206
- now fold in the callable's `module.qualname`, so same-name /
207
- different-implementation misses while genuinely identical tools still
208
- share, including across processes for the disk-backed `FileCache`.
209
-
210
- ### Docs
211
-
212
- - Streaming documentation described parameters the API rejects.
213
- `AsyncAgentRunner.astream()` and `HandoffCoordinator.stream()` take no
214
- `stream_tokens` (only the sync `AgentRunner.stream()` does), and every
215
- `text_delta` example was built on a default model where
216
- `use_function_calling` auto-detects to `True` and yields zero deltas.
217
- `simple_stream` was documented with the wrong signature entirely.
218
- Added a table naming exactly which stream methods accept what.
219
-
220
- ### Tests
221
-
222
- - Repaired 20 stale text-mode tests. `MockModel` defined
223
- `call_with_tools` unconditionally, so 3.1.7's auto-detect routed every
224
- text script down the function-calling path and the runner returned
225
- `""`. The mock now advertises the capability only when scripted for
226
- it. Suite: 206 passed, 3 skipped.
227
-
228
- ## [3.3.0] - 2026-08-19
229
-
230
- Dependency DAGs for the Supervisor. Plans declare which steps consume
231
- which, and the executor derives ordering, parallelism, AND context
232
- routing from those edges — unifying the old split where sequential
233
- mode had threading but no parallelism and concurrent mode had
234
- parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
235
-
236
- ### Added
237
-
238
- - **`depends_on` plan steps.** Every plan step now carries an `id`;
239
- a step that consumes an earlier step's output lists that id in
240
- `depends_on`. Sync `Supervisor` executes in stable topological
241
- order; `AsyncSupervisor` runs a completion-driven scheduler where a
242
- step starts the MOMENT its dependencies finish (not on wave
243
- barriers) and independent steps run concurrently. In DAG mode each
244
- step is threaded ONLY its direct dependencies' results — explicit
245
- routing instead of "everything prior", which also stops the
246
- per-entry context budget shrinking as plans grow.
247
-
248
- - **Plan sanitization that never fails a run.** Missing/duplicate ids
249
- auto-assigned, unknown dependencies dropped (a planner typo degrades
250
- to a root step, not a dead run), self-deps dropped, cycles broken
251
- deterministically (back-edge in plan order), spawn steps cannot be
252
- depended on. If repairs were needed, the plan is re-requested once
253
- (`max_plan_retries`, default 1) with the repair warnings appended;
254
- the sanitized original is kept when the retry is no better.
255
-
256
- - **Failure cascade + `skipped` flag.** A step whose dependency failed
257
- (after retries / success-check) is skipped, transitively, with
258
- `SubtaskResult.skipped=True` and an error naming the failed dep.
259
- Independent branches keep running; synthesis runs over what
260
- succeeded. Skipped steps never dispatch — no tokens burned
261
- downstream of garbage.
262
-
263
- - **`skip_when` conditional execution.** A step may declare
264
- `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
265
- evaluated in Python (no LLM call) against the dependency's 3.2
266
- structured output, dotted paths supported, strictly FAIL-OPEN (any
267
- doubt → the step runs). Condition-skips do NOT cascade — dependents
268
- treat them as empty successes ("retrieval unnecessary" is not
269
- "answering impossible").
270
-
271
- - **`Specialist` registry entries.** `agents={}` now also accepts
272
- `Specialist(description, runner, depends_on=[...names...],
273
- output_schema=..., when_to_use=...)`. The extras render into the
274
- planning catalog (`typically after:` / `returns: Schema(fields)` /
275
- `use when:`) so the planner can write real dependency graphs and
276
- `skip_when` conditions against actual field names. `depends_on`
277
- here is a planner HINT, never an execution constraint (the same
278
- specialist can appear twice in one plan; step-ids disambiguate).
279
- Classic `(description, runner)` tuples keep working — they are
280
- wrapped internally, and `Specialist` tuple-unpacks for older code.
281
-
282
- - **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
283
- rate-limited deployments. `sequential=True` is now sugar for
284
- `max_parallel=1` with all-prior threading.
285
-
286
- - **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
287
- `step_id` field on `dispatch` / `subtask_result` stream events.
288
-
289
- ### Backward compatibility
290
-
291
- A plan where NO step declares `depends_on` runs with byte-identical
292
- legacy semantics: sync + async-sequential thread all prior results in
293
- plan order; async-concurrent runs everything at once with no
294
- threading. Verified by regression tests against the 3.2 behaviour.
295
-
296
- ## [3.2.0] - 2026-08-13
297
-
298
- Typed multi-agent pipelines. Specialists can now declare a Pydantic
299
- output schema once and pass validated instances to each other through
300
- the Supervisor, instead of downstream agents re-parsing prose.
301
-
302
- ### Added
303
-
304
- - **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
305
- constructor.** Declare the runner's output shape once
306
- (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
307
- on every call or describing JSON in the prompt. A per-call
308
- `output_schema=` still wins when both are set. `None` keeps the exact
309
- pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
310
-
311
- - **Schema coercion via forced native function calling.** When a schema
312
- is in play, the final answer is converted by forcing a provider-native
313
- tool call against the schema (constrained decoding), not by regexing
314
- JSON out of prose. The ReAct loop itself is untouched: tool selection
315
- and intermediate reasoning run exactly as before, and the coercion
316
- happens once, after the loop finishes. Models without a
317
- `call_with_tools` implementation fall back to the previous text-JSON
318
- parsing, so custom `BaseChatModel` subclasses keep working.
319
- `completion.content` keeps the human-readable answer alongside
320
- `completion.output` in every case.
321
-
322
- - **`SubtaskResult.output`.** The Supervisor now preserves each
323
- specialist's validated Pydantic instance next to its `content` text.
324
- Consumers that only read `content` are unaffected.
325
-
326
- - **Structured specialist-to-specialist handoff.** When an earlier step
327
- produced typed output, `_build_augmented_query` serializes it into the
328
- next specialist's context as a labelled JSON block
329
- (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
330
- text, so downstream steps parse fields rather than interpreting
331
- sentences like `INTENT: ... SEARCH_QUERY: ...`.
332
-
333
- - **`vector_search_tool` pipeline options.** New kwargs:
334
- `max_text_chars` (default 500; pass `0` for full untruncated passages,
335
- which a reranker judging evidence actually needs) and
336
- `structured_output` (default False; when True the tool returns a JSON
337
- array of `{id, text, vector_score, metadata}` instead of the
338
- human-formatted list). Defaults preserve existing behaviour byte-for-
339
- byte.
340
-
341
- ### Fixed
342
-
343
- - **Supervisor planning prompt contradicted the execution engine.** The
344
- planner rule said sub-agents "do NOT see previous steps' output" and
345
- discouraged dependency chains, but the dispatcher has threaded prior
346
- findings into every step since `_build_augmented_query` shipped.
347
- The rule now tells the planner that sequential steps receive earlier
348
- results (structured when available) and that chains like
349
- intent -> retrieval -> reranking are a good plan shape, while still
350
- requiring same-specialist steps to merge and banning report-only steps.
351
-
352
- ## [3.1.7] — 2026-07-27
353
-
354
- ### Changed
355
-
356
- - **`use_function_calling` default flipped to auto-detect** on
357
- `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
358
- now `Optional[bool] = None`; `None` resolves to `True` when the
359
- model class overrides `BaseChatModel.call_with_tools` (both `GPT`
360
- and `Claude` do) and to `False` when it doesn't (or when
361
- `bind_tools_natively=True`). Callers passing `True`/`False`
362
- explicitly are unaffected. Rationale: text-mode ReAct requires the
363
- model to emit strict JSON with any long `action_input` string
364
- properly escaped — a 1200-word markdown draft with unescaped
365
- newlines or quotes reliably breaks `json.loads` and killed the run.
366
- Function-calling mode routes the parser through the SDK's typed
367
- channel so escaping is handled automatically. The historical
368
- default (`False`) was the fragile option; the new default matches
369
- what most users actually want.
370
-
371
- ### Fixed
372
-
373
- - **Malformed parser JSON no longer crashes the run.** When the
374
- text-mode assistant response failed `json.loads` (typically because
375
- a long `action_input` string had unescaped `"`, `\n`, or backticks),
376
- the framework used to raise `JSONDecodeError` and unwind the whole
377
- invocation. The runner now (1) tries a regex-based salvage that
378
- extracts `{Thought, action, action_input}` from the raw text
379
- covering the common "outer envelope valid, inner string broke
380
- escaping" failure, and (2) if salvage fails, feeds a targeted fix
381
- hint back to the model (`"your last response was not valid JSON;
382
- emit …, escape newlines as \n"`) and continues the loop bounded
383
- by `max_iterations`. Exhaustion returns a clear framework message
384
- rather than an uncaught exception. Applied to both sync and async
385
- runners via a shared `_salvage_react_json` helper.
386
- The salvager's action-name regex is intentionally strict
387
- (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
388
- "action" out of an unrelated `"key":"value"` pair inside malformed
389
- JSON.
390
-
391
- - **Verbose trace in `bind_tools_natively` mode now prints tool
392
- name + args + response.** Previously native runs showed blank
393
- `[tool.call.start]` / `[tool.call.complete]` pairs (the
394
- observability layer fires them without the trace context), so you
395
- couldn't tell which tool the model actually invoked or what came
396
- back. The runner now prints `[tool] Invoking '<name>' with args:
397
- <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
398
- when the dispatch raised) in the post-dispatch loop, matching the
399
- format text-mode and function-calling mode use. Mirrored to the
400
- async runner.
401
-
402
- - **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
403
- a vector store** instead of dumping raw HTML into the model's
404
- context. Fixes the TPM-limit trap: when a research agent fetches
405
- four articles in parallel (via ``multi_tool_use.parallel`` or
406
- native binding), the combined bodies can easily exceed 40k tokens
407
- and blow past a 30k TPM ceiling on the very next model call.
408
- New parameters on ``web_fetch_tool``:
409
-
410
- | Kwarg | Default | Effect |
411
- |---|---|---|
412
- | ``vector_store`` | ``None`` | When set, each fetch is HTML-stripped, chunked with ``TextSplitter``, embedded via the store's embeddings, and added with ``{src: url, chunk_index, total_chunks}`` metadata. The tool response becomes a compact summary (URL, byte count, chunk count, 240-char preview) — NOT the raw body. The model then calls ``vector_search`` / ``Rag`` to pull only the passages it needs. |
413
- | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
414
- | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
415
-
416
- Backwards-compatible: the positional ``cache_dir`` signature keeps
417
- working; `web_fetch_tool()` with no ``vector_store`` returns raw
418
- body as before. Ingest and cache_dir compose — enable both and get
419
- disk-cached full bodies AND searchable chunks. HTML stripping is
420
- minimal and dependency-free (regex-based: script/style blocks
421
- dropped whole, then tags stripped, whitespace collapsed) so the
422
- ingest path adds no new install dependency. On JSON/plain-text
423
- responses the stripper is a near no-op.
424
-
425
- The observation returned to the model shows topical coverage --
426
- first, middle, and last chunk previews (up to 3 samples,
427
- deduplicated for short pages) -- so the model can tell what
428
- topics the page actually covers, not just the intro paragraph.
429
- Without this the model would only see the page's opening and
430
- wouldn't know to query for topics discussed later in the same
431
- page. Explicit instruction in the observation ("query with
432
- SPECIFIC keywords from the topics above; do NOT re-fetch; do
433
- NOT ask for the full body") steers the model toward the RAG path
434
- on follow-up turns.
435
-
436
- - **`multi_tool_use.parallel` now reaches its dispatch path.**
437
- When GPT wanted to batch several tool calls into one turn (fetch N
438
- URLs concurrently, run M searches at once), it emitted OpenAI's
439
- synthetic `multi_tool_use.parallel` meta-tool. The registry's
440
- `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
441
- already knew how to unpack it, but the runner loop's known-tools
442
- guardrail rejected the name FIRST as unregistered — dumping the
443
- raw `{"tool_uses": [...]}` payload into the user-facing "final
444
- answer" and never invoking any of the nested calls. Added
445
- `multi_tool_use.parallel` to the recognized action set in both
446
- sync and async runners so the meta-tool flows through to dispatch
447
- and the existing unpackers run. Nested calls with the `functions.`
448
- prefix are normalized before dispatch (same as top-level FC
449
- calls), so the model can emit either shape.
450
-
451
- - **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
452
- Passing `full_access("./workspace")` used to iterate the string
453
- into 11 single-character "subtrees" (Python's `list("./workspace")`)
454
- — every path check silently rejected because no real path could
455
- ever match a `"."` or `"/"` "allowed subtree". The classmethod
456
- now detects a bare string and treats it as `[allowed_paths]`, so
457
- `full_access("./workspace")` does the intuitive thing (equivalent
458
- to `full_access(["./workspace"])` and auto-infers the workspace).
459
- Same fix on `read_only`. List inputs are unchanged.
460
-
461
- - **`Permissions.full_access` now accepts (and auto-infers)
462
- `workspace`.** The classmethod set `allowed_paths` but not
463
- `workspace`, so short paths like `write_file(path="report.md")`
464
- resolved to CWD (outside the sandbox) and raised
465
- `PermissionError: access denied` — a landmine that every caller of
466
- `Permissions.full_access(["./workspace"])` hit sooner or later.
467
- New signature: `full_access(allowed_paths, *, workspace=None)`.
468
- When `workspace` isn't passed AND `allowed_paths` has exactly one
469
- entry, that path is auto-set as the workspace (the "project-scoped
470
- agent whose one allowed subtree IS its workspace" case, which is
471
- 99% of use). Two or more paths stay ambiguous and require an
472
- explicit `workspace=` if short-path resolution is wanted. Pass an
473
- explicit `workspace=` string to override the auto-choice.
474
- Backwards-compatible on the positional signature; adds a keyword
475
- argument that existing callers didn't use.
476
-
477
- ## [3.1.5] — 2026-07-26
478
-
479
- ### Fixed
480
-
481
- - **Text-mode tool results no longer use `role: "function"`.** In text
482
- mode (the default — no `use_function_calling`) the runner fed each tool
483
- observation back to the model as a `role: "function"` message. Newer
484
- OpenAI models reject that role outright (`400 … 'messages[N].role' does
485
- not support 'function' with this model`, e.g. gpt-5.x), and Anthropic
486
- never accepted it — text-mode multi-tool runs on Claude were latently
487
- broken too; older GPT models simply still tolerated the legacy role.
488
- Tool observations now go back as a plain `role: "user"` turn framed as
489
- `Observation: …`, which every provider and model generation accepts and
490
- which matches the ReAct template's own few-shot convention.
491
- Function-calling mode is unchanged (native `role: "tool"` +
492
- `tool_call_id`). The async runner was additionally emitting `function`
493
- unconditionally (even in FC mode); it now uses the same shared helper.
494
-
495
- ### Added
496
-
497
- - **`subtask_success_check` on `Supervisor` / `AsyncSupervisor`.** Opt-in
498
- predicate `(SubtaskResult) -> bool | str` that decides whether a
499
- *returned* (non-raised) sub-task result is actually acceptable — the
500
- "ran fine but produced nothing useful" case a plain retry can't catch
501
- (a scraper that saved 0 links, an extractor that found nothing). Return
502
- `True` to accept, or `False`/a `str` reason to reject; a rejected
503
- result is retried like a raised error, with the reason fed back into the
504
- query, bounded by `max_subtask_retries`. After retries are exhausted the
505
- last result is returned with its `error` set (content preserved). A
506
- check that itself raises is treated as "accept" so a buggy predicate
507
- can't wedge the run. Default `None` keeps the exceptions-only behavior.
508
- New example `examples/robust_link_scraper.py` wires it together with a
509
- scraping `system_addendum` (parse relative+absolute hrefs, fall back to
510
- `sitemap.xml` on JS-rendered sites).
511
-
512
- ## [3.1.4] — 2026-07-26
513
-
514
- ### Fixed
515
-
516
- - **A malformed-JSON tool argument no longer crashes the whole agent
517
- run.** When a model emitted a Python snippet or a Windows path as a
518
- tool-call argument — `re.findall(r'\d+')`, `C:\Users` — the `\d` / `\U`
519
- are illegal JSON escapes, and the OpenAI adapter's eager
520
- `json.loads(call.function.arguments)` raised `JSONDecodeError` and
521
- `raise`d it, unwinding the entire ReAct loop before the agent's own
522
- retry machinery could act. Under a Supervisor this surfaced as a bare
523
- `ERROR: Invalid \escape: line 1 column 598` and the sub-task was
524
- abandoned. Now:
525
- - `_parse_tool_arguments` repairs the common case (backslashes that
526
- don't begin a valid JSON escape are doubled), recovering `\d`,
527
- `\w`, `\s`, etc. with zero extra round-trips. A backslash before a
528
- valid-escape letter (`\b`, `\n`, …) remains ambiguous and is left
529
- as the escape — a documented limit.
530
- - When repair fails, `call_with_tools` returns a dedicated
531
- `invalid_tool_args` result and the loop feeds the error back as a
532
- retryable observation ("your arguments weren't valid JSON — escape
533
- backslashes and resend"), bounded by `max_iterations`, in all
534
- three modes across both `AgentRunner` and `AsyncAgentRunner`.
535
- `Claude` was already immune (its tool inputs arrive pre-parsed).
536
-
537
- - **A tool-call preamble is no longer returned as the final answer.**
538
- Models routinely end a turn with an announcement instead of an action
539
- — "I'll look up your recent scores to get a clear view of your
540
- communication skills. Just a second!" — and every "no tool call
541
- found" branch in both runners was coded as *this text is the answer,
542
- break*. The loop terminated on iteration 1 and the caller got a
543
- promise instead of a result. Three sites per runner were affected:
544
- the native-binding path (`type != "tool_use"`), the
545
- `use_function_calling` path (parser unresolved), and the JSON-text
546
- path (response didn't parse). `max_iterations` never helped, because
547
- the break happened before any iteration was spent.
548
-
549
- The runner now feeds the model one corrective nudge — "your last turn
550
- had no action, so nothing happened; do it, don't announce it" — and
551
- continues the loop. Verified against both `AgentRunner` and
552
- `AsyncAgentRunner` in all three modes.
553
-
554
- ### Added
555
-
556
- - **Proactive "act, don't announce" system-prompt clause.** The reactive
557
- `text_turn_nudges` fix corrects an agent *after* it narrates instead of
558
- acting; this clause heads it off. When (and only when) an agent has
559
- tools, its system prompt now tells it to call the tool rather than
560
- reply "I'll do X / just a second" and stop — and to report what it DID
561
- in past tense. Injected in all three modes across both runners; skipped
562
- for tool-less chat agents, where prose is the correct answer. Sits
563
- before any `system_addendum` so a caller's role instructions still win.
564
-
565
- - **`max_subtask_retries` on `Supervisor` / `AsyncSupervisor`** (default
566
- `1`). A sub-task that raised used to be recorded as an error and the
567
- Supervisor moved straight to synthesis — no second attempt. Now a
568
- failed sub-task is re-dispatched up to this many times, with the prior
569
- error appended to the query so the specialist knows what to fix
570
- ("your previous attempt failed with X — diagnose and try again").
571
- Bounded and informed: only raised exceptions trigger a retry (a
572
- sub-task that returns content is accepted as-is, since the Supervisor
573
- can't tell "terse but correct" from "wrong"), and the error text is
574
- fed back rather than blindly re-running. Set to `0` for the old
575
- quit-on-first-failure behavior. Applies in both sequential and
576
- concurrent async modes.
577
-
578
- - **`text_turn_nudges` on `AgentRunner` / `AsyncAgentRunner`** (default
579
- `1`). Caps the re-prompts described above at one extra LLM call per
580
- run; after the budget is spent the model's text stands as the answer.
581
- Set to `0` for the previous behavior. Automatically skipped when no
582
- tools are registered, since a runner with no tools is a plain chat
583
- call and prose genuinely is the answer there.
584
-
585
- ## [3.1.3] — 2026-07-22
586
-
587
- Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
588
- need to upgrade for functionality; upgrade to pick up the improved
589
- onboarding docs bundled in the sdist.
590
-
591
- ### Documentation
592
-
593
- - **Tools doc rewritten to answer "how do I actually use these?"**
594
- Added §0 `How each built-in tool is registered` as the entry
595
- section. Two registration paths — auto vs manual — laid out in a
596
- table on the first screen. Six runnable subsections covering every
597
- combination:
598
- - §0.1 DefaultTools via `Permissions(...)` (auto)
599
- - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
600
- - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
601
- `vector_search_tool(store)`
602
- - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
603
- - §0.5 Custom `StructuredTool` from scratch
604
- - §0.6 Fully-loaded runner combining all of the above
605
- - §0.7 Rules on name collisions, invisible-denied-capabilities,
606
- async-tool behavior
607
- The existing inventory + wrapper / controls / cheat-sheet sections
608
- are unchanged; they now sit after the "how to use them" primer
609
- instead of before it.
610
-
611
- ## [3.1.2] — 2026-07-22
612
-
613
- Patch release. Two independent fixes.
614
-
615
- ### Fixed
616
-
617
- - **`llm_judge` correctly parses YES/NO across providers.** The judge
618
- parser was comparing the reply's first word to the literal string
619
- `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
620
- equality check and marked every genuine PASS as FAIL. Claude replies
621
- `"YES"` without punctuation so the bug hid during local development.
622
- Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
623
- insensitive) at the start of the reply. Handles every real shape:
624
- `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
625
- Ambiguous replies (`Maybe`, empty string) still fail closed.
626
- - Regression test `test_llm_judge_parses_various_verdict_shapes`
627
- covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
628
-
629
- ### Added
630
-
631
- - **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
632
- longer need to remember which module each tool lives in:
633
-
634
- ```python
635
- from agentx_dev.Tools import (
636
- StandardTool, StructuredTool,
637
- AsyncStandardTool, AsyncStructuredTool,
638
- web_search_tool, web_fetch_tool,
639
- vector_search_tool, handoff_tool,
640
- DefaultTools, Permissions,
641
- )
642
- ```
643
-
644
- Both this form and the pre-existing `from agentx_dev import X`
645
- form coexist. Implementation uses PEP 562 module `__getattr__`
646
- and `__dir__` so re-exports are lazy (no import cost for modules
647
- the caller doesn't touch) and show up in IDE autocomplete +
648
- `dir(agentx_dev.Tools)`.
649
-
650
- ## [3.1.1] — 2026-07-21
651
-
652
- Second batch of 3.1 features + a full docs + brand pass.
653
-
654
- ### Added
655
-
656
- **Streaming through orchestration**
657
- - `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
658
- `plan_start` / `plan` / `dispatch` / `subtask_result` /
659
- `synthesize_start` / `final` / `completion` events.
660
- - `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
661
- `completion` / `handoff` / `final` / `result` events per hop.
662
- - Legacy `.run()` / `.arun()` refactored to consume the streams (no
663
- code duplication).
664
-
665
- **Prompt optimization — `Compiled`**
666
- - New `agentx_dev.Compiler` module.
667
- - `Compiled(runner_factory, trainset, ...)` iteratively refines a
668
- runner's `system_addendum` against the eval harness. Half of
669
- DSPy's power at a tenth of the surface.
670
-
671
- **Anthropic Batch API**
672
- - `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
673
- batch rate, polls to completion, returns results in submission order.
674
- - Per-request error dicts on failure; token usage funneled into
675
- `TokenUsage` so cost tracking stays a single source of truth.
676
-
677
- **Vector store adapters — `agentx_dev.VectorStores`**
678
- - `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
679
- public shape as the in-memory `VectorStore` (`add` / `search` /
680
- `delete` / `clear` / `__len__` / `embeddings`).
681
- - `vector_search_tool()` and `SemanticMemory` accept any of them.
682
- - SDK imports lazy; friendly `ImportError` when the underlying SDK
683
- is missing.
684
-
685
- **Trace viewer (`viewer/`)**
686
- - Self-hosted single-page app that reads `FileHook` JSONL and renders
687
- a timeline with type/text filters, summary sidebar, JSON drill-down.
688
- - Works from `file://`, no server required.
689
-
690
- **Docs site (`host/`)**
691
- - Full editorial dark-first design system (JetBrains Mono headings,
692
- Inter body, `#B8FF3E` electric-lime accent).
693
- - Command palette (`Cmd+K`) with keyboard navigation and live search.
694
- - Hero code snippet with hand-tinted syntax highlighting.
695
- - Reading progress bar, breadcrumbs, header anchor links.
696
- - Sidebar sliding active marker, collapsible groups.
697
- - Code copy buttons, language labels.
698
- - Right-rail auto-TOC with `IntersectionObserver` scrollspy.
699
- - Dark/light theme toggle, persisted.
700
- - Cache-busted assets so edits land on refresh without hard-reload.
701
-
702
- **Brand identity (`brand/`)**
703
- - Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
704
- `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
705
- - Copy audit dropped "small" (weak) and "LangChain" references from
706
- all marketing surfaces.
707
- - Favicon wired into docs + trace viewer.
708
-
709
- **Test suite (`tests/`)**
710
- - Restored + expanded pytest suite: 127 tests passing (3 skipped for
711
- absent optional SDKs).
712
- - Coverage: parser + all `AgentType` variants, `ToolRegistry`
713
- (dispatch / dup-guard / circuit-breaker / timeout), Permissions
714
- (capability gating + sandbox + traversal), budgets (cost / rate /
715
- retry / non-retryable HTTP), runner loop (streaming + output_schema
716
- + chat history), embeddings + `VectorStore` + `SemanticMemory`,
717
- handoffs (bounded hops + history sanitization), evals harness
718
- (all assertion helpers + JSON case loaders), vector-store adapter
719
- shape conformance.
720
-
721
- **Docs (`docs/`)**
722
- - Full docs tree (34 pages), including new pages for:
723
- vector store adapters, prompt optimization, batch API, trace viewer,
724
- and a **use-cases** landing (13 concrete scenarios with runnable code).
725
- - Rewrote **Tools** page to enumerate every built-in tool with args,
726
- return shape, capability flag, and use-case guidance.
727
- - Rewrote **Agents** page to cover all four orchestration
728
- architectures (Solo / Supervisor / Handoffs / Compiled) with
729
- decision trees, worked examples, and cheat sheet.
730
- - **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
731
- parallel retrieval, self-critique, citations, user memory.
732
-
733
- **Examples**
734
- - `examples/agentic_rag_demo.py` — the runnable version of the
735
- agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
736
- runs a 3-turn scripted session proving user-notes recall works.
737
-
738
- **Package**
739
- - `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
740
- - `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
741
-
742
- ### Fixed
743
-
744
- - `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
745
- minimal system prompt instead of the AgentType template so the
746
- ReAct `action/action_input` scaffold no longer fights the native
747
- tool interface. Previously produced JSON-blob answers under GPT.
748
- - `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
749
- and function role messages between hops so tool_call_ids from a
750
- previous agent don't leak into the next model's call (OpenAI 400).
751
- - Docs site marker positioning uses double-`requestAnimationFrame` +
752
- `document.fonts.ready` so the sidebar accent bar lands on the
753
- correct row even on a cold font cache.
754
- - Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
755
- outrank `#doc a` link styling (previously rendered lime-on-lime
756
- and was invisible).
757
-
758
- ### Notes
759
-
760
- - Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
761
- did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
762
- and includes both batches of features.
763
-
764
- ## [3.1.0] — internal only (commits 52840e7)
765
-
766
- First batch of 3.1 features. Committed but not released to PyPI.
767
- Merged into 3.1.1 for the public release.
768
-
769
- ### Added
770
- - Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
771
- - Parallel per-turn tool dispatch in `AgentRunner`
772
- (`bind_tools_natively=True`, `parallel_tool_workers`).
773
- - Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
774
- - RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
775
- `VectorStore`, `VectorHit`, `vector_search_tool()`).
776
- - Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
777
- `HandoffCoordinator`, `HandoffResult`).
778
- - Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
779
- helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
780
- - `TokenUsage.cache_hit_ratio` property.
781
-
782
- ## [3.0.6] — 2026-03 (baseline)
783
-
784
- Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
785
- persistent state, scrubbed subprocess env, path sanitizer,
786
- `permissions.json` mode 0o600, ReDoS guard on `grep`,
787
- `invoke`/`ainvoke` accept bare strings and message lists).
1
+ # Changelog
2
+
3
+ All notable changes to `agentx-dev` are documented here. Format loosely
4
+ follows [Keep a Changelog](https://keepachangelog.com/); versioning is
5
+ [Semver](https://semver.org/).
6
+
7
+ ## [3.5.0] - 2026-10-04
8
+
9
+ Agents that keep working through errors. Opt-in; one default change (below).
10
+
11
+ ### Added
12
+
13
+ - **Persistent mode** (`persistence=Persistence(...)`) for `AgentRunner`,
14
+ `AsyncAgentRunner`, `Supervisor` and `AsyncSupervisor`. When a run gets
15
+ stuck (the same call repeated, or tool errors in a row) it is
16
+ asked, in four escalating steps, to find the root cause, try a
17
+ different approach, probe its assumptions, and say what blocks it,
18
+ before it may stop; real progress resets the ladder. Runs stop on
19
+ `max_minutes` or the model's cost cap, not a step count.
20
+ - **Context compaction** for long runs: old turns become notes, the task
21
+ (with its attachments) and recent turns are untouched, and the failed
22
+ attempts are kept word for word.
23
+ - **Patient retries**: transient provider errors (429, 5xx, timeouts,
24
+ connection errors) are retried with backoff until the deadline; auth
25
+ and invalid-request errors still raise at once.
26
+ - **Supervisors replan**: a step that does not finish is replanned
27
+ around under one shared deadline; finished steps are kept and can be
28
+ depended on. A recovery step names the steps it redoes
29
+ (`"replaces": [...]`); a failed step counts as resolved only when its
30
+ replacement finishes. New `replan`, `reflect`, `compact` and `budget`
31
+ stream events.
32
+ - **Outcomes**: every completion has `.outcome` and (persistent runs)
33
+ `.progress`; `SubtaskResult` and `SupervisorResult` have `.outcome`.
34
+ - New guide: Long-running agents.
35
+
36
+ ### Changed
37
+
38
+ - A `Supervisor`/`AsyncSupervisor` now treats a specialist that finished
39
+ with an outcome other than `done` (for example `iteration_limit`) as a
40
+ failed attempt: it retries up to `max_subtask_retries` with the reason
41
+ fed back, then flags the step. Previously such a result was accepted
42
+ as a success. This applies without `persistence`. Consequences: each
43
+ give-up costs one extra attempt by default (`max_subtask_retries=1`);
44
+ the flagged step's recap is no longer passed to downstream
45
+ specialists; steps that `depends_on` it are skipped; and
46
+ `SupervisorResult.outcome` is `partial` or `stuck`.
47
+ - While `persistence` is set the tool-result cache is off, and the
48
+ iteration cap is `persistence.max_turns`.
49
+
50
+ ## [3.4.3] - 2026-09-26
51
+
52
+ Two path-resolution fixes for Windows sandboxes. Non-breaking.
53
+
54
+ ### Fixed
55
+
56
+ - **`full_access(["/workspace"])` now means the project's workspace
57
+ folder, not the drive root.** On Windows a rooted path without a drive
58
+ letter resolves to the current drive, so the sandbox became
59
+ `C:\workspace`; `auto_create_paths` then created it, and an agent
60
+ asked for `workspace/spam.csv` searched an empty directory outside the
61
+ project and reported the file missing. Slash-rooted sandbox roots are
62
+ now re-rooted at the running project, matching what a leading slash
63
+ already meant for tool arguments. POSIX absolute paths (`/workspace`
64
+ as a Docker mount) and drive-qualified paths are untouched.
65
+ - **`workspace/report.md` no longer nests into
66
+ `<workspace>/workspace/report.md`.** The `workspace` field documented
67
+ this pass-through, but only the `./workspace/...` spelling had it.
68
+ Models name the workspace folder constantly, so the missing case hit
69
+ often; new files still resolve into the workspace as before.
70
+
71
+ ## [3.4.2] - 2026-09-19
72
+
73
+ `media=` everywhere, CSV / text / Excel attachments, and structured output
74
+ on models that need the Responses API. Non-breaking.
75
+
76
+ ### Added
77
+
78
+ - **`media=` on chat models and structured output.** `llm.invoke`,
79
+ `llm.ainvoke`, and `with_structured_output(...).invoke` / `.ainvoke` take
80
+ `media=[...]` (paths, URLs, `Media`, part dicts), appended to the last
81
+ user turn, matching the agent runner. Media inside `content` lists
82
+ already worked; this adds the argument.
83
+ - **CSV, text files, and Excel in `media=`.** Text-like files (CSV, TSV,
84
+ TXT, Markdown, JSON, XML, YAML, HTML) are read as text -- exactly as
85
+ written, UTF-8 or Windows-1252, CRLF normalised -- and spreadsheets
86
+ (.xlsx / .xls / .ods) are converted with pandas (`dtype=object`, so
87
+ cell values aren't re-inferred) to one CSV block per sheet. Both reach
88
+ GPT (chat and Responses) and Claude as a labelled text block, which
89
+ every model accepts. New `Media.text()` / `Media.spreadsheet()`; a
90
+ 100,000-character cap (`max_chars=`, `truncate=True`). pandas and
91
+ openpyxl are now core dependencies, so spreadsheets work after a plain
92
+ `pip install agentx-dev` (`[excel]` still works). Date cells without a
93
+ time are written as dates, not `... 00:00:00`.
94
+ - **Media docs section.** Its own nav group: Overview & flow, With chat
95
+ models, With agents, Reference (constructors, per-provider wire
96
+ formats, errors). `docs/guides/media.md` is now a pointer to it.
97
+
98
+ ### Fixed
99
+
100
+ - **`with_structured_output` on models that need the Responses API.**
101
+ Structured output forces a single tool; if the Responses API rejects a
102
+ forced tool choice for the model, `GPT` retries with
103
+ `tool_choice="required"` (the same tool when there is only one), then
104
+ `"auto"`, remembering it per model. `StructuredOutputRunnable` also
105
+ accepts a JSON text answer that validates against the schema.
106
+ - **`.txt` media failed on Claude.** 3.4.0 stored text files as base64
107
+ documents, which Anthropic only accepts for PDFs. Text files now go
108
+ out as text; older base64 text parts in saved histories are decoded
109
+ on the way out.
110
+ - **Unsupported files reached the provider.** `Media.document()`
111
+ accepted any file type -- including CSV, which Windows' own type table
112
+ labels `application/vnd.ms-excel` -- and sent it as an attachment
113
+ neither provider accepts. Word, PowerPoint and archives now raise
114
+ `ValueError` with the fix before any request; a text file or
115
+ spreadsheet by URL raises too, since only PDFs can be fetched by URL.
116
+ - **Misleading WARNING on recovered calls.** The retry wrapper logged
117
+ every non-retryable 400 at WARNING before the caller could recover, so a
118
+ call that switched to the Responses API and succeeded still printed the
119
+ original "Function tools with reasoning_effort are not supported" text.
120
+ Now DEBUG; recoveries log their own WARNING and real failures log ERROR.
121
+
122
+ ## [3.4.1] - 2026-09-18
123
+
124
+ Tool calls on OpenAI models that require the Responses API.
125
+
126
+ ### Fixed
127
+
128
+ - **Tool calls failed on models that need the Responses API.** Some
129
+ OpenAI models (e.g. `gpt-6-astra`) reject function tools combined with
130
+ reasoning on `/v1/chat/completions`, and the error's suggested fix --
131
+ `reasoning_effort='none'` -- is itself rejected by those models, so
132
+ 3.4.0's parameter adaptation had nowhere to go. `GPT` now switches a
133
+ model's tool calls to `/v1/responses` when the provider says to,
134
+ retries, and remembers it (WARNING-logged). History is translated only
135
+ at the wire (`function_call` / `function_call_output` items paired by
136
+ `call_id`), so agents, `tool_calls`, and completions are unchanged.
137
+ Learned parameter fixes carry across endpoints (`reasoning.effort` maps
138
+ to `reasoning_effort`). Requests are sent with `store=False`, matching
139
+ chat completions. Plain text calls and streaming stay on chat
140
+ completions.
141
+ - Requests chat completions can't express (a document URL) go to the
142
+ Responses API, which accepts `file_url`, instead of raising.
143
+
144
+ ### Added
145
+
146
+ - `GPT(use_responses_api=None | True | False)`: automatic (default),
147
+ always, or never.
148
+
149
+ ## [3.4.0] - 2026-09-18
150
+
151
+ Media input for GPT and Claude, models that adapt to each generation's
152
+ parameter support, and workspace-rooted paths. Non-breaking; two
153
+ defaults changed -- see docs/guides/upgrading.md.
154
+
155
+ ### Added
156
+
157
+ - **Media input for GPT and Claude.** New `Media` type
158
+ (`Media.image()`, `.document()`, `.audio()`, `.from_path()`,
159
+ `.from_url()`, `.from_bytes()`) and a `media=[...]` argument on
160
+ `AgentRunner.invoke` / `stream` and `AsyncAgentRunner.ainvoke` /
161
+ `astream`. Items can be paths, URLs, `Media`, or content-part dicts
162
+ in either provider's native shape; each model renders them in its
163
+ own wire format (OpenAI `image_url` / `file` / `input_audio`,
164
+ Anthropic `image` / `document`). Unsupported combinations -- audio to
165
+ Claude, a document URL to GPT -- raise `ValueError` before any
166
+ request. Media is stored as plain JSON dicts, so `completion.history`
167
+ and `Session.save()` keep working. Guide: docs/guides/media.md.
168
+
169
+ - **Models adapt to per-generation parameter support.** `GPT` and
170
+ `Claude` read a parameter-compatibility 400 (which names the
171
+ parameter and, for enums, the allowed values), make the smallest
172
+ change it asks for, retry, and remember it per model: an unsupported
173
+ `reasoning_effort` moves to the nearest supported value, `max_tokens`
174
+ becomes `max_completion_tokens` on reasoning models (up front for
175
+ known families), parameters a model lacks are dropped, and Claude's
176
+ `max_tokens` is clamped to the model's cap. Logged at WARNING; other
177
+ 400s raise unchanged. `adapt_params=False` opts out.
178
+
179
+ - **`Claude` gains `top_p`, `top_k`, `thinking`, `stop_sequences`.**
180
+
181
+ ### Changed
182
+
183
+ - `Claude(temperature=)` defaults to `None` (not sent; the API default is
184
+ the old 1.0). Always sending it conflicted with `top_p` on newer models
185
+ and with extended thinking.
186
+ - `GPT(reasoning_effort=)` accepts any string, not just
187
+ `none | low | medium | high`, so `minimal` and `xhigh` are expressible.
188
+
189
+ ### Fixed
190
+
191
+ - **`reasoning_effort="none"` crashed on models that don't take it**
192
+ ("Unsupported value: 'reasoning_effort' does not support 'none' with
193
+ this model"). The models docs even recommended `"none"` as a fix for
194
+ tool-calling conflicts; that advice is gone.
195
+ - **Workspace-rooted paths resolved to the drive root.** With a workspace
196
+ set, `/bruce.jpeg` became `C:\bruce.jpeg` on Windows (a leading slash
197
+ with no drive means the current drive's root) and the sandbox rejected
198
+ it. A leading slash now means the workspace root; the re-rooted path
199
+ is still sandbox-checked, so traversal is rejected as before.
200
+ - **`run_python` ran in the host process's directory, not the
201
+ workspace.** It passed no `cwd`, so `open("bruce.jpeg")` looked
202
+ wherever the program was launched from. It now starts in the workspace,
203
+ matching `run_shell`.
204
+ - **Message-list input stringified media into the prompt.** A user turn
205
+ whose content was a list (text + image) went through `str()`, so an
206
+ attached image reached the model as base64 text. Text and media are
207
+ now split, and earlier turns keep their list content.
208
+ - **Claude returned the wrong block with extended thinking.** It read
209
+ `response.content[0].text`; with thinking the first block is a
210
+ `thinking` block. Text blocks are now joined.
211
+ - `GPT.Initialize` / `stream_text` / `astream_text` now run messages
212
+ through the same OpenAI translator as `call_with_tools`.
213
+
214
+ ## [3.3.1] - 2026-09-09
215
+
216
+ Correctness fixes in the agent loop, found by driving it with a
217
+ scripted model rather than reading it. No API changes; every fix
218
+ replaces a silent wrong answer or a runaway cost with correct
219
+ behaviour. Nine regression tests ship with them
220
+ (`tests/test_agent_loop_flaws.py`).
221
+
222
+ ### Fixed
223
+
224
+ - **Native binding had no loop-level spiral guard.** The repeat breaker
225
+ sat after the native branch's `continue`, so `bind_tools_natively`
226
+ runs never reached it: a model stuck re-issuing one call burned the
227
+ full `max_iterations` (20 LLM turns where text mode stopped at 3) and
228
+ returned the "hit max_iterations" recap quoting the dup-guard's own
229
+ warning text instead of the data.
230
+
231
+ - **`respond` batched with real tool calls dropped them.** A model that
232
+ emitted "do X, and here is my answer" in one turn had X silently
233
+ discarded -- never dispatched, never in `completion.tool_calls`, no
234
+ error. The batch now runs and the answer defers one turn.
235
+
236
+ - **`completion.history` could not be replayed as `chat_history`.** The
237
+ copy filter kept only truthy `{role, content}`, which dropped every
238
+ tool-calling assistant turn (`content=""`), stripped `tool_call_id`
239
+ off `role="tool"` messages, and replayed a stored system prompt on top
240
+ of the fresh one -- so a follow-up call sent two system messages, zero
241
+ assistant turns, and an orphaned tool message providers reject. Fixed
242
+ in both runners.
243
+
244
+ - **A sync `AgentRunner` silently ignored async tools.** `known_tools`
245
+ unioned only the two sync registry tables while the registry accepted,
246
+ listed and prompt-advertised async ones, so calling one fell through
247
+ to implicit-final and returned `action_input` as the answer with an
248
+ empty `tool_calls` list. Now unions all four, matching the async
249
+ runner; the sync dispatcher already returns a clear `ToolError`, so
250
+ the silent wrong answer became an actionable one.
251
+
252
+ - **`AsyncAgentRunner` regressed the function-calling message shape.**
253
+ It appended its FC turn as raw JSON text with no `tool_calls` block
254
+ and never set `_last_function_call_id`, so observations went back as
255
+ `role="user"` -- text-mode shape while in FC mode, losing provider
256
+ correlation and the cached prefix.
257
+
258
+ - **A `BaseException` from a specialist orphaned its siblings.**
259
+ `CancelledError` and `KeyboardInterrupt` are not `Exception`, so
260
+ `_run_subtask`'s handler never saw them; `t.result()` re-raised and
261
+ left sibling tasks running unowned, with in-flight LLM calls still
262
+ billing. The scheduler now owns its tasks in a `try`/`finally`, which
263
+ also covers a consumer that stops iterating `astream` early.
264
+
265
+ - **The tool cache collided on tool name.** It is a process-wide
266
+ singleton keyed on `(tool_name, args)` with no record of which
267
+ implementation ran, so two runners whose tools merely share a name --
268
+ `search`, `fetch`, `query`, routine across Supervisor specialists --
269
+ served each other's results and the second function never ran. Keys
270
+ now fold in the callable's `module.qualname`, so same-name /
271
+ different-implementation misses while genuinely identical tools still
272
+ share, including across processes for the disk-backed `FileCache`.
273
+
274
+ ### Docs
275
+
276
+ - Streaming documentation described parameters the API rejects.
277
+ `AsyncAgentRunner.astream()` and `HandoffCoordinator.stream()` take no
278
+ `stream_tokens` (only the sync `AgentRunner.stream()` does), and every
279
+ `text_delta` example was built on a default model where
280
+ `use_function_calling` auto-detects to `True` and yields zero deltas.
281
+ `simple_stream` was documented with the wrong signature entirely.
282
+ Added a table naming exactly which stream methods accept what.
283
+
284
+ ### Tests
285
+
286
+ - Repaired 20 stale text-mode tests. `MockModel` defined
287
+ `call_with_tools` unconditionally, so 3.1.7's auto-detect routed every
288
+ text script down the function-calling path and the runner returned
289
+ `""`. The mock now advertises the capability only when scripted for
290
+ it. Suite: 206 passed, 3 skipped.
291
+
292
+ ## [3.3.0] - 2026-08-19
293
+
294
+ Dependency DAGs for the Supervisor. Plans declare which steps consume
295
+ which, and the executor derives ordering, parallelism, AND context
296
+ routing from those edges — unifying the old split where sequential
297
+ mode had threading but no parallelism and concurrent mode had
298
+ parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
299
+
300
+ ### Added
301
+
302
+ - **`depends_on` plan steps.** Every plan step now carries an `id`;
303
+ a step that consumes an earlier step's output lists that id in
304
+ `depends_on`. Sync `Supervisor` executes in stable topological
305
+ order; `AsyncSupervisor` runs a completion-driven scheduler where a
306
+ step starts the MOMENT its dependencies finish (not on wave
307
+ barriers) and independent steps run concurrently. In DAG mode each
308
+ step is threaded ONLY its direct dependencies' results — explicit
309
+ routing instead of "everything prior", which also stops the
310
+ per-entry context budget shrinking as plans grow.
311
+
312
+ - **Plan sanitization that never fails a run.** Missing/duplicate ids
313
+ auto-assigned, unknown dependencies dropped (a planner typo degrades
314
+ to a root step, not a dead run), self-deps dropped, cycles broken
315
+ deterministically (back-edge in plan order), spawn steps cannot be
316
+ depended on. If repairs were needed, the plan is re-requested once
317
+ (`max_plan_retries`, default 1) with the repair warnings appended;
318
+ the sanitized original is kept when the retry is no better.
319
+
320
+ - **Failure cascade + `skipped` flag.** A step whose dependency failed
321
+ (after retries / success-check) is skipped, transitively, with
322
+ `SubtaskResult.skipped=True` and an error naming the failed dep.
323
+ Independent branches keep running; synthesis runs over what
324
+ succeeded. Skipped steps never dispatch — no tokens burned
325
+ downstream of garbage.
326
+
327
+ - **`skip_when` conditional execution.** A step may declare
328
+ `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
329
+ evaluated in Python (no LLM call) against the dependency's 3.2
330
+ structured output, dotted paths supported, strictly FAIL-OPEN (any
331
+ doubt → the step runs). Condition-skips do NOT cascade — dependents
332
+ treat them as empty successes ("retrieval unnecessary" is not
333
+ "answering impossible").
334
+
335
+ - **`Specialist` registry entries.** `agents={}` now also accepts
336
+ `Specialist(description, runner, depends_on=[...names...],
337
+ output_schema=..., when_to_use=...)`. The extras render into the
338
+ planning catalog (`typically after:` / `returns: Schema(fields)` /
339
+ `use when:`) so the planner can write real dependency graphs and
340
+ `skip_when` conditions against actual field names. `depends_on`
341
+ here is a planner HINT, never an execution constraint (the same
342
+ specialist can appear twice in one plan; step-ids disambiguate).
343
+ Classic `(description, runner)` tuples keep working — they are
344
+ wrapped internally, and `Specialist` tuple-unpacks for older code.
345
+
346
+ - **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
347
+ rate-limited deployments. `sequential=True` is now sugar for
348
+ `max_parallel=1` with all-prior threading.
349
+
350
+ - **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
351
+ `step_id` field on `dispatch` / `subtask_result` stream events.
352
+
353
+ ### Backward compatibility
354
+
355
+ A plan where NO step declares `depends_on` runs with byte-identical
356
+ legacy semantics: sync + async-sequential thread all prior results in
357
+ plan order; async-concurrent runs everything at once with no
358
+ threading. Verified by regression tests against the 3.2 behaviour.
359
+
360
+ ## [3.2.0] - 2026-08-13
361
+
362
+ Typed multi-agent pipelines. Specialists can now declare a Pydantic
363
+ output schema once and pass validated instances to each other through
364
+ the Supervisor, instead of downstream agents re-parsing prose.
365
+
366
+ ### Added
367
+
368
+ - **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
369
+ constructor.** Declare the runner's output shape once
370
+ (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
371
+ on every call or describing JSON in the prompt. A per-call
372
+ `output_schema=` still wins when both are set. `None` keeps the exact
373
+ pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
374
+
375
+ - **Schema coercion via forced native function calling.** When a schema
376
+ is in play, the final answer is converted by forcing a provider-native
377
+ tool call against the schema (constrained decoding), not by regexing
378
+ JSON out of prose. The ReAct loop itself is untouched: tool selection
379
+ and intermediate reasoning run exactly as before, and the coercion
380
+ happens once, after the loop finishes. Models without a
381
+ `call_with_tools` implementation fall back to the previous text-JSON
382
+ parsing, so custom `BaseChatModel` subclasses keep working.
383
+ `completion.content` keeps the human-readable answer alongside
384
+ `completion.output` in every case.
385
+
386
+ - **`SubtaskResult.output`.** The Supervisor now preserves each
387
+ specialist's validated Pydantic instance next to its `content` text.
388
+ Consumers that only read `content` are unaffected.
389
+
390
+ - **Structured specialist-to-specialist handoff.** When an earlier step
391
+ produced typed output, `_build_augmented_query` serializes it into the
392
+ next specialist's context as a labelled JSON block
393
+ (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
394
+ text, so downstream steps parse fields rather than interpreting
395
+ sentences like `INTENT: ... SEARCH_QUERY: ...`.
396
+
397
+ - **`vector_search_tool` pipeline options.** New kwargs:
398
+ `max_text_chars` (default 500; pass `0` for full untruncated passages,
399
+ which a reranker judging evidence actually needs) and
400
+ `structured_output` (default False; when True the tool returns a JSON
401
+ array of `{id, text, vector_score, metadata}` instead of the
402
+ human-formatted list). Defaults preserve existing behaviour byte-for-
403
+ byte.
404
+
405
+ ### Fixed
406
+
407
+ - **Supervisor planning prompt contradicted the execution engine.** The
408
+ planner rule said sub-agents "do NOT see previous steps' output" and
409
+ discouraged dependency chains, but the dispatcher has threaded prior
410
+ findings into every step since `_build_augmented_query` shipped.
411
+ The rule now tells the planner that sequential steps receive earlier
412
+ results (structured when available) and that chains like
413
+ intent -> retrieval -> reranking are a good plan shape, while still
414
+ requiring same-specialist steps to merge and banning report-only steps.
415
+
416
+ ## [3.1.7] — 2026-07-27
417
+
418
+ ### Changed
419
+
420
+ - **`use_function_calling` default flipped to auto-detect** on
421
+ `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
422
+ now `Optional[bool] = None`; `None` resolves to `True` when the
423
+ model class overrides `BaseChatModel.call_with_tools` (both `GPT`
424
+ and `Claude` do) and to `False` when it doesn't (or when
425
+ `bind_tools_natively=True`). Callers passing `True`/`False`
426
+ explicitly are unaffected. Rationale: text-mode ReAct requires the
427
+ model to emit strict JSON with any long `action_input` string
428
+ properly escaped — a 1200-word markdown draft with unescaped
429
+ newlines or quotes reliably breaks `json.loads` and killed the run.
430
+ Function-calling mode routes the parser through the SDK's typed
431
+ channel so escaping is handled automatically. The historical
432
+ default (`False`) was the fragile option; the new default matches
433
+ what most users actually want.
434
+
435
+ ### Fixed
436
+
437
+ - **Malformed parser JSON no longer crashes the run.** When the
438
+ text-mode assistant response failed `json.loads` (typically because
439
+ a long `action_input` string had unescaped `"`, `\n`, or backticks),
440
+ the framework used to raise `JSONDecodeError` and unwind the whole
441
+ invocation. The runner now (1) tries a regex-based salvage that
442
+ extracts `{Thought, action, action_input}` from the raw text
443
+ covering the common "outer envelope valid, inner string broke
444
+ escaping" failure, and (2) if salvage fails, feeds a targeted fix
445
+ hint back to the model (`"your last response was not valid JSON;
446
+ emit …, escape newlines as \n"`) and continues the loop bounded
447
+ by `max_iterations`. Exhaustion returns a clear framework message
448
+ rather than an uncaught exception. Applied to both sync and async
449
+ runners via a shared `_salvage_react_json` helper.
450
+ The salvager's action-name regex is intentionally strict
451
+ (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
452
+ "action" out of an unrelated `"key":"value"` pair inside malformed
453
+ JSON.
454
+
455
+ - **Verbose trace in `bind_tools_natively` mode now prints tool
456
+ name + args + response.** Previously native runs showed blank
457
+ `[tool.call.start]` / `[tool.call.complete]` pairs (the
458
+ observability layer fires them without the trace context), so you
459
+ couldn't tell which tool the model actually invoked or what came
460
+ back. The runner now prints `[tool] Invoking '<name>' with args:
461
+ <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
462
+ when the dispatch raised) in the post-dispatch loop, matching the
463
+ format text-mode and function-calling mode use. Mirrored to the
464
+ async runner.
465
+
466
+ - **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
467
+ a vector store** instead of dumping raw HTML into the model's
468
+ context. Fixes the TPM-limit trap: when a research agent fetches
469
+ four articles in parallel (via ``multi_tool_use.parallel`` or
470
+ native binding), the combined bodies can easily exceed 40k tokens
471
+ and blow past a 30k TPM ceiling on the very next model call.
472
+ New parameters on ``web_fetch_tool``:
473
+
474
+ | Kwarg | Default | Effect |
475
+ |---|---|---|
476
+ | ``vector_store`` | ``None`` | When set, each fetch is HTML-stripped, chunked with ``TextSplitter``, embedded via the store's embeddings, and added with ``{src: url, chunk_index, total_chunks}`` metadata. The tool response becomes a compact summary (URL, byte count, chunk count, 240-char preview) — NOT the raw body. The model then calls ``vector_search`` / ``Rag`` to pull only the passages it needs. |
477
+ | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
478
+ | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
479
+
480
+ Backwards-compatible: the positional ``cache_dir`` signature keeps
481
+ working; `web_fetch_tool()` with no ``vector_store`` returns raw
482
+ body as before. Ingest and cache_dir compose — enable both and get
483
+ disk-cached full bodies AND searchable chunks. HTML stripping is
484
+ minimal and dependency-free (regex-based: script/style blocks
485
+ dropped whole, then tags stripped, whitespace collapsed) so the
486
+ ingest path adds no new install dependency. On JSON/plain-text
487
+ responses the stripper is a near no-op.
488
+
489
+ The observation returned to the model shows topical coverage --
490
+ first, middle, and last chunk previews (up to 3 samples,
491
+ deduplicated for short pages) -- so the model can tell what
492
+ topics the page actually covers, not just the intro paragraph.
493
+ Without this the model would only see the page's opening and
494
+ wouldn't know to query for topics discussed later in the same
495
+ page. Explicit instruction in the observation ("query with
496
+ SPECIFIC keywords from the topics above; do NOT re-fetch; do
497
+ NOT ask for the full body") steers the model toward the RAG path
498
+ on follow-up turns.
499
+
500
+ - **`multi_tool_use.parallel` now reaches its dispatch path.**
501
+ When GPT wanted to batch several tool calls into one turn (fetch N
502
+ URLs concurrently, run M searches at once), it emitted OpenAI's
503
+ synthetic `multi_tool_use.parallel` meta-tool. The registry's
504
+ `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
505
+ already knew how to unpack it, but the runner loop's known-tools
506
+ guardrail rejected the name FIRST as unregistered — dumping the
507
+ raw `{"tool_uses": [...]}` payload into the user-facing "final
508
+ answer" and never invoking any of the nested calls. Added
509
+ `multi_tool_use.parallel` to the recognized action set in both
510
+ sync and async runners so the meta-tool flows through to dispatch
511
+ and the existing unpackers run. Nested calls with the `functions.`
512
+ prefix are normalized before dispatch (same as top-level FC
513
+ calls), so the model can emit either shape.
514
+
515
+ - **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
516
+ Passing `full_access("./workspace")` used to iterate the string
517
+ into 11 single-character "subtrees" (Python's `list("./workspace")`)
518
+ — every path check silently rejected because no real path could
519
+ ever match a `"."` or `"/"` "allowed subtree". The classmethod
520
+ now detects a bare string and treats it as `[allowed_paths]`, so
521
+ `full_access("./workspace")` does the intuitive thing (equivalent
522
+ to `full_access(["./workspace"])` and auto-infers the workspace).
523
+ Same fix on `read_only`. List inputs are unchanged.
524
+
525
+ - **`Permissions.full_access` now accepts (and auto-infers)
526
+ `workspace`.** The classmethod set `allowed_paths` but not
527
+ `workspace`, so short paths like `write_file(path="report.md")`
528
+ resolved to CWD (outside the sandbox) and raised
529
+ `PermissionError: access denied` — a landmine that every caller of
530
+ `Permissions.full_access(["./workspace"])` hit sooner or later.
531
+ New signature: `full_access(allowed_paths, *, workspace=None)`.
532
+ When `workspace` isn't passed AND `allowed_paths` has exactly one
533
+ entry, that path is auto-set as the workspace (the "project-scoped
534
+ agent whose one allowed subtree IS its workspace" case, which is
535
+ 99% of use). Two or more paths stay ambiguous and require an
536
+ explicit `workspace=` if short-path resolution is wanted. Pass an
537
+ explicit `workspace=` string to override the auto-choice.
538
+ Backwards-compatible on the positional signature; adds a keyword
539
+ argument that existing callers didn't use.
540
+
541
+ ## [3.1.5] — 2026-07-26
542
+
543
+ ### Fixed
544
+
545
+ - **Text-mode tool results no longer use `role: "function"`.** In text
546
+ mode (the default — no `use_function_calling`) the runner fed each tool
547
+ observation back to the model as a `role: "function"` message. Newer
548
+ OpenAI models reject that role outright (`400 … 'messages[N].role' does
549
+ not support 'function' with this model`, e.g. gpt-5.x), and Anthropic
550
+ never accepted it — text-mode multi-tool runs on Claude were latently
551
+ broken too; older GPT models simply still tolerated the legacy role.
552
+ Tool observations now go back as a plain `role: "user"` turn framed as
553
+ `Observation: …`, which every provider and model generation accepts and
554
+ which matches the ReAct template's own few-shot convention.
555
+ Function-calling mode is unchanged (native `role: "tool"` +
556
+ `tool_call_id`). The async runner was additionally emitting `function`
557
+ unconditionally (even in FC mode); it now uses the same shared helper.
558
+
559
+ ### Added
560
+
561
+ - **`subtask_success_check` on `Supervisor` / `AsyncSupervisor`.** Opt-in
562
+ predicate `(SubtaskResult) -> bool | str` that decides whether a
563
+ *returned* (non-raised) sub-task result is actually acceptable — the
564
+ "ran fine but produced nothing useful" case a plain retry can't catch
565
+ (a scraper that saved 0 links, an extractor that found nothing). Return
566
+ `True` to accept, or `False`/a `str` reason to reject; a rejected
567
+ result is retried like a raised error, with the reason fed back into the
568
+ query, bounded by `max_subtask_retries`. After retries are exhausted the
569
+ last result is returned with its `error` set (content preserved). A
570
+ check that itself raises is treated as "accept" so a buggy predicate
571
+ can't wedge the run. Default `None` keeps the exceptions-only behavior.
572
+ New example `examples/robust_link_scraper.py` wires it together with a
573
+ scraping `system_addendum` (parse relative+absolute hrefs, fall back to
574
+ `sitemap.xml` on JS-rendered sites).
575
+
576
+ ## [3.1.4] — 2026-07-26
577
+
578
+ ### Fixed
579
+
580
+ - **A malformed-JSON tool argument no longer crashes the whole agent
581
+ run.** When a model emitted a Python snippet or a Windows path as a
582
+ tool-call argument — `re.findall(r'\d+')`, `C:\Users` — the `\d` / `\U`
583
+ are illegal JSON escapes, and the OpenAI adapter's eager
584
+ `json.loads(call.function.arguments)` raised `JSONDecodeError` and
585
+ `raise`d it, unwinding the entire ReAct loop before the agent's own
586
+ retry machinery could act. Under a Supervisor this surfaced as a bare
587
+ `ERROR: Invalid \escape: line 1 column 598` and the sub-task was
588
+ abandoned. Now:
589
+ - `_parse_tool_arguments` repairs the common case (backslashes that
590
+ don't begin a valid JSON escape are doubled), recovering `\d`,
591
+ `\w`, `\s`, etc. with zero extra round-trips. A backslash before a
592
+ valid-escape letter (`\b`, `\n`, …) remains ambiguous and is left
593
+ as the escape — a documented limit.
594
+ - When repair fails, `call_with_tools` returns a dedicated
595
+ `invalid_tool_args` result and the loop feeds the error back as a
596
+ retryable observation ("your arguments weren't valid JSON — escape
597
+ backslashes and resend"), bounded by `max_iterations`, in all
598
+ three modes across both `AgentRunner` and `AsyncAgentRunner`.
599
+ `Claude` was already immune (its tool inputs arrive pre-parsed).
600
+
601
+ - **A tool-call preamble is no longer returned as the final answer.**
602
+ Models routinely end a turn with an announcement instead of an action
603
+ — "I'll look up your recent scores to get a clear view of your
604
+ communication skills. Just a second!" — and every "no tool call
605
+ found" branch in both runners was coded as *this text is the answer,
606
+ break*. The loop terminated on iteration 1 and the caller got a
607
+ promise instead of a result. Three sites per runner were affected:
608
+ the native-binding path (`type != "tool_use"`), the
609
+ `use_function_calling` path (parser unresolved), and the JSON-text
610
+ path (response didn't parse). `max_iterations` never helped, because
611
+ the break happened before any iteration was spent.
612
+
613
+ The runner now feeds the model one corrective nudge — "your last turn
614
+ had no action, so nothing happened; do it, don't announce it" — and
615
+ continues the loop. Verified against both `AgentRunner` and
616
+ `AsyncAgentRunner` in all three modes.
617
+
618
+ ### Added
619
+
620
+ - **Proactive "act, don't announce" system-prompt clause.** The reactive
621
+ `text_turn_nudges` fix corrects an agent *after* it narrates instead of
622
+ acting; this clause heads it off. When (and only when) an agent has
623
+ tools, its system prompt now tells it to call the tool rather than
624
+ reply "I'll do X / just a second" and stop — and to report what it DID
625
+ in past tense. Injected in all three modes across both runners; skipped
626
+ for tool-less chat agents, where prose is the correct answer. Sits
627
+ before any `system_addendum` so a caller's role instructions still win.
628
+
629
+ - **`max_subtask_retries` on `Supervisor` / `AsyncSupervisor`** (default
630
+ `1`). A sub-task that raised used to be recorded as an error and the
631
+ Supervisor moved straight to synthesis — no second attempt. Now a
632
+ failed sub-task is re-dispatched up to this many times, with the prior
633
+ error appended to the query so the specialist knows what to fix
634
+ ("your previous attempt failed with X — diagnose and try again").
635
+ Bounded and informed: only raised exceptions trigger a retry (a
636
+ sub-task that returns content is accepted as-is, since the Supervisor
637
+ can't tell "terse but correct" from "wrong"), and the error text is
638
+ fed back rather than blindly re-running. Set to `0` for the old
639
+ quit-on-first-failure behavior. Applies in both sequential and
640
+ concurrent async modes.
641
+
642
+ - **`text_turn_nudges` on `AgentRunner` / `AsyncAgentRunner`** (default
643
+ `1`). Caps the re-prompts described above at one extra LLM call per
644
+ run; after the budget is spent the model's text stands as the answer.
645
+ Set to `0` for the previous behavior. Automatically skipped when no
646
+ tools are registered, since a runner with no tools is a plain chat
647
+ call and prose genuinely is the answer there.
648
+
649
+ ## [3.1.3] — 2026-07-22
650
+
651
+ Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
652
+ need to upgrade for functionality; upgrade to pick up the improved
653
+ onboarding docs bundled in the sdist.
654
+
655
+ ### Documentation
656
+
657
+ - **Tools doc rewritten to answer "how do I actually use these?"**
658
+ Added §0 `How each built-in tool is registered` as the entry
659
+ section. Two registration paths — auto vs manual — laid out in a
660
+ table on the first screen. Six runnable subsections covering every
661
+ combination:
662
+ - §0.1 DefaultTools via `Permissions(...)` (auto)
663
+ - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
664
+ - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
665
+ `vector_search_tool(store)`
666
+ - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
667
+ - §0.5 Custom `StructuredTool` from scratch
668
+ - §0.6 Fully-loaded runner combining all of the above
669
+ - §0.7 Rules on name collisions, invisible-denied-capabilities,
670
+ async-tool behavior
671
+ The existing inventory + wrapper / controls / cheat-sheet sections
672
+ are unchanged; they now sit after the "how to use them" primer
673
+ instead of before it.
674
+
675
+ ## [3.1.2] — 2026-07-22
676
+
677
+ Patch release. Two independent fixes.
678
+
679
+ ### Fixed
680
+
681
+ - **`llm_judge` correctly parses YES/NO across providers.** The judge
682
+ parser was comparing the reply's first word to the literal string
683
+ `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
684
+ equality check and marked every genuine PASS as FAIL. Claude replies
685
+ `"YES"` without punctuation so the bug hid during local development.
686
+ Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
687
+ insensitive) at the start of the reply. Handles every real shape:
688
+ `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
689
+ Ambiguous replies (`Maybe`, empty string) still fail closed.
690
+ - Regression test `test_llm_judge_parses_various_verdict_shapes`
691
+ covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
692
+
693
+ ### Added
694
+
695
+ - **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
696
+ longer need to remember which module each tool lives in:
697
+
698
+ ```python
699
+ from agentx_dev.Tools import (
700
+ StandardTool, StructuredTool,
701
+ AsyncStandardTool, AsyncStructuredTool,
702
+ web_search_tool, web_fetch_tool,
703
+ vector_search_tool, handoff_tool,
704
+ DefaultTools, Permissions,
705
+ )
706
+ ```
707
+
708
+ Both this form and the pre-existing `from agentx_dev import X`
709
+ form coexist. Implementation uses PEP 562 module `__getattr__`
710
+ and `__dir__` so re-exports are lazy (no import cost for modules
711
+ the caller doesn't touch) and show up in IDE autocomplete +
712
+ `dir(agentx_dev.Tools)`.
713
+
714
+ ## [3.1.1] — 2026-07-21
715
+
716
+ Second batch of 3.1 features + a full docs + brand pass.
717
+
718
+ ### Added
719
+
720
+ **Streaming through orchestration**
721
+ - `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
722
+ `plan_start` / `plan` / `dispatch` / `subtask_result` /
723
+ `synthesize_start` / `final` / `completion` events.
724
+ - `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
725
+ `completion` / `handoff` / `final` / `result` events per hop.
726
+ - Legacy `.run()` / `.arun()` refactored to consume the streams (no
727
+ code duplication).
728
+
729
+ **Prompt optimization — `Compiled`**
730
+ - New `agentx_dev.Compiler` module.
731
+ - `Compiled(runner_factory, trainset, ...)` iteratively refines a
732
+ runner's `system_addendum` against the eval harness. Half of
733
+ DSPy's power at a tenth of the surface.
734
+
735
+ **Anthropic Batch API**
736
+ - `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
737
+ batch rate, polls to completion, returns results in submission order.
738
+ - Per-request error dicts on failure; token usage funneled into
739
+ `TokenUsage` so cost tracking stays a single source of truth.
740
+
741
+ **Vector store adapters — `agentx_dev.VectorStores`**
742
+ - `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
743
+ public shape as the in-memory `VectorStore` (`add` / `search` /
744
+ `delete` / `clear` / `__len__` / `embeddings`).
745
+ - `vector_search_tool()` and `SemanticMemory` accept any of them.
746
+ - SDK imports lazy; friendly `ImportError` when the underlying SDK
747
+ is missing.
748
+
749
+ **Trace viewer (`viewer/`)**
750
+ - Self-hosted single-page app that reads `FileHook` JSONL and renders
751
+ a timeline with type/text filters, summary sidebar, JSON drill-down.
752
+ - Works from `file://`, no server required.
753
+
754
+ **Docs site (`host/`)**
755
+ - Full editorial dark-first design system (JetBrains Mono headings,
756
+ Inter body, `#B8FF3E` electric-lime accent).
757
+ - Command palette (`Cmd+K`) with keyboard navigation and live search.
758
+ - Hero code snippet with hand-tinted syntax highlighting.
759
+ - Reading progress bar, breadcrumbs, header anchor links.
760
+ - Sidebar sliding active marker, collapsible groups.
761
+ - Code copy buttons, language labels.
762
+ - Right-rail auto-TOC with `IntersectionObserver` scrollspy.
763
+ - Dark/light theme toggle, persisted.
764
+ - Cache-busted assets so edits land on refresh without hard-reload.
765
+
766
+ **Brand identity (`brand/`)**
767
+ - Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
768
+ `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
769
+ - Copy audit dropped "small" (weak) and "LangChain" references from
770
+ all marketing surfaces.
771
+ - Favicon wired into docs + trace viewer.
772
+
773
+ **Test suite (`tests/`)**
774
+ - Restored + expanded pytest suite: 127 tests passing (3 skipped for
775
+ absent optional SDKs).
776
+ - Coverage: parser + all `AgentType` variants, `ToolRegistry`
777
+ (dispatch / dup-guard / circuit-breaker / timeout), Permissions
778
+ (capability gating + sandbox + traversal), budgets (cost / rate /
779
+ retry / non-retryable HTTP), runner loop (streaming + output_schema
780
+ + chat history), embeddings + `VectorStore` + `SemanticMemory`,
781
+ handoffs (bounded hops + history sanitization), evals harness
782
+ (all assertion helpers + JSON case loaders), vector-store adapter
783
+ shape conformance.
784
+
785
+ **Docs (`docs/`)**
786
+ - Full docs tree (34 pages), including new pages for:
787
+ vector store adapters, prompt optimization, batch API, trace viewer,
788
+ and a **use-cases** landing (13 concrete scenarios with runnable code).
789
+ - Rewrote **Tools** page to enumerate every built-in tool with args,
790
+ return shape, capability flag, and use-case guidance.
791
+ - Rewrote **Agents** page to cover all four orchestration
792
+ architectures (Solo / Supervisor / Handoffs / Compiled) with
793
+ decision trees, worked examples, and cheat sheet.
794
+ - **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
795
+ parallel retrieval, self-critique, citations, user memory.
796
+
797
+ **Examples**
798
+ - `examples/agentic_rag_demo.py` — the runnable version of the
799
+ agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
800
+ runs a 3-turn scripted session proving user-notes recall works.
801
+
802
+ **Package**
803
+ - `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
804
+ - `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
805
+
806
+ ### Fixed
807
+
808
+ - `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
809
+ minimal system prompt instead of the AgentType template so the
810
+ ReAct `action/action_input` scaffold no longer fights the native
811
+ tool interface. Previously produced JSON-blob answers under GPT.
812
+ - `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
813
+ and function role messages between hops so tool_call_ids from a
814
+ previous agent don't leak into the next model's call (OpenAI 400).
815
+ - Docs site marker positioning uses double-`requestAnimationFrame` +
816
+ `document.fonts.ready` so the sidebar accent bar lands on the
817
+ correct row even on a cold font cache.
818
+ - Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
819
+ outrank `#doc a` link styling (previously rendered lime-on-lime
820
+ and was invisible).
821
+
822
+ ### Notes
823
+
824
+ - Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
825
+ did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
826
+ and includes both batches of features.
827
+
828
+ ## [3.1.0] — internal only (commits 52840e7)
829
+
830
+ First batch of 3.1 features. Committed but not released to PyPI.
831
+ Merged into 3.1.1 for the public release.
832
+
833
+ ### Added
834
+ - Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
835
+ - Parallel per-turn tool dispatch in `AgentRunner`
836
+ (`bind_tools_natively=True`, `parallel_tool_workers`).
837
+ - Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
838
+ - RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
839
+ `VectorStore`, `VectorHit`, `vector_search_tool()`).
840
+ - Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
841
+ `HandoffCoordinator`, `HandoffResult`).
842
+ - Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
843
+ helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
844
+ - `TokenUsage.cache_hit_ratio` property.
845
+
846
+ ## [3.0.6] — 2026-03 (baseline)
847
+
848
+ Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
849
+ persistent state, scrubbed subprocess env, path sanitizer,
850
+ `permissions.json` mode 0o600, ReDoS guard on `grep`,
851
+ `invoke`/`ainvoke` accept bare strings and message lists).