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

# Pydantic AI

> Model Darwin requests and states with typed Pydantic AI tools.

Wrap the `darwin-sdk` Python client in narrow Pydantic AI tools. Let generated Darwin models validate API responses and keep the agent-facing tool descriptions focused on when each operation is appropriate.

[Copy the Pydantic AI MCP recipe](https://github.com/darwin-studios/darwin-integrations/blob/main/frameworks/pydantic-ai.md).

Search requires one natural-language query. Action mutations require exact identifiers and stable request IDs. Validate all model-produced tool arguments before sending them to Darwin.

Never coerce a structured nonterminal Action state into a successful return value merely to satisfy an agent result schema.

## Separate domain models

| Model            | Purpose                                                  |
| ---------------- | -------------------------------------------------------- |
| Search request   | Natural-language intent and explicit hard filters        |
| Search selection | Exact capability ID and revision                         |
| Action mutation  | Operation-specific fields and stable request ID          |
| Action response  | Current state, valid next actions, and typed interaction |

Keep validation strict at the Darwin boundary and let the application decide how much of the response belongs in model context.