Cloud providers

Overview

MagOneAI supports major cloud LLM providers with native integration. Configure your API keys in the Admin Portal, and start using models immediately across your organization.

Cloud providers offer:

• No infrastructure management — pay per token, no servers to maintain
• Latest models — access to cutting-edge capabilities as they're released
• Scalability — handle any volume without capacity planning
• High availability — provider-managed uptime and redundancy

This guide covers OpenAI, Anthropic, and Google Gemini in full. The three newer providers have pages of their own, linked from the table below.

Choosing a provider

When you add an LLM configuration, the Provider picker shows seven options in two groups.

Direct APIs

You reach the model vendor's own API with a key from that vendor.

Cloud and self-hosted

You reach a model through a cloud platform you already pay for, or through a server you run.

OpenAI configuration

OpenAI provides the widely-used GPT family of models, including GPT-5, GPT-4o, and the reasoning-focused o-series.

Reasoning models

GPT-5 and the o-series behave differently from chat models at the API level, and MagOneAI handles the differences for you rather than making you configure around them.

• temperature and top_p are stripped. OpenAI rejects both on reasoning models. The gateway removes them before the request goes out, so a config carrying them still works instead of erroring.
• max_tokens becomes max_completion_tokens. Renamed for every reasoning model, whether or not thinking is on, because these models require the newer field.
• A minimum output budget is enforced when thinking is on. If max_completion_tokens is unset or below 4096, it is raised to 4096. A reasoning model can otherwise spend its whole budget on the scratch pad and return nothing visible, so a tight cap fails silently rather than loudly. This means a configured max_tokens of 500 becomes 4096 in the request.
• Thinking maps to reasoning_effort. Setting thinking_enabled and thinking_effort on an agent translates to OpenAI's reasoning_effort parameter.
• Reasoning tokens are counted separately. These models report a reasoning_tokens figure alongside normal completion tokens, and the platform logs it. That is the quickest way to confirm the model actually spent effort thinking rather than answering straight away.
• Prompt caching is accounted for. OpenAI reports cached input under cached_tokens. Because OpenAI's prompt_tokens already includes the cached portion, input token counts are left as reported rather than double-counted.

Setup steps

Azure OpenAI

Azure OpenAI is configured as an OpenAI-compatible provider — there is no separate Azure provider type. Point the endpoint at your Azure deployment URL, including the ?api-version=... query string Azure requires:

https://mycompany.openai.azure.com/openai/deployments/gpt-4o?api-version=2024-02-15-preview

MagOneAI preserves any query parameters already on the endpoint when it appends /chat/completions (and /models), so the api-version param survives every request rather than being silently dropped. Store the Azure key in Vault exactly like any other OpenAI-compatible key.

Function calling

All OpenAI models support native function calling. When you attach tools to an agent using an OpenAI model, MagOneAI automatically formats tool definitions in OpenAI's function calling format and processes tool calls from the model's responses.

Vision support

GPT-4o and GPT-4o-mini support vision. Send images as part of the input:

• Image URLs (must be publicly accessible or signed URLs)
• Base64-encoded images
• File uploads processed by MagOneAI

Against the native OpenAI API, MagOneAI can hand the model an image by URL directly, avoiding a re-download; when a direct URL isn't usable it falls back to sending the image inline as base64. Anthropic and Gemini always receive images as base64 — the gateway downloads any URL image first before calling those providers.

Vision models can:

• Extract text from documents (OCR)
• Understand charts and diagrams
• Answer questions about images
• Describe image content

Use vision models for document processing, visual QA, and multimodal workflows.

Cost considerations

Model pricing changes often enough that repeating it here would mislead more than it helps. Check OpenAI's pricing page for current rates, and set the real per-token cost on each model in its LLM Config so usage analytics reflect what you actually spend.

Optimization tips:

• Use GPT-4o-mini for simple tasks; it is substantially cheaper than GPT-4o
• Reach for a reasoning model only when the task genuinely needs extended thinking. Reasoning tokens are billed as output, so a model that thinks hard costs more than the response length suggests
• Within the GPT-5 family, step down to mini or nano before stepping outside it

Anthropic configuration

Anthropic provides the Claude family of models, known for their extended context windows and strong reasoning capabilities.

Setup steps

Function calling via "tool use"

Anthropic models support function calling through their "tool use" feature. It works the same as OpenAI's function calling from an application perspective — models can call tools during reasoning.

Anthropic's tool use is often praised for:

• Accurate tool parameter generation
• Intelligent tool selection
• Strong reasoning about when tools are needed vs when to answer directly

Extended context windows

All Claude models support 200K token context windows, significantly larger than most other models. Some Claude models offer experimental 1M token context.

Use cases for extended context:

• Process entire codebases or long documents
• Maintain conversation history over many turns
• Include extensive reference materials in every request
• Avoid context summarization and loss of detail

Note: Extended context is powerful but expensive. Only include necessary context.

Cost considerations

Model pricing changes often enough that repeating it here would mislead more than it helps. Check Anthropic's current pricing, and set the real per-token cost on each model in its LLM Config so usage analytics reflect what you actually spend.

Optimization tips:

• Use Claude Haiku for simple tasks (much cheaper than Sonnet/Opus)
• Use Claude for extended context needs instead of multiple smaller requests

Google Gemini configuration

Google provides the Gemini family of models with strong multimodal capabilities and competitive pricing. MagOneAI integrates with Gemini natively using a Google AI Studio API key.

Setup steps

Function calling

Gemini models support native function calling. Google's function calling implementation is compatible with OpenAI's format, making integration straightforward.

Multimodal capabilities

All Gemini models are natively multimodal, supporting:

• Text input and output
• Image understanding
• Audio understanding (select models)
• Video understanding (select models)

Gemini excels at:

• Document analysis with complex layouts
• Video content understanding
• Cross-modal reasoning (e.g., "Describe what's being said in this video")

Extended context — up to 2M tokens

Gemini 2.5 Pro supports 2 million token context, the largest available from any major provider. This enables:

• Processing entire books or documentation sets
• Analyzing hours of video content
• Maintaining extremely long conversation histories
• Including massive reference materials

Cost note: 2M tokens of context is expensive even at Google's pricing. Use extended context judiciously.

Cost considerations

Model pricing changes often enough that repeating it here would mislead more than it helps. Check Google's current pricing, and set the real per-token cost on each model in its LLM Config so usage analytics reflect what you actually spend.

Optimization tips:

• Use Gemini Flash for long-context tasks (very cheap compared to alternatives)
• Leverage native multimodal capabilities instead of separate OCR + LLM pipeline
• Use Gemini Pro when you need the 2M context window

API key management

All provider API keys are stored in HashiCorp Vault with military-grade security.

How API keys are stored

Key reference format

In configuration files and UI, API keys are referenced by Vault path, never stored directly:

vault:openai/api_key
vault:anthropic/production_key
vault:google/gemini_key

This ensures:

• Keys never appear in logs
• Configuration files can be version-controlled safely
• Keys can be rotated without updating configurations

Rotation without disruption

To rotate an API key:

1. Generate new key from provider (OpenAI, Anthropic, Google)
2. Update the key in Vault at the existing path
3. Existing workflows continue with no disruption
4. (Optional) Revoke old key from provider after confirming new key works

No agent configurations or workflow definitions need updating.

Usage tracking and costs

Monitor model usage across all cloud providers in the analytics dashboards.

What's tracked

• Token usage — input tokens and output tokens per provider, org, and project
• Per-token cost — when you set input/output cost per 1k tokens on a model, usage analytics surface token-based cost
• Latency — response times by provider and model

Usage analytics

Usage and cost analytics appear in the analytics dashboards — see the Admin Portal.

View:

• Token usage over time — daily, weekly, monthly trends
• Usage by provider, organization, and project
• Per-token cost for models that have cost configured

Quotas

MagOneAI enforces token-based quotas (daily, weekly, and monthly) at the org, project, use-case, and user scope. When a quota is exceeded, requests are rejected with a clear error message until the quota resets or is increased.

Quotas are configured and managed on a dedicated surface — see Usage and quotas.

Best practices

Troubleshooting

Next steps