Repository navigation
v2.16.0
Read before upgrading
AgentConfig.modelnow defaults togpt-5.6-terra. The old default,gpt-5-mini, is on OpenAI's deprecation list with a shutdown date of 2026-12-11. If you never setmodel, your agents switch models with this upgrade. Setmodelexplicitly to stay on a specific one. (#355)AgentConfigtakes itsmodefrom the Instructor client and warns when an explicitmodedisagrees with the client. (#293)ChatHistory(max_messages=...)only accepts a non-negativeintorNone. Booleans, floats, strings and negative numbers raiseValueError, in the constructor and in a loaded snapshot.load()also rejects a snapshot whosehistoryis not a list or whosecurrent_turn_idis not a string or null, and a snapshot larger than its capacity is trimmed right after loading instead of on the nextadd_message. (#356)- Media on fields declared with
exclude=Trueis no longer sent to the model. (#359) - MCP endpoint URLs keep their query string, and a URL whose path already ends in
/mcpor/sseis used as given. If your server is mounted under a path that ends that way, pass the full endpoint URL. (#364) - Models generated from MCP schemas now enforce the schema's bounds, lengths, patterns and item counts, so a value the server would reject fails locally first. (#363)
- MCP resource URIs are kept exactly as the server sent them, and braces in a plain resource URI are literal instead of becoming URI parameters. (#345)
token:countedhandlers are kept on the agent that registered them. Agents sharing one Instructor client no longer fire each other's token handlers. (#347)
Features
- Opt-in chat message capture for tracing:
TracingConfig(capture_messages=True)orATOMIC_AGENTS_TRACE_CAPTURE_MESSAGES=trueaddsgen_ai.input.messagesandgen_ai.output.messagesto chat attempt spans for OpenAI-compatible chat text, tool calls and tool replies. Off by default.hide_inputsdrops the request attribute andhide_outputsdrops both. An attribute larger thanmax_attribute_lengthis left out whole and its size is recorded asgen_ai.input.messages.original_lengthorgen_ai.output.messages.original_length, so raiseATOMIC_AGENTS_TRACE_MAX_ATTRIBUTE_LENGTHfor agents with long prompts. Tool-call arguments that are not valid JSON are kept as raw text. Streams and non-text media are not captured, and native Responses and Anthropic calls record request text only. (#334) - Three new forge tools:
deed_pagepublishes static files to a public deed.page URL (#330),sofya_searchdoes web and news search with page text per result (#367), andoutcrawl_searchdoes web search with optional page content as Markdown (#339). - The forge calculator honors
safe_modeandallowed_functions: safe mode only evaluates allowlisted operators, math functions and the callables you configure. (#361) - The MiniMax quickstart defaults to M3.1 Flash. (#322)
Fixes
Agents, history and hooks
- Schemas resolve through generic agent subclasses, so a fully specialized subclass gets its own input and output schema. (#328)
disable_hooks()pauses the agent's Instructor callbacks, andenable_hooks()restores them. (#327)- Local image, audio and PDF paths inside tuple fields are restored when a saved history is loaded. (#342)
- Formatted tool calls use the title the JSON Schema advertises. (#358)
MCP
$refresolves by its complete JSON Pointer, so#/definitions/Valueand#/$defs/Valueno longer collide. (#335)- Boolean schemas work as inputs:
trueaccepts anything,falserejects everything. (#357) - Scalar
enumandconstconstraints survive conversion. (#300) - Generic tool results that only carry
structuredContentare returned instead of dropped. (#360) - Discovery stops with an error when a server repeats a pagination cursor, instead of looping. (#344)
- With several resources or prompts from one server, each generated class reports errors and builds results with its own name and output schema. (#346)
Tracing
- Agent runs and tool calls that are already in flight keep the tracing config they started with when
uninstrument()or a secondinstrument()happens in between. (#349)
Forge tools
pdf_reader: a page range like1-999999999999is bounded by the document length before iterating (#336), and streamed downloads are closed on every failure path (#337).youtube_transcript_scraper: duration comes from the Data APIcontentDetailsinstead of the summed transcript segments. (#362)webpage_scraperkeeps Markdown content during whitespace cleanup. (#343)arxiv_searchkeeps legacy archive names when stripping version suffixes. (#365)wikipedia_searchfetches full text for the first available result. (#366)
Assembler
- A failed clone or a failed tool copy cleans up after itself and can be retried, and an existing destination is left alone. (#350)
Examples and docs
- The
youtube-summarizerandyoutube-to-recipeexamples fetch transcripts again. They called ayoutube-transcript-apimethod that the pinned version no longer has. (#433) - Examples, README and guides use
gpt-5.6-terra. (#355) The quickstart no longer references retired Anthropic and Groq model IDs. (#331) - The contributing guide's tool walkthrough matches the current
BaseToolAPI. (#338) - Docs cover generic schema resolution and hook pausing (#329), and warn that log shippers carry Instructor's raw retry-exhaustion record (#326).
Verification
- Core suite on the merged tree: 1362 passed and 11 skipped on Windows, plus two tests that only fail in a local all-packages environment and pass in CI. Every forge tool's tests and the assembler tests were run too. Black and Flake8 are clean.
- Each merged pull request was tested alone on top of main, and its new tests were run against the old source to confirm they fail there.
- The quickstarts and the hooks, multimodal and persistent-memory examples were run unmodified against a live model through an OpenAI-compatible endpoint. One known rough edge showed up on both the old and the new code: when a streamed response comes back empty,
run_streamraises aValidationErrorfor the missing field. - Not run live: the three new vendor tools with a real key, the examples that need SearXNG, Gemini or a YouTube Data API key, and
rag-chatbot.
Full changelog: v2.15.0...v2.16.0