BREAKING CHANGE: rename result -> output

[samuelcolvin]

No description provided.

[hyperlint-ai]

PR Change Summary

Renamed instances of 'result' to 'output' across multiple files to improve clarity and consistency in the API documentation.

• Updated variable names from 'result' to 'output' in code examples and documentation.
• Modified type annotations to reflect the change from 'result_type' to 'output_type'.
• Adjusted print statements to use 'output' instead of 'data' for consistency.

Modified Files

• README.md
• docs/agents.md
• docs/api/agent.md
• docs/api/models/function.md
• docs/api/models/test.md
• docs/api/result.md
• docs/common-tools.md
• docs/dependencies.md
• docs/graph.md
• docs/index.md
• docs/input.md
• docs/logfire.md
• docs/mcp/client.md
• docs/mcp/server.md
• docs/message-history.md
• docs/models.md
• docs/multi-agent-applications.md
• docs/results.md
• docs/testing-evals.md
• docs/tools.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

What is Hyperlint?

Hyperlint is an AI agent that helps you write, edit, and maintain your documentation.

Learn more about the Hyperlint AI reviewer and the checks that we can run on your documentation.

[github-actions]

Docs Preview

commit:	4521735
Preview URL:	https://72fa1fb1-pydantic-ai-previews.pydantic.workers.dev

[samuelcolvin]

@dmontagu please look at this and check if you're happy, it needs more tests and docs, but I think the principle should be clear.

[dmontagu]

I don't love this name, partially because it's kind of wordy, partially because I want a name for a function that you call and use its result as the final output, and I feel like whatever that thing gets called will be difficult to distinguish from this name. In particular, I wanted to use OutputTool for that, but it seems confusing for OutputTool and ToolStructuredOutput to be different things.

I'll try to think of a better name for this ASAP..

[dmontagu]

Actually, I feel like we could just use OutputTool as long as it's compatible with the "structured output" version (basically instantiating a type and using that as the output) and the (python) function calling version (using the value returned by the function as the output). It makes sense, considering that for many/most types you'd use with ToolStructuredOutput, it's basically doing a function call with the model's response, just to the type's initializer instead of an arbitrary callable.

So I'd propose we rename this to OutputTool, and plan to (eventually) support instantiating it with arbitrary callables (not just types)

[dmontagu]

I did the renaming, and tweaked the init signature to be a bit more future-proof (in particular, I've made it keyword-only). I'd be happy to change that in the future, just don't want that to break things when we add support for callables if getting type-checking to work requires some tweaks.

I made the keyword argument's keyword type_, but I'm open to changing it to type or tp or whatever you think makes sense. (output_type seems unfortunate given it's already an OutputTool but could do that too).

[samuelcolvin]

my only concern is that OutputTool feels like a kind of tool not a kind of structured output. It's not obvious what we would call "output using JSON Schema prompt" as an alternative to OutputTool? OutputJSONSchema feels confusing.

Could we call it OutputWithTool, then in future add OutputWithJSONSchema?

See instructor Mode for reference.

[dmontagu]

Isn't it a kind of tool though?

[dmontagu]

Okay thinking about it more, I'd be fine with OutputContent or OutputJson for the case you are describing.

I'd also be okay with ToolOutput and PromptSchemaOutput and StructuredOutput, or some similar slew of names for the different modes.

But I'd rather not include With in the name if at all possible, that just seems unnecessarily verbose.

I have a weak preference for the name starting with Output instead of ending for discoverability, but it's not the end of the world; if it ends with Output though we should maybe put them all in a dedicated module to help with discoverability in that way.

[dmontagu]

I'd also be okay just having a single Output type with different __init__ signatures for the different modes. I see pros and cons to that though; I'm still fine having separate types for the separate modes.

[dmontagu]

okay, I renamed OutputTool to ToolOutput and I think that's good enough for this

[Copilot]

Copilot reviewed 90 out of 90 changed files in this pull request and generated no comments.