Provider API Reference

The Provider API connects BindAI agents to external AI model services. Providers isolate vendor-specific model communication from the rest of the agent architecture, allowing agents to select different model providers while keeping application and agent logic largely independent of the underlying service. This page documents the current Provider API and provider architecture.

Overview

A provider connects an agent’s model request to an external AI service. Conceptually:

Agent
  |
  v
Provider
  |
  v
AI Model Service
  |
  v
Response

The provider handles the vendor-specific communication required to execute the request.

Provider Selection

BindAI uses a provider-and-model identifier when configuring an agent. The general format is:

provider:model

Examples include:

openai:gpt-4.1-mini
anthropic:claude-sonnet-4
google:gemini-2.5-flash
groq:llama-3.3-70b-versatile
ollama:llama3
openrouter:openai/gpt-4.1-mini

The exact models available depend on the provider and the external service.

Supported Providers

The current BindAI provider ecosystem includes:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

Additional providers can be added as the provider ecosystem grows.

Configuring a Provider

Providers are normally selected through the agent configuration. For example:

from bindai_core import Agent

agent = Agent.builder().provider("openai:gpt-4.1-mini").build()

Changing the provider-model identifier can allow the same agent architecture to use another supported provider.

Provider Registry

BindAI maintains a provider registry for registered provider implementations. Conceptually:

Provider Registry
       |
       +---- OpenAI
       +---- Anthropic
       +---- Google
       +---- Groq
       +---- Ollama
       +---- OpenRouter

The registry provides provider discovery and creation for registered provider implementations. Provider packages register their implementations with the registry.

Provider Bootstrap

Provider registration is initialized through BindAI’s provider bootstrap mechanism. The CLI initializes the available provider packages before starting the application. This allows provider integrations to remain modular instead of requiring all provider implementations to be hard-coded into the core agent runtime.

Request Lifecycle

A typical provider-backed agent execution follows this flow:

User Input
    |
    v
Agent
    |
    v
Build Request
    |
    v
Provider
    |
    v
External Model
    |
    v
Provider Response
    |
    v
AgentResult

The provider is responsible for communicating with the configured model service. The agent remains responsible for higher-level execution such as tools, memory, Knowledge, middleware, and application behavior.

Provider Responsibilities

A provider implementation can be responsible for concerns such as:

Model selection
Request construction
Authentication
Communication with the external service
Response handling
Streaming
Provider-specific error handling
Provider-specific capabilities

The exact implementation differs between providers.

Authentication

External providers generally require credentials. Typical configuration uses environment variables. Examples include:

OPENAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY
GROQ_API_KEY
OPENROUTER_API_KEY

Ollama commonly uses a locally available model service rather than requiring a cloud API key. Credentials should not be hard-coded into application source code.

Environment Configuration

Provider credentials can be loaded through environment configuration. For example:

Application
    |
    v
Environment Variables
    |
    v
Provider
    |
    v
External AI Service

Applications should keep secrets outside source control and provide them through the deployment environment.

Model Selection

A provider can expose access to multiple models. For example:

OpenAI
  |
  +---- GPT Model A
  +---- GPT Model B
  +---- GPT Model C

The selected model is part of the provider-model identifier. Changing models therefore generally requires changing the configured model identifier rather than rewriting the agent itself.

Streaming

Providers can support streaming model responses. Conceptually:

Model
  |
  v
Provider
  |
  v
Partial Output
  |
  v
Agent Stream
  |
  v
Application

Streaming allows applications to process model output incrementally instead of waiting for the complete response. Streaming behavior can vary by provider and model.

Structured Output

Provider capabilities can also affect structured-output behavior. An agent can request structured output using a supported schema. For example:

from pydantic import BaseModel
from bindai_core import Agent


class Person(BaseModel):
    name: str
    age: int


agent = Agent.builder().provider("openai:gpt-4.1-mini").build()

result = agent.run(
    "Alice is 30 years old.",
    output=Person,
)

Whether a particular provider and model can satisfy a structured-output request depends on the provider’s capabilities.

Tool Calling

Providers can participate in model-driven tool calling. Conceptually:

Agent
  |
  v
Provider
  |
  v
Model
  |
  +---- Tool Call
            |
            v
          Tool

The provider communicates the tool definitions and model responses required by the agent execution layer. The exact tool-calling capabilities depend on the selected provider and model.

Provider and Memory

Memory is handled by BindAI’s memory layer rather than being a provider responsibility. Conceptually:

Agent
  |
  +---- Memory
  |
  +---- Knowledge
  |
  +---- Tools
  |
  v
Provider
  |
  v
Model

This separation allows an application to change AI providers without changing its memory storage architecture.

Provider and Knowledge

Knowledge and retrieval are also separate from model-provider communication. An agent can combine:

A model provider
Knowledge
A retriever
Memory
Tools

The agent prepares the appropriate context before sending the model request.

Provider and Workflows

Workflows can coordinate agents that use different providers. For example:

Workflow
   |
   +---- Agent A -> OpenAI
   |
   +---- Agent B -> Anthropic
   |
   +---- Agent C -> Google

This allows different workflow stages to use different models where appropriate. The exact workflow API is documented separately.

Provider Errors

External model services can fail for many reasons. Examples include:

Invalid credentials
Invalid model identifiers
Invalid requests
Rate limits
Network failures
Service outages
Unsupported capabilities
Provider-side errors

Applications should distinguish provider failures from errors in their own application logic.

Provider Independence

A major purpose of the provider layer is reducing vendor-specific coupling. Conceptually:

                  Agent
                    |
                    v
             Provider Selection
                    |
          +---------+---------+
          |         |         |
          v         v         v
       OpenAI   Anthropic   Google

The same agent architecture can often be reused with another provider by changing its provider-model configuration. However, providers are not necessarily feature-equivalent. Applications should account for differences in:

Model capabilities
Context limits
Tool calling
Structured output
Streaming
Latency
Rate limits
Availability

Performance Considerations

Provider performance can vary significantly. Important considerations include:

Response latency
Throughput
Context-window size
Model capability
Streaming behavior
Rate limits
Service availability
Cost

Provider selection should therefore be based on application requirements rather than assuming that all providers behave identically.

Custom Providers

BindAI’s provider architecture is designed to support additional provider implementations. A custom provider integration generally needs to:

Register with the provider system.
Resolve a provider-model configuration.
Communicate with the target model service.
Convert requests into the service’s expected format.
Convert responses into the format expected by BindAI.
Handle provider-specific failures.
Support relevant capabilities such as streaming where appropriate.

The exact implementation contract should be verified against the current provider base classes and registry implementation before creating a new provider package.

Provider Packages

Provider integrations are kept modular. Conceptually:

BindAI Core
     |
     +---- Provider Package: OpenAI
     +---- Provider Package: Anthropic
     +---- Provider Package: Google
     +---- Provider Package: Groq
     +---- Provider Package: Ollama
     +---- Provider Package: OpenRouter

This architecture allows provider integrations to evolve independently from the core agent package.

Security

Provider integrations handle credentials and potentially sensitive model input. Applications should:

Keep API credentials out of source code.
Use environment or secret-management systems.
Use secure transport.
Avoid logging credentials.
Avoid unnecessarily logging sensitive prompts and responses.
Restrict provider credentials to the required permissions.
Rotate credentials according to organizational policy.

Provider security is part of the overall application security model.

Testing Providers

Provider integrations should be tested at multiple levels. Useful tests include:

Provider registration
Provider discovery
Model configuration
Request construction
Response handling
Streaming behavior
Structured output
Tool calling
Invalid configuration
Authentication failures
Provider errors

Tests that require real external services should be separated from deterministic unit tests and should use appropriate credentials and test resources.

Provider Configuration and Agent Logic

Provider configuration should remain separate from business logic. For example:

Business Logic
      |
      v
Agent Configuration
      |
      v
Provider + Model

This makes it easier to change models, providers, or deployment configuration without rewriting application behavior.

API Accuracy

The Provider API should not be represented as though every provider exposes the same public Python class with identical methods. The current architecture is centered on:

Provider implementations
Provider registration
Provider discovery
Provider-model identifiers
Agent provider configuration
Provider-specific capabilities

Applications should verify the current provider implementation contract before building custom integrations. This documentation intentionally avoids assuming unsupported APIs such as:

Provider(...)
provider.generate(...)
provider.chat(...)
provider.complete(...)
provider.stream(...)
project.provider(...)
agent.set_provider(...)

unless those methods are explicitly present in the installed implementation.

Best Practices

Select providers through the provider:model configuration.
Keep credentials in environment or secret-management systems.
Choose models based on actual application requirements.
Test provider configuration before production use.
Account for provider-specific capabilities.
Avoid unnecessary vendor-specific logic in agents.
Handle provider failures explicitly.
Keep provider integrations modular.
Monitor provider latency, limits, and availability.
Do not assume all providers support identical model features.

The Provider API works closely with:

Agent
AgentResult
Tool
Memory
Knowledge
Workflow
Provider Registry

Together these components separate model communication from agent behavior, tool execution, retrieval, memory, and workflow orchestration.

Summary

The Provider API is the abstraction layer between BindAI agents and external AI model services. The current architecture uses registered provider implementations and provider:model identifiers to select the model service used by an agent. Supported providers currently include OpenAI, Anthropic, Google Gemini, Groq, Ollama, and OpenRouter. This separation allows BindAI applications to remain modular and portable while still accommodating provider-specific capabilities and differences.

​Provider API Reference

​Overview

​Provider Selection

​Supported Providers

​Configuring a Provider

​Provider Registry

​Provider Bootstrap

​Request Lifecycle

​Provider Responsibilities

​Authentication

​Environment Configuration

​Model Selection

​Streaming

​Structured Output

​Tool Calling

​Provider and Memory

​Provider and Knowledge

​Provider and Workflows

​Provider Errors

​Provider Independence

​Performance Considerations

​Custom Providers

​Provider Packages

​Security

​Testing Providers

​Provider Configuration and Agent Logic

​API Accuracy

​Best Practices

​Related APIs

​Summary