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

tonyxwz · 2025-07-25T19:52:14Z

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

passing the reference instead of the actual data to the agent context window
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 · 2025-07-25T19:52:31Z

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

docs/examples/data-analyst.md