Docs: add an example of using RunContext to pass data among tools

[tonyxwz]

I find it a very common pattern in my day job to share large output with another tool (API output, dataset etc). The pattern can be implemented by

1. passing the reference instead of the actual data to the agent context window
2. some prompt to let the LLM know about the output reference.

There is no such examples in the documentation to illustrate this usage so I added one. Hope it will be useful to other users.

The format of the variable reference in the example is inspired by IPython: Out[1].

I am more familiar with using Anthropic models on AWS, so I am actually using Claude 3.7 in my local testing. But the example should work with OpenAI models too.

Checks

• run make
• preview mkdocs locally

Running the Example

examples/pydantic_ai_examples/data_analyst.py:50 load_dataset
    path: 'cornell-movie-review-data/rotten_tomatoes' (str) len=41
    split: 'train' (str) len=5
examples/pydantic_ai_examples/data_analyst.py:64 load_dataset
    ref: 'Out[1]' (str) len=6
examples/pydantic_ai_examples/data_analyst.py:97 display
    name: 'Out[1]' (str) len=6
    dataset.head(): <DataFrame({
        'text': <Series({
            0: (
                'the rock is destined to be the 21st century\'s new " conan " and that he\'s going to make a splash even'
                ' greater than arnold schwarzenegger , jean-claud van damme or steven segal .'
            ),
            1: (
                'the gorgeously elaborate continuation of " the lord of the rings " trilogy is so huge that a column o'
                "f words cannot adequately describe co-writer/director peter jackson's expanded vision of j . r . r . "
                "tolkien's middle-earth ."
            ),
            2: 'effective but too-tepid biopic',
            3: 'if you sometimes like to go to the movies to have fun , wasabi is a good place to start .',
            4: (
                "emerges as something rare , an issue movie that's so honest and keenly observed that it doesn't feel "
                'like one .'
            ),
        })>,
        'label': <Series({
            0: 1,
            1: 1,
            2: 1,
            3: 1,
            4: 1,
        })>,
    })> (DataFrame) len=5
examples/pydantic_ai_examples/data_analyst.py:85 run_duckdb
    sql: 'SELECT label, COUNT(*) as count FROM dataset GROUP BY label ORDER BY label' (str) len=74
    dataset: 'Out[1]' (str) len=6
examples/pydantic_ai_examples/data_analyst.py:97 display
    name: 'Out[2]' (str) len=6
    dataset.head(): <DataFrame({
        'label': <Series({
            0: 0,
            1: 1,
        })>,
        'count': <Series({
            0: 4265,
            1: 4265,
        })>,
    })> (DataFrame) len=2
examples/pydantic_ai_examples/data_analyst.py:107 <module>
    result.output: (
        'Based on the results, there are **4,265 negative comments** in the Cornell Movie Review Dataset (Rotten Tomat'
        'oes). The dataset appears to be balanced, with an equal number of negative and positive reviews in the traini'
        'ng split.'
    ) (str) len=227

[hyperlint-ai]

PR Change Summary

Added an example demonstrating how to use RunContext for passing data among tools, particularly in data analytics workflows.

• Introduced a new example in the documentation for using RunContext to reference tool outputs.
• Updated the tools documentation for clarity on tool registration.
• Provided a detailed example of analyzing a dataset using RunContext.

Modified Files

• docs/tools.md

Added Files

• docs/examples/data-analyst.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.

[DouweM]

@tonyxwz Thanks Tony! Just a few suggestions

[tonyxwz]

Pushed a new revision.

[tonyxwz]

https://github.com/pydantic/pydantic-ai/actions/runs/16605150201/job/46974951928#step:9:46

Run uv run --no-project --with httpx .github/set_docs_pr_preview_url.py
Installed 8 packages in 5ms
Docs preview URL: https://91de4635-pydantic-ai-previews.pydantic.workers.dev/
Pull request number not set
Error: Process completed with exit code 1.

https://91de4635-pydantic-ai-previews.pydantic.workers.dev/

[DouweM]

We should use get here right?

[tonyxwz]

Thanks, changed to using get.

[DouweM]

We can make this a bit cleaner by giving the output field a default value of {}, and then passing deps=AnalystAgentDeps() below

[tonyxwz]

Done, added field and default_factory in the class

[DouweM]

Suggested change

	"""Display at most 5 rows of the dataframe ."""
	"""Display at most 5 rows of the dataframe."""

[tonyxwz]

fixed.

[DouweM]

@tonyxwz Thanks Tony, this'll be a nice example -- just a few final suggestions and I'll merge

[DouweM]

Let's just use print here. Don't forget to update the output in the doc as well.

[tonyxwz]

done

[DouweM]

@tonyxwz Thanks Tony, nice addition!