> ## 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.

Search requires one natural-language query. Act thread writes require exact identifiers, the current revision, and stable retry IDs. Validate all model-produced tool arguments before sending them to Darwin.

Never coerce a typed request or nonterminal operation state into a successful return value merely to satisfy an agent result schema.

## Separate domain models

| Model | Purpose |
| - | - |
| Search request | Query with optional category, objective, and result count |
| Search selection | Exact agent and nested capability IDs |
| 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.