node_modules/

**.idea/

/test_tmp/

::: pydantic_ai.models.mcp_sampling

Here's an example of how you can use the DuckDuckGo search tool with an agent:

```py {title="main.py" test="skip"}

```py {title="duckduckgo_search.py" test="skip"}

from pydantic_aiimport Agent

from pydantic_ai.common_tools.duckduckgoimport duckduckgo_search_tool

Here's an example of how you can use the Tavily search tool with an agent:

```py {title="main.py" test="skip"}

```py {title="tavily_search.py" test="skip"}

import os

from pydantic_ai.agentimport Agent

_(This example is complete, it can be run "as is")_

```python {title="test_joke_app.py" hl_lines="10-12" call_name="test_application_code"}

```python {title="test_joke_app.py" hl_lines="10-12" call_name="test_application_code" requires="joke_app.py"}

from joke_appimport MyDeps, application_code, joke_agent

Pydantic Evals includes several built-in evaluators and allows you to create custom evaluators:

```python {title="simple_eval_evaluator.py"}

```python {title="simple_eval_evaluator.py" requires="simple_eval_dataset.py"}

from dataclassesimport dataclass

from simple_eval_datasetimport dataset

You can also write datasets as JSON files:

```python {title="generate_dataset_example_json.py"}

```python {title="generate_dataset_example_json.py" requires="generate_dataset_example.py"}

from pathlibimport Path

from generate_dataset_exampleimport AnswerOutput, MetadataType, QuestionInputs

A[mermaid diagram](#mermaid-diagrams) for this graph can be generated with the following code:

```py {title="graph_example_diagram.py" py="3.10"}

```py {title="graph_example_diagram.py" py="3.10" requires="graph_example.py"}

from graph_exampleimport DivisibleBy5, fives_graph

fives_graph.mermaid_code(start_node=DivisibleBy5)

A[mermaid diagram](#mermaid-diagrams) for this graph can be generated with the following code:

```py {title="vending_machine_diagram.py" py="3.10"}

```py {title="vending_machine_diagram.py" py="3.10" requires="vending_machine.py"}

from vending_machineimport InsertCoin, vending_machine_graph

vending_machine_graph.mermaid_code(start_node=InsertCoin)

Below is a contrived example that stops whenever the counter is at 2, ignoring any node runs beyond that:

```python {title="count_down_next.py" noqa="I001" py="3.10"}

```python {title="count_down_next.py" noqa="I001" py="3.10" requires="count_down.py"}

from pydantic_graphimport End, FullStatePersistence

from count_downimport CountDown, CountDownState, count_down_graph

As you can see in this code,`run_node` requires no external application state (apart from state persistence) to be run, meaning graphs can easily be executed by distributed execution and queueing systems.

```python {title="count_down_from_persistence.py" noqa="I001" py="3.10"}

```python {title="count_down_from_persistence.py" noqa="I001" py="3.10" requires="count_down.py"}

from pathlibimport Path

from pydantic_graphimport End

```python {title="ai_q_and_a_run.py" noqa="I001" py="3.10"}

```python {title="ai_q_and_a_run.py" noqa="I001" py="3.10" requires="ai_q_and_a_graph.py"}

import sys

from pathlibimport Path

-`'BT'`: Bottom to top, the diagram flows vertically from bottom to top.

Here is an example of how to do this using 'Left to Right' (LR) instead of the default 'Top to Bottom' (TB):

```py {title="vending_machine_diagram.py" py="3.10"}

```py {title="vending_machine_diagram.py" py="3.10" requires="vending_machine.py"}

from vending_machineimport InsertCoin, vending_machine_graph

vending_machine_graph.mermaid_code(start_node=InsertCoin,direction='LR')

If you have a direct URL for the image, you can use[`ImageUrl`][pydantic_ai.ImageUrl]:

```py {title="main.py" test="skip" lint="skip"}

```py {title="image_input.py" test="skip" lint="skip"}

from pydantic_aiimport Agent, ImageUrl

agent= Agent(model='openai:gpt-4o')

If you have the image locally, you can also use[`BinaryContent`][pydantic_ai.BinaryContent]:

```py {title="main.py" test="skip" lint="skip"}

```py {title="local_image_input.py" test="skip" lint="skip"}

import httpx

from pydantic_aiimport Agent, BinaryContent

If you have a direct URL for the document, you can use[`DocumentUrl`][pydantic_ai.DocumentUrl]:

```py {title="main.py" test="skip" lint="skip"}

```py {title="document_input.py" test="skip" lint="skip"}

from pydantic_aiimport Agent, DocumentUrl

agent= Agent(model='anthropic:claude-3-sonnet')

You can also use[`BinaryContent`][pydantic_ai.BinaryContent] to pass document data directly:

```py {title="main.py" test="skip" lint="skip"}

```py {title="binary_content_input.py" test="skip" lint="skip"}

from pathlibimport Path

from pydantic_aiimport Agent, BinaryContent

Before creating the Streamable HTTP client, we need to run a server that supports the Streamable HTTP transport.

```python {title="streamable_http_server.py" py="3.10"test="skip"}

```python {title="streamable_http_server.py" py="3.10"dunder_name="not_main"}

from mcp.server.fastmcpimport FastMCP

app= FastMCP()

defadd(a:int,b:int) ->int:

return a+ b

app.run(transport='streamable-http')

if__name__=='__main__':

app.run(transport='streamable-http')

Then we can create the client:

returnawait call_tool(tool_name, args,metadata={'deps': ctx.deps})

server= MCPServerStdio('python', ['-m','tests.mcp_server'],process_tool_call=process_tool_call)

server= MCPServerStdio('python', ['mcp_server.py'],process_tool_call=process_tool_call)

agent= Agent(

model=TestModel(call_tools=['echo_deps']),

deps_type=int,

When the model interacts with these servers, it will see the prefixed tool names, but the prefixes will be automatically handled when making tool calls.

!!! info "What is MCP Sampling?"

In MCP[sampling](https://modelcontextprotocol.io/docs/concepts/sampling) is a system by which an MCP server can make LLM calls via the MCP client - effectively proxying requests to an LLM via the client over whatever transport is being used.

Pydantic AI supports sampling as both a client and server. See the[server](./server.md#mcp-sampling) documentation for details on how to use sampling within a server.

Sampling is automatically supported by Pydantic AI agents when they act as a client.

Let's say we have an MCP server that wants to use sampling (in this case to generate an SVG as per the tool arguments).

??? example "Sampling MCP Server"

Using this server with an`Agent` will automatically allow sampling:

```python {title="sampling_mcp_client.py" py="3.10" requires="generate_svg.py"}

from pydantic_aiimport Agent

from pydantic_ai.mcpimport MCPServerStdio

server= MCPServerStdio(command='python',args=['generate_svg.py'])

agent= Agent('openai:gpt-4o',mcp_servers=[server])

asyncdefmain():

asyncwith agent.run_mcp_servers():

result=await agent.run('Create an image of a robot in a punk style.')

print(result.output)

_(This example is complete, it can be run "as is" with Python 3.10+)_

You can disallow sampling by settings[`allow_sampling=False`][pydantic_ai.mcp.MCPServerStdio.allow_sampling] when creating the server reference, e.g.:

```python {title="sampling_disallowed.py" hl_lines="6" py="3.10"}

from pydantic_ai.mcpimport MCPServerStdio

server= MCPServerStdio(

command='python',

args=['generate_svg.py'],

allow_sampling=False,

)

This allows use of dependencies that aren't imported in the code, and is more explicit.

```py {title="inline_script_metadata.py" py="3.10"}

```py {title="inline_script_metadata.py" py="3.10" requires="mcp_run_python.py"}

from mcpimport ClientSession

from mcp.client.stdioimport stdio_client