> ## Documentation Index
> Fetch the complete documentation index at: https://inference-docs.cerebras.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with Pydantic AI

> Learn how to build type-safe, production-ready AI agents using Pydantic AI with Cerebras Inference for blazing-fast responses.

## What is Pydantic AI?

Pydantic AI is a Python agent framework designed to make it easy to build production-grade applications with Generative AI. It leverages Pydantic's validation and serialization capabilities to create type-safe, reliable AI agents. When combined with Cerebras Inference, you get both the safety of type validation and the speed of the world's fastest inference.

Key features include:

* **Type-safe structured outputs** using Pydantic models
* **Function calling (tools)** to extend agent capabilities
* **Streaming support** for real-time responses
* **Async-first design** for high-performance applications
* **Built-in validation** to ensure reliable outputs

Learn more on the [Pydantic AI website](https://ai.pydantic.dev/?utm_source=cerebras\&utm_campaign=pydantic-ai).

## Prerequisites

Before you begin, ensure you have:

* **Cerebras API Key** - Get a free API key [here](https://cloud.cerebras.ai/?utm_source=3pi_pydantic-ai\&utm_campaign=integrations)
* **Python 3.9 or higher** - Pydantic AI requires Python 3.9+
* **Basic familiarity with Pydantic** - Understanding of Pydantic models is helpful but not required

## Configure Pydantic AI with Cerebras

<Steps>
  <Step title="Install Pydantic AI">
    Install Pydantic AI using pip. This will install Pydantic AI along with its core dependencies:

    ```bash theme={null}
    pip install pydantic-ai openai 
    ```

    For development with additional tools, you can install optional dependencies:

    ```bash skip theme={null}
    pip install 'pydantic-ai[logfire]'
    ```
  </Step>

  <Step title="Set up your API key">
    Create a `.env` file in your project directory to store your Cerebras API key securely:

    ```bash theme={null}
    CEREBRAS_API_KEY=your-cerebras-api-key-here
    ```

    Alternatively, you can set it as an environment variable in your shell:

    ```bash theme={null}
    export CEREBRAS_API_KEY=your-cerebras-api-key-here
    ```
  </Step>

  <Step title="Create your first agent">
    Pydantic AI makes it easy to create agents with Cerebras models. Here's a simple example that creates an agent using GPT-OSS 120B. The `OpenAIChatModel` class is used because Cerebras provides an OpenAI-compatible API:

    ```python theme={null}
    import os
    import asyncio
    from openai import AsyncOpenAI
    from pydantic_ai import Agent
    from pydantic_ai.models.openai import OpenAIChatModel
    from pydantic_ai.providers.cerebras import CerebrasProvider

    # Create an OpenAI client with the integration header
    openai_client = AsyncOpenAI(
        base_url='https://api.cerebras.ai/v1',
        api_key=os.getenv('CEREBRAS_API_KEY'),
        default_headers={'X-Cerebras-3rd-Party-Integration': 'pydantic-ai'}
    )

    # Create a Cerebras provider with the custom client
    provider = CerebrasProvider(openai_client=openai_client)

    # Create a Cerebras model instance
    model = OpenAIChatModel('gpt-oss-120b', provider=provider)

    # Create an agent with the Cerebras model
    agent = Agent(
        model=model,
        system_prompt='You are a helpful assistant that provides clear, concise answers.'
    )

    async def main():
        # Run the agent asynchronously
        result = await agent.run('What is the capital of France?')
        print(result.output)

    asyncio.run(main())
    ```

    This creates a basic agent that uses Cerebras for inference. The agent will respond with validated, type-safe outputs.
  </Step>

  <Step title="Add structured outputs with Pydantic models">
    One of Pydantic AI's most powerful features is the ability to get structured, validated outputs. Define a Pydantic model to specify the exact structure you want, and the agent will automatically extract and validate the data:

    ```python theme={null}
    import os
    import asyncio
    from pydantic import BaseModel, Field
    from pydantic_ai import Agent
    from pydantic_ai.models.openai import OpenAIChatModel

    # Define your output structure with validation
    class CityInfo(BaseModel):
        city: str = Field(description="The name of the city")
        country: str = Field(description="The country where the city is located")
        population: int = Field(description="Approximate population")
        famous_for: list[str] = Field(description="List of things the city is famous for")

    # Create the Cerebras model
    model = OpenAIChatModel(
        'gpt-oss-120b',
        provider='cerebras'
    )

    # Create an agent with structured output
    agent = Agent(
        model=model,
        output_type=CityInfo,  # Changed from result_type to output_type
        system_prompt='Extract city information from the user query. Provide accurate, factual data.'
    )

    # Get structured, validated output
    async def main():
        result = await agent.run('Tell me about Paris')
        print(result.output)

    import asyncio
    asyncio.run(main())
    ```

    The agent will automatically validate the output against your Pydantic model, ensuring type safety and data integrity.
  </Step>

  <Step title="Use async for better performance">
    For production applications, use async/await to handle multiple requests efficiently. This is especially powerful with Cerebras's fast inference speeds, allowing you to process many requests concurrently:

    ```python theme={null}
    import os
    import asyncio
    from pydantic_ai import Agent
    from pydantic_ai.models.openai import OpenAIChatModel

    # Create the Cerebras model
    model = OpenAIChatModel(
        'gpt-oss-120b',
        provider='cerebras'
    )

    agent = Agent(
        model=model,
        system_prompt='You are a helpful assistant.'
    )

    async def main():
        results = await asyncio.gather(
            agent.run('What is 2+2?'),
            agent.run('What is the capital of Spain?'),
            agent.run('Who wrote Romeo and Juliet?')
        )
        for i, result in enumerate(results, 1):
            print(f"Answer {i}: {result.output}")

    asyncio.run(main())
    ```

    Async operations allow your application to scale efficiently while taking advantage of Cerebras's ultra-low latency.
  </Step>

  <Step title="Add tools for function calling">
    Pydantic AI supports tools (function calling) to extend your agent's capabilities beyond text generation. Tools allow your agent to perform actions, fetch data, or interact with external systems:

    ```python theme={null}
    import os
    import asyncio
    from datetime import datetime
    from pydantic_ai import Agent, RunContext
    from pydantic_ai.models.openai import OpenAIChatModel

    model = OpenAIChatModel(
        'gpt-oss-120b',
        provider='cerebras'
    )

    agent = Agent(
        model=model,
        system_prompt='You are a helpful assistant with access to tools.'
    )

    @agent.tool
    def get_current_time(ctx: RunContext[None]) -> str:
        """Get the current time in a readable format."""
        return datetime.now().strftime('%I:%M %p')

    @agent.tool
    def calculate(ctx: RunContext[None], expression: str) -> str:
        """Safely evaluate a mathematical expression.
        
        Args:
            expression: A mathematical expression like '15 * 23'
        """
        try:
            # In production, use a safe eval library like numexpr
            result = eval(expression, {'__builtins__': {}}, {})
            return str(result)
        except Exception as e:
            return f"Error: {str(e)}"

    # The agent can now use these tools automatically
    import asyncio

    async def main():
        result = await agent.run('What time is it and what is 15 * 23?')
        print(result.output)

    asyncio.run(main())
    ```

    The agent will automatically determine when to call tools based on the user's query, making your agents more capable and interactive.
  </Step>

  <Step title="Stream responses in real-time">
    For real-time applications like chatbots or interactive UIs, you can stream responses from Cerebras as they're generated. This provides a better user experience with immediate feedback:

    ```python theme={null}
    import os
    import asyncio
    from pydantic_ai import Agent
    from pydantic_ai.models.openai import OpenAIChatModel

    model = OpenAIChatModel(
        'gpt-oss-120b',
        provider='cerebras'
    )

    agent = Agent(
        model=model,
        system_prompt='You are a creative writing assistant.'
    )

    # Stream the response token by token
    async def main():
        async with agent.run_stream('Write a short poem about AI') as response:
            async for chunk in response.stream_text():
                print(chunk, end='', flush=True)
            print()  # New line at the end

    asyncio.run(main())
    ```

    Streaming is particularly effective with Cerebras's high-speed inference, delivering tokens to users almost instantaneously.
  </Step>
</Steps>

## Available Cerebras Models

You can use any of the following Cerebras models with Pydantic AI. Each model offers different trade-offs between capability, speed, and cost:

* **`gpt-oss-120b`** - Large open-source model with broad knowledge
* **`zai-glm-4.7`** - Advanced 357B parameter model with strong reasoning capabilities

To switch models, simply change the model name (e.g., `'gpt-oss-120b'`) when creating your model instance.

## Advanced Features

### Dependency Injection

Pydantic AI supports dependency injection to pass context and state to your agents and tools:

```python theme={null}
import os
import asyncio
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from pydantic_ai.models.openai import OpenAIChatModel

@dataclass
class UserContext:
    user_id: str
    preferences: dict

model = OpenAIChatModel(
    'gpt-oss-120b',
    provider='cerebras'
)

agent = Agent(
    model=model,
    deps_type=UserContext
)

@agent.tool
def get_user_preference(ctx: RunContext[UserContext], key: str) -> str:
    """Get a user preference by key."""
    return ctx.deps.preferences.get(key, 'Not set')

# Run with dependencies
import asyncio

async def main():
    user_ctx = UserContext(
        user_id='user123',
        preferences={'theme': 'dark', 'language': 'en'}
    )
    result = await agent.run('What is my theme preference?', deps=user_ctx)
    print(result.output)

asyncio.run(main())
```

### Result Validators

Add custom validation logic to ensure outputs meet your requirements:

```python theme={null}
import os
import asyncio
from pydantic import BaseModel, Field
from pydantic_ai import Agent, ModelRetry
from pydantic_ai.models.openai import OpenAIChatModel

class Summary(BaseModel):
    title: str
    summary: str = Field(description="A concise summary")
    word_count: int

model = OpenAIChatModel(
    'gpt-oss-120b',
    provider='cerebras'
)

agent = Agent(
    model=model,
    output_type=Summary  # Changed from result_type to output_type
)

@agent.output_validator
def validate_summary_length(ctx, result: Summary) -> Summary:
    """Ensure summary is not too long."""
    if result.word_count > 500:
        raise ModelRetry('Summary is too long. Please make it more concise.')
    return result

import asyncio

async def main():
    result = await agent.run('Summarize the history of artificial intelligence')
    print(result.output)

asyncio.run(main())
```

## Debugging with Pydantic Logfire

Pydantic Logfire provides powerful debugging and monitoring capabilities for your AI agents. It automatically tracks all agent runs, tool calls, and model interactions:

```python theme={null}
import os
import asyncio
import logfire
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel

# Configure Logfire
logfire.configure()

model = OpenAIChatModel(
    'gpt-oss-120b',
    provider='cerebras'
)

agent = Agent(model=model)

# All agent runs are automatically logged to Logfire
result = agent.run_sync('What is machine learning?')
print(result.output)
```

Logfire provides a web UI where you can view traces, debug issues, and monitor performance. Learn more in the [Pydantic Logfire documentation](https://ai.pydantic.dev/logfire/?utm_source=cerebras\&utm_campaign=pydantic-ai).

## Next Steps

* **Explore the [Pydantic AI documentation](https://ai.pydantic.dev/?utm_source=cerebras\&utm_campaign=pydantic-ai)** - Learn about advanced features like dependency injection, result validators, and more
* **Try different Cerebras models** - Experiment with different models to find the best balance of speed and capability for your use case
* **Build multi-agent systems** - Use Pydantic AI's [multi-agent patterns](https://ai.pydantic.dev/multi-agent-patterns/?utm_source=cerebras\&utm_campaign=pydantic-ai) to create complex workflows
* **Add monitoring with Logfire** - Integrate [Pydantic Logfire](https://ai.pydantic.dev/logfire/?utm_source=cerebras\&utm_campaign=pydantic-ai) for debugging and observability
* **Check out examples** - Browse the [Pydantic AI examples](https://ai.pydantic.dev/examples/?utm_source=cerebras\&utm_campaign=pydantic-ai) for inspiration
* **Read the API reference** - Dive deep into the [API documentation](https://ai.pydantic.dev/api/agent/?utm_source=cerebras\&utm_campaign=pydantic-ai)
* **Migrate to GLM4.7**: Ready to upgrade? Follow our [migration guide](https://inference-docs.cerebras.ai/resources/glm-47-migration) to start using our latest model

## FAQ

<Accordion title="Why use OpenAIModel for Cerebras?">
  Cerebras provides an OpenAI-compatible API, so you use the `OpenAIModel` class from Pydantic AI. This allows you to leverage the full OpenAI ecosystem while benefiting from Cerebras's superior speed and performance. Simply point the `base_url` to Cerebras's endpoint.
</Accordion>

<Accordion title="Can I use streaming with structured outputs?">
  Currently, streaming is primarily designed for text outputs. For structured outputs with Pydantic models, use the standard `run()` or `run_sync()` methods. The model needs to generate the complete response before it can be validated against your schema.
</Accordion>

<Accordion title="How do I handle rate limits?">
  Pydantic AI automatically handles retries for transient errors. For rate limiting, you can implement custom retry logic using the `retries` parameter when running agents, or use a library like `tenacity` to add more sophisticated retry strategies around your agent calls.
</Accordion>

<Accordion title="Which model should I choose for structured outputs?">
  For complex structured outputs with nested objects or strict validation requirements, we recommend using `gpt-oss-120b`. It provides the best accuracy for following schemas and generating valid JSON. For simpler extractions, `gpt-oss-120b` can be more cost-effective.
</Accordion>

<Accordion title="Can I use Pydantic AI with other Cerebras features?">
  Yes! Pydantic AI works seamlessly with all Cerebras features. You can use streaming, function calling, and all supported parameters. Simply pass additional parameters through the model configuration or when calling `run()`.
</Accordion>

## Troubleshooting

### Import Error: "No module named 'pydantic\_ai'"

Make sure you've installed Pydantic AI:

```bash theme={null}
pip install pydantic-ai
```

If you're using a virtual environment, ensure it's activated before installing.

### Authentication Error

If you see authentication errors, verify that:

1. Your `CEREBRAS_API_KEY` environment variable is set correctly
2. Your API key is valid and active (check your [Cerebras dashboard](https://cloud.cerebras.ai/?utm_source=3pi_pydantic-ai\&utm_campaign=integrations))
3. You're using the correct base URL: `https://api.cerebras.ai/v1`
4. The API key is being loaded properly with `os.getenv('CEREBRAS_API_KEY')`

### Model Not Found Error

Ensure you're using one of the supported Cerebras models:

* `gpt-oss-120b`
* `zai-glm-4.7`

Model names are case-sensitive and must match exactly as shown above.

### Structured Output Validation Errors

If your structured outputs aren't validating correctly:

1. **Add field descriptions** - Use Pydantic's `Field(description="...")` to provide clear guidance to the model
2. **Simplify your schema** - Start with simpler models and gradually add complexity
3. **Add examples in your prompt** - Include sample outputs in your system prompt
4. **Use a more capable model** - Try `gpt-oss-120b` for better structured output quality
5. **Add result validators** - Use `@agent.result_validator` to provide feedback and retry logic

### Tool Calling Issues

If tools aren't being called correctly:

1. **Add clear docstrings** - Tools need descriptive docstrings that explain what they do
2. **Use type hints** - Properly annotate all parameters with types
3. **Test tools independently** - Verify your tool functions work correctly outside the agent
4. **Check the system prompt** - Make sure your prompt doesn't discourage tool use

### Performance Issues

If you're experiencing slower than expected performance:

1. **Use async operations** - Switch from `run_sync()` to `run()` with async/await
2. **Enable streaming** - Use `run_stream()` for better perceived performance
3. **Choose the right model** - Use `gpt-oss-120b` for simple tasks that don't require the largest model
4. **Batch requests** - Use `asyncio.gather()` to process multiple requests concurrently

<Note>
  For more detailed troubleshooting and community support, visit the [Pydantic AI GitHub discussions](https://github.com/pydantic/pydantic-ai/discussions) or check the [troubleshooting guide](https://ai.pydantic.dev/help/?utm_source=cerebras\&utm_campaign=pydantic-ai).
</Note>