Metorial-Python SDK

Quick Start

This example uses PydanticAI with Anthropic Claude and Metorial Search, a built-in web search provider that requires no auth configuration. You just need two environment variables:

• METORIAL_API_KEY from platform.metorial.com
• ANTHROPIC_API_KEY from console.anthropic.com

pip install metorial pydantic-ai python-dotenv

For readability, the README snippets below use bare await. In a normal .py script, wrap them in async def main() and call asyncio.run(main()).

import os

from metorial import Metorial, metorial_pydantic_ai
from pydantic_ai import Agent

metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])

deployment = metorial.provider_deployments.create(
    name="Metorial Search",
    provider_id="metorial-search",
)

session = await metorial.connect(
    adapter=metorial_pydantic_ai(),
    providers=[
        {"provider_deployment_id": deployment.id},
    ],
)
agent = Agent(
    "anthropic:claude-sonnet-4-20250514",
    system_prompt="You are a helpful research assistant.",
    tools=session.tools(),
)

result = await agent.run(
    "Search the web for the latest news about AI agents and summarize the top 3 stories."
)
output = getattr(result, "data", None) or getattr(result, "output", str(result))
print(output)

See the full runnable example at examples/pydantic-ai/.

Examples

Check out the examples/ directory for complete working examples:

Provider Examples

These examples use connect() directly when you want provider-native tool formats rather than a framework adapter.

<details open> <summary><strong>OpenAI</strong></summary>

import os
from openai import AsyncOpenAI
from metorial import Metorial, metorial_openai

metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])
openai = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

deployment = metorial.provider_deployments.create(
    name="Metorial Search",
    provider_id="metorial-search",
)

session = await metorial.connect(
    adapter=metorial_openai(),
    providers=[{"provider_deployment_id": deployment.id}],
)
messages = [{"role": "user", "content": "Search the web for the latest news about AI agents."}]

response = await openai.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=session.tools(),
)

if response.choices[0].message.tool_calls:
    results = await session.call_tools(response.choices[0].message.tool_calls)
    # Add results to messages and continue conversation...

</details>

<details> <summary><strong>Anthropic</strong></summary>

import os
from anthropic import AsyncAnthropic
from metorial import Metorial, metorial_anthropic

metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])
anthropic = AsyncAnthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

deployment = metorial.provider_deployments.create(
    name="Metorial Search",
    provider_id="metorial-search",
)

session = await metorial.connect(
    adapter=metorial_anthropic(),
    providers=[{"provider_deployment_id": deployment.id}],
)
response = await anthropic.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=session.tools(),
    messages=[{"role": "user", "content": "Search the web for the latest news about AI agents."}],
)

if response.stop_reason == "tool_use":
    tool_calls = [b for b in response.content if b.type == "tool_use"]
    results = await session.call_tools(tool_calls)
    # Add results to messages and continue conversation...

</details>

<details> <summary><strong>Google Gemini</strong></summary>

import os
import google.generativeai as genai
from metorial import Metorial, metorial_google

metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])
genai.configure(api_key=os.environ["GOOGLE_API_KEY"])

deployment = metorial.provider_deployments.create(
    name="Metorial Search",
    provider_id="metorial-search",
)

session = await metorial.connect(
    adapter=metorial_google(),
    providers=[{"provider_deployment_id": deployment.id}],
)
model = genai.GenerativeModel("gemini-2.5-pro", tools=session.tools())
chat = model.start_chat()
response = chat.send_message("Search the web for the latest news about AI agents.")

for part in response.parts:
    if fn := part.function_call:
        result = await session.call_tool(fn.name, dict(fn.args))
        # Continue conversation with result...

</details>

<details> <summary><strong>Mistral</strong></summary>

import os
from mistralai import Mistral
from metorial import Metorial, metorial_mistral

metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

deployment = metorial.provider_deployments.create(
    name="Metorial Search",
    provider_id="metorial-search",
)

session = await metorial.connect(
    adapter=metorial_mistral(),
    providers=[{"provider_deployment_id": deployment.id}],
)
response = await mistral.chat.complete_async(
    model="mistral-large-latest",
    tools=session.tools(),
    messages=[{"role": "user", "content": "Search the web for the latest news about AI agents."}],
)

if response.choices[0].message.tool_calls:
    results = await session.call_tools(response.choices[0].message.tool_calls)
    # Add results to messages and continue conversation...

</details>

<details> <summary><strong>OpenAI-compatible Models (DeepSeek, Together, xAI)</strong></summary>

import os
from openai import AsyncOpenAI
from metorial import Metorial, metorial_openai_compatible

metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])
xai_compatible = AsyncOpenAI(
    api_key=os.environ["OPENAI_COMPATIBLE_API_KEY"],
    base_url="https://your-openai-compatible-endpoint/v1",
)

deployment = metorial.provider_deployments.create(
    name="Metorial Search",
    provider_id="metorial-search",
)

session = await metorial.connect(
    adapter=metorial_openai_compatible(),
    providers=[{"provider_deployment_id": deployment.id}],
)
response = await xai_compatible.chat.completions.create(
    model="your-model-name",
    tools=session.tools(),
    messages=[{"role": "user", "content": "Search the web for the latest news about AI agents."}],
)

if response.choices[0].message.tool_calls:
    results = await session.call_tools(response.choices[0].message.tool_calls)
    # Add results to messages and continue conversation...

</details>

Framework Integration Examples

Pre-Created Auth Config

An auth config represents an already-authenticated connection to a provider — for example, a user who has completed the OAuth flow for Slack. Once created (via the dashboard or a setup session), reference it by ID:

providers=[
    {
        "provider_deployment_id": "your-slack-deployment-id",
        "provider_auth_config_id": "your-auth-config-id",
    }
]

4. Use the auth config in a connected session

session = await metorial.connect( adapter=metorial_pydantic_ai(), providers=[ { "provider_deployment_id": "your-slack-deployment-id", "provider_auth_config_id": completed[0].auth_config.id, } ], ) tools = session.tools()

Session Options

• Recommended entry point: Use metorial.connect(adapter=..., providers=[...]) for new code. It matches the Node SDK and does not require manual close calls.
• Compatibility wrapper: provider_session(...) still exists when you want the older provider-specific session helpers inside an async with, but it is now just a thin wrapper over the same adapter/session resolution path used by connect().
• Multiple providers: Pass multiple entries in the providers list to combine tools from different MCP servers.

Metorial Python SDK

The official Python SDK for Metorial. Give your AI agents access to tools like Slack, GitHub, SAP, and hundreds more through MCP — without managing servers, auth flows, or infrastructure.

Sign up for a free account to get started.

Complete API Documentation

• Documentation - Documentation and guides
• API Reference - Complete API reference

Reference a session template by ID

session = await metorial.connect( adapter=metorial_pydantic_ai(), providers=[ {"session_template_id": "your-template-id"}, ], ) tools = session.tools()

Supported LLM Integrations

This SDK formats MCP tools for each LLM provider. Pass the provider parameter to get tools in the right format.

Framework Integrations

For popular agent frameworks, we provide helper functions that convert tools to the framework's native format: