Skip to content

Model Setup

Every place Promptise takes a model — build_agent(model=...), .superagent and .agent files, promptise mcpcast --model, the CLI — takes it in one of three forms:

Form Example
Model(...) in code — credentials explicit Model("gpt-4o", provider="azure", deployment="chat-prod", endpoint=..., api_key=..., api_version=...)
A provider:model string — credentials from .env / environment "azure:chat-prod", "openai:gpt-5-mini"
A model: block in a .superagent / .agent file provider: azure / model: gpt-4o / deployment: chat-prod

Nothing to install per provider — pip install promptise reaches all of them. This page gets you to a working model; the full reference — every word of Model, Azure AI Foundry in depth, every provider's section, custom and self-hosted endpoints, failover, per-node models — is Agent → Models & Providers.

Two minutes to a working model

1. Pick the provider and see what it needs. Nothing set yet:

$ promptise models check azure:chat-prod
azure:chat-prod → azure_openai:chat-prod  (Azure OpenAI (OpenAI models deployed in Azure AI Foundry))
  model part: chat-prod — in the string form, your DEPLOYMENT name (Foundry → Deployments → Name); with Model(...), the model name (gpt-4o) — the deployment goes in deployment=
  route: native integration (core)
  AZURE_OPENAI_ENDPOINT: MISSING — Azure AI Foundry portal → your resource → Overview → Endpoint (https://<resource>.openai.azure.com/, no path)
  AZURE_OPENAI_API_KEY: MISSING — Azure AI Foundry portal → your resource → Keys and Endpoint → KEY 1 (or Entra ID: pass extra={'azure_ad_token_provider': ...})
  OPENAI_API_VERSION: MISSING — the REST API version your deployment supports, e.g. 2024-10-21 (Azure docs → 'API version lifecycle')
  Azure routes requests by deployment name, not model name: Model('gpt-4o', provider='azure', deployment='chat-prod', ...).
Not usable yet.
  - AZURE_OPENAI_ENDPOINT is not set — Azure AI Foundry portal → your resource → Overview → Endpoint (https://<resource>.openai.azure.com/, no path) (e.g. https://my-resource.openai.azure.com/)
  - AZURE_OPENAI_API_KEY is not set — Azure AI Foundry portal → your resource → Keys and Endpoint → KEY 1 (or Entra ID: pass extra={'azure_ad_token_provider': ...})
  - OPENAI_API_VERSION is not set — the REST API version your deployment supports, e.g. 2024-10-21 (Azure docs → 'API version lifecycle') (e.g. 2024-10-21)
  - put AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, OPENAI_API_VERSION in a .env file next to your script (loaded automatically; a variable already exported with a non-empty value wins, an empty one is filled from the file), export it, or pass it in code: Model(..., endpoint=, api_key=, api_version=) — see promptise models env azure

2. Give it the values — in .env, or in code.

promptise models env <provider> prints the lines, with a note on where each value is found in the provider's console:

promptise models env azure >> .env    # then fill in the values

$ promptise models env azure
# Azure OpenAI (OpenAI models deployed in Azure AI Foundry) — model string example: azure:chat-prod
export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
#   ↳ Azure AI Foundry portal → your resource → Overview → Endpoint (https://<resource>.openai.azure.com/, no path)
export AZURE_OPENAI_API_KEY=...
#   ↳ Azure AI Foundry portal → your resource → Keys and Endpoint → KEY 1 (or Entra ID: pass extra={'azure_ad_token_provider': ...})
export OPENAI_API_VERSION=2024-10-21
#   ↳ the REST API version your deployment supports, e.g. 2024-10-21 (Azure docs → 'API version lifecycle')

from promptise import Model, build_agent

agent = await build_agent(
    model=Model(
        "gpt-4o",                                         # the model
        provider="azure",
        deployment="chat-prod",                           # Foundry → Deployments → Name
        endpoint="https://my-resource.openai.azure.com/", # your resource → Overview → Endpoint
        api_key="...",                                    # your resource → Keys and Endpoint
        api_version="2024-10-21",
    ),
    servers=...,
)

A value given in code counts as provided — nothing needs to be in the environment. Every word is explained in Models & Providers → In code: Model.

3. Check again, then ping. Without --ping the check covers configuration only — the key is set, not that it works. --ping makes a real one-token call:

$ promptise models check openai:gpt-5-mini --ping
…
Configuration OK.
Pinging… ok — replied 'ok'

For a local model (Ollama, or an endpoint= on localhost) the check also connects to the server and fails with nothing is listening at http://localhost:11434 — is Ollama running? when it is down.

Every provider at a glance

Provider provider= Environment variables (exact names) Model(...) words Route
OpenAI openai
also gpt		 OPENAI_API_KEY
OPENAI_BASE_URL (optional)		 api_key=, endpoint= native (core)
Azure OpenAI azure
also azure_openai, azure-openai, azureopenai, aoai		 AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_API_KEY
OPENAI_API_VERSION		 deployment=, api_key=, endpoint=, api_version= native (core)
Azure AI Foundry model catalog foundry
also azure_ai, azure-ai, azureai, ai-foundry		 AZURE_INFERENCE_ENDPOINT
AZURE_INFERENCE_CREDENTIAL		 api_key=, endpoint=, api_version= OpenAI-compatible, URL built from the words
Anthropic Claude anthropic
also claude		 ANTHROPIC_API_KEY api_key=, endpoint= native (core)
Google Gemini gemini
also google_genai, google, google-genai, genai		 GOOGLE_API_KEY / GEMINI_API_KEY api_key=, endpoint= OpenAI-compatible: https://generativelanguage.googleapis.com/v1beta/openai/
Google Vertex AI vertex
also google_vertexai, vertexai, google-vertex, gcp		 GOOGLE_CLOUD_PROJECT
GOOGLE_CLOUD_LOCATION (optional)
GOOGLE_OAUTH_ACCESS_TOKEN (optional)		 api_key=, endpoint=, region=, project= OpenAI-compatible, URL built from the words
Amazon Bedrock bedrock
also aws, amazon		 AWS_DEFAULT_REGION / AWS_REGION
AWS_BEARER_TOKEN_BEDROCK		 api_key=, endpoint=, region= OpenAI-compatible, URL built from the words
Ollama ollama
also local		 OLLAMA_HOST (optional) endpoint= OpenAI-compatible, URL built from the words
Cohere cohere COHERE_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.cohere.ai/compatibility/v1
DeepSeek deepseek DEEPSEEK_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.deepseek.com/v1
Fireworks AI fireworks FIREWORKS_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.fireworks.ai/inference/v1
Groq groq GROQ_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.groq.com/openai/v1
Hugging Face Inference Providers huggingface
also hf		 HF_TOKEN / HUGGINGFACEHUB_API_TOKEN api_key=, endpoint= OpenAI-compatible: https://router.huggingface.co/v1
Mistral AI mistral
also mistralai		 MISTRAL_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.mistral.ai/v1
NVIDIA NIM nvidia
also nim		 NVIDIA_API_KEY api_key=, endpoint= OpenAI-compatible: https://integrate.api.nvidia.com/v1
OpenRouter openrouter OPENROUTER_API_KEY api_key=, endpoint= OpenAI-compatible: https://openrouter.ai/api/v1
Perplexity perplexity PPLX_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.perplexity.ai
Together AI together TOGETHER_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.together.xyz/v1
xAI Grok xai
also grok		 XAI_API_KEY api_key=, endpoint= OpenAI-compatible: https://api.x.ai/v1

Nothing to install for any row: pip install promptise covers every provider. native=True opts into a provider's own LangChain integration when you have it installed.

Where next

Learn the concept