docs: add Pydantic AI guide + Hermes standalone provider-plugin section #72
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,206 @@ | ||
| --- | ||
| title: "Pydantic AI" | ||
| icon: "/integration-logo/pydantic-ai-icondoc.svg" | ||
| description: "Use Pydantic AI with Eden AI to build type-safe agents on 500+ AI models through one API." | ||
| --- | ||
|
|
||
| import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; | ||
|
|
||
| <TechArticleSchema | ||
| title={"Pydantic AI"} | ||
| description={"Use Pydantic AI with Eden AI to build type-safe agents on 500+ AI models through one API."} | ||
| path="v3/integrations/pydantic-ai" | ||
| articleSection="AI Frameworks" | ||
| about={"LLM Framework Integration"} | ||
| proficiencyLevel="Intermediate" | ||
| keywords={["Eden AI", "AI API", "Pydantic AI", "Python", "Agents"]} | ||
| datePublished="2026-07-16T00:00:00Z" | ||
| dateModified="2026-07-16T00:00:00Z" | ||
| /> | ||
|
|
||
| Use Pydantic AI with Eden AI to build type-safe agents on 500+ AI models through one API. | ||
|
|
||
| ## Overview | ||
|
|
||
| Pydantic AI is a type-safe, structured-output agent framework for Python. It works with any OpenAI-compatible endpoint through `OpenAIChatModel` + `OpenAIProvider`, so you can point it at Eden AI's V3 API and access models from OpenAI, Anthropic, Google, Cohere, Meta, and more — behind one key, with EU-based, GDPR-aligned inference. | ||
|
|
||
| ## Installation | ||
|
|
||
| <CodeGroup> | ||
| ```bash pip | ||
| pip install pydantic-ai | ||
| ``` | ||
|
|
||
| ```bash poetry | ||
| poetry add pydantic-ai | ||
| ``` | ||
|
|
||
| </CodeGroup> | ||
|
|
||
| ## Quick Start | ||
|
|
||
| Point Pydantic AI's OpenAI model at Eden AI: | ||
|
|
||
| <CodeGroup> | ||
| {/* skip-test */} | ||
| ```python Python | ||
| from pydantic_ai import Agent | ||
| from pydantic_ai.models.openai import OpenAIChatModel | ||
| from pydantic_ai.providers.openai import OpenAIProvider | ||
|
|
||
| model = OpenAIChatModel( | ||
| "openai/gpt-4o", | ||
| provider=OpenAIProvider( | ||
| api_key="YOUR_EDEN_AI_API_KEY", # Get from https://app.edenai.run | ||
| base_url="https://api.edenai.run/v3", | ||
| ), | ||
| ) | ||
|
|
||
| agent = Agent(model) | ||
| result = agent.run_sync("Hello! How are you?") | ||
| print(result.output) | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| ## Available Models | ||
|
|
||
| Access models from multiple providers using the `provider/model` format: | ||
|
|
||
| **OpenAI** | ||
| - `openai/gpt-4o` | ||
| - `openai/gpt-4o-mini` | ||
| - `openai/gpt-4-turbo` | ||
|
|
||
| **Anthropic** | ||
| - `anthropic/claude-sonnet-4-5` | ||
| - `anthropic/claude-opus-4-5` | ||
| - `anthropic/claude-haiku-4-5` | ||
|
|
||
| **Google** | ||
| - `google/gemini-2.5-pro` | ||
| - `google/gemini-2.5-flash` | ||
|
|
||
| **Mistral** | ||
| - `mistral/mistral-large-latest` | ||
| - `mistral/mistral-small-latest` | ||
|
|
||
| ## Structured Output | ||
|
|
||
| Pydantic AI's signature feature works unchanged — define a Pydantic `output_type` and the agent returns a validated object, whichever Eden AI model you choose: | ||
|
|
||
| <CodeGroup> | ||
| {/* skip-test */} | ||
| ```python Python | ||
| from pydantic import BaseModel | ||
| from pydantic_ai import Agent | ||
| from pydantic_ai.models.openai import OpenAIChatModel | ||
| from pydantic_ai.providers.openai import OpenAIProvider | ||
|
|
||
| class City(BaseModel): | ||
| name: str | ||
| country: str | ||
| population: int | ||
|
|
||
| model = OpenAIChatModel( | ||
| "anthropic/claude-sonnet-4-5", | ||
| provider=OpenAIProvider( | ||
| api_key="YOUR_EDEN_AI_API_KEY", | ||
| base_url="https://api.edenai.run/v3", | ||
| ), | ||
| ) | ||
|
|
||
| agent = Agent(model, output_type=City) | ||
| result = agent.run_sync("Tell me about the capital of France.") | ||
| print(result.output) # City(name='Paris', country='France', population=...) | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| ## Multi-Turn Conversations | ||
|
|
||
| Keep conversation history across runs with `message_history`: | ||
|
|
||
| <CodeGroup> | ||
| {/* skip-test */} | ||
| ```python Python | ||
| from pydantic_ai import Agent | ||
| from pydantic_ai.models.openai import OpenAIChatModel | ||
| from pydantic_ai.providers.openai import OpenAIProvider | ||
|
|
||
| model = OpenAIChatModel( | ||
| "anthropic/claude-sonnet-4-5", | ||
| provider=OpenAIProvider( | ||
| api_key="YOUR_EDEN_AI_API_KEY", | ||
| base_url="https://api.edenai.run/v3", | ||
| ), | ||
| ) | ||
| agent = Agent(model, system_prompt="You are a helpful assistant.") | ||
|
|
||
| result = agent.run_sync("What is the capital of France?") | ||
| print(result.output) | ||
|
|
||
| # Continue the conversation with prior context | ||
| result = agent.run_sync( | ||
| "What's its population?", | ||
| message_history=result.all_messages(), | ||
| ) | ||
| print(result.output) | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| ## Error Handling | ||
|
|
||
| <CodeGroup> | ||
| {/* skip-test */} | ||
| ```python Python | ||
| from pydantic_ai import Agent | ||
| from pydantic_ai.models.openai import OpenAIChatModel | ||
| from pydantic_ai.providers.openai import OpenAIProvider | ||
| from pydantic_ai.exceptions import ModelHTTPError, UnexpectedModelBehavior | ||
|
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🌐 Web query:
💡 Result: ModelHTTPError is not a standard error class in the Pydantic AI framework or general Python programming. Based on the provided technical documentation for Pydantic AI, the library primarily uses UserError for configuration or usage issues [1], ModelRetry for validation failures during agent runs [2], and NotImplementedError for base model methods that have not been implemented by specific providers [1]. If you are encountering an error related to HTTP requests in Pydantic AI, it typically relates to the underlying HTTP client used by the model provider (e.g., OpenAI, Anthropic, or Groq) [3][4][5]. These are usually handled by the provider's official SDK or standard HTTP exception classes rather than a specific library-wide ModelHTTPError. If you are seeing this name, it may be a custom exception defined within your specific codebase or a third-party library not covered by the official Pydantic AI documentation. Citations:
🌐 Web query:
💡 Result: Based on the provided documentation for Pydantic AI, there is no public class named ModelHTTPError defined within the pydantic_ai.exceptions module or the broader library. Pydantic AI uses standard exception handling mechanisms, and model-related errors typically surface through specific exceptions related to request failures or configuration issues, such as UserError or general HTTP/network exceptions depending on the underlying provider client (e.g., httpx for OpenAI or Anthropic). [1][2] Citations:
Drop 🤖 Prompt for AI Agents |
||
|
|
||
| model = OpenAIChatModel( | ||
| "openai/gpt-4o", | ||
| provider=OpenAIProvider( | ||
| api_key="YOUR_EDEN_AI_API_KEY", | ||
| base_url="https://api.edenai.run/v3", | ||
| ), | ||
| ) | ||
| agent = Agent(model) | ||
|
|
||
| try: | ||
| result = agent.run_sync("Hello!") | ||
| print(result.output) | ||
| except ModelHTTPError as e: | ||
| print(f"Model HTTP error (auth, rate limit, bad request): {e}") | ||
| except UnexpectedModelBehavior as e: | ||
| print(f"Unexpected model behavior: {e}") | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| ## Environment Variables | ||
|
|
||
| <CodeGroup> | ||
| ```bash .env | ||
| EDEN_AI_API_KEY=your_api_key_here | ||
| ``` | ||
|
|
||
| {/* skip-test */} | ||
| ```python Python | ||
| import os | ||
| from pydantic_ai.models.openai import OpenAIChatModel | ||
| from pydantic_ai.providers.openai import OpenAIProvider | ||
|
|
||
| model = OpenAIChatModel( | ||
| "openai/gpt-4o", | ||
| provider=OpenAIProvider( | ||
| api_key=os.getenv("EDEN_AI_API_KEY"), | ||
| base_url="https://api.edenai.run/v3", | ||
| ), | ||
| ) | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| ## Next Steps | ||
|
|
||
| - [Chat Completions](/v3/llms/chat-completions) - Core LLM endpoint | ||
| - [List LLM Models](/v3/llms/listing-models) - Browse available providers and models | ||
| - [OpenAI SDK (Python)](/v3/integrations/openai-sdk-python) - Direct SDK usage | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
"OpenAIModel" OR "OpenAIChatModel" site:ai.pydantic.dev💡 Result:
In the context of the PydanticAI framework, OpenAIChatModel is a class designed to facilitate interaction with OpenAI's API [1]. It serves as a model implementation that utilizes the official OpenAI Python client internally to manage API requests [1]. While the search results specifically identify and document OpenAIChatModel as part of the pydantic_ai.models.openai module [1], there is no distinct, documented class named OpenAIModel currently identified in the standard PydanticAI library structure; it is likely a misidentification or a conceptual reference to the base model interface or the broader family of OpenAI-compatible models [1][2]. Key characteristics of OpenAIChatModel include: - Functionality: It acts as a bridge between PydanticAI agents and OpenAI's chat-based language models [1]. - Initialization: It requires a model name (e.g., 'gpt-4o') and accepts optional parameters such as providers, model profiles, and default settings [1]. - Integration: It inherits from the base Model class [1], allowing it to be used seamlessly within PydanticAI Agents to process tasks, manage tool usage, and handle structured output [1][3][4]. If you encountered the term OpenAIModel, it may refer to the generic Model base class or a custom implementation in a specific codebase, as OpenAIChatModel is the explicit, provided implementation for OpenAI chat interfaces within the framework [1][2].
Citations:
🌐 Web query:
"OpenAIProvider" site:ai.pydantic.dev pydantic_ai.providers.openai💡 Result:
In the Pydantic AI library, OpenAI support is provided through the pydantic_ai.models.openai module, which defines model classes for interacting with OpenAI APIs [1]. Specifically, there is no top-level class named OpenAIProvider; instead, models are initialized using model strings (e.g., 'openai:gpt-4o') or by instantiating OpenAIChatModel or OpenAIResponsesModel [1]. Key points regarding OpenAI integration in Pydantic AI: 1. Model Initialization: When defining an Agent, you specify the model using a string identifier [2]. For example, Agent('openai:gpt-4o') automatically configures the agent to use the OpenAI provider [3][2]. 2. Provider Classes: - OpenAIChatModel: A model that uses the standard OpenAI Chat API [1]. - OpenAIResponsesModel: A model designed for the OpenAI Responses API [1]. 3. Provider Configuration: Both model classes accept a provider argument during initialization, which defaults to 'openai' [1]. This argument allows for specifying alternative compatible providers or custom AsyncOpenAI client configurations [1]. 4. Documentation Reference: Technical details and configuration options, such as OpenAIChatModelSettings, can be found in the pydantic_ai.models.openai API documentation [1].
Citations:
🌐 Web query:
site:ai.pydantic.dev pydantic_ai.models.openai OpenAIChatModel provider api_key base_url💡 Result:
In Pydantic AI, the OpenAIChatModel is designed to interface with the OpenAI API (or compatible services) [1]. Configuration of the
api_keyandbase_urlforOpenAIChatModelis typically handled through the underlying provider rather than directly in theOpenAIChatModelconstructor [1]. 1. Provider Configuration: TheOpenAIChatModelconstructor accepts aproviderargument [1]. By default, this is set to'openai'[1]. To customize parameters likeapi_keyorbase_url, you should instantiate a specific provider object (e.g.,OpenAIProvideror a similar provider class) and pass it to theproviderargument of theOpenAIChatModel[1]. 2. Environment Variables: For standard OpenAI usage, Pydantic AI typically retrieves the API key from environment variables (e.g.,OPENAI_API_KEY) automatically when using the default provider [1]. 3. General Pattern for Custom Providers: While documentation for specificOpenAIChatModelprovider configuration options can vary by version, the general pattern for custom configurations in Pydantic AI involves [2][3]: - Instantiating the provider class (e.g.,provider = OpenAIProvider(api_key='...', base_url='...')). - Passing this instance to the model (e.g.,model = OpenAIChatModel(..., provider=provider)). If you are using a self-hosted or compatible OpenAI-like API, ensure the provider instance is configured with the correctbase_urlandapi_keybefore initializing theOpenAIChatModel[1]. Check your specific version's API documentation for the exact provider class exported bypydantic_ai.providers[1][2].Citations:
🏁 Script executed:
Repository: edenai/docs
Length of output: 6263
🌐 Web query:
site:ai.pydantic.dev "pydantic_ai.providers.openai" OR "OpenAIProvider" OR "class OpenAIProvider"💡 Result:
PydanticAI does not have a class named OpenAIProvider within the pydantic_ai.providers namespace. In PydanticAI, OpenAI integration is primarily handled through the pydantic_ai.models.openai module [1]. The core class for using OpenAI models is OpenAIChatModel (or OpenAIResponsesModel for the Responses API) [1]. When configuring an agent, you typically specify the model name (e.g., 'openai:gpt-5.2') directly in the Agent constructor [2][3]. Internally, the framework uses these model classes to interact with the OpenAI API. While there is a concept of a provider within the OpenAIChatModel configuration—often defaulting to 'openai' or 'gateway'—it is managed via string identifiers or specific provider objects rather than a top-level class named OpenAIProvider [1]. If you are looking to define a custom provider or configure the underlying connection, you would interact with the model settings or the specific model class constructors [1].
Citations:
Replace
OpenAIProviderwith the supported PydanticAI OpenAI configurationOpenAIChatModelis valid, butpydantic_ai.providers.openai.OpenAIProvideris not exposed in PydanticAI, so this snippet will fail on import. Use the documented model/provider setup for the installed version instead.🤖 Prompt for AI Agents