Production Agent Advisor

The Initiative cockpit uses a bounded Agent Advisor. It makes one model request when a Facilitator asks for a question, a gate evaluation, or intervention suggestions. It does not run an autonomous agent loop and it cannot change an Initiative without a Facilitator action.

Vercel AI Gateway

The production API can use Vercel AI Gateway through its OpenAI-compatible endpoint. Set these variables on the Vercel project that hosts Modeller.Api:

Agent__BaseUrl=https://ai-gateway.vercel.sh/v1
Agent__Model=openai/gpt-5.4-mini
Agent__TimeoutSeconds=30
Agent__MaxOutputTokens=1200
Agent__MaxPromptCharacters=24000

By default, the public cockpit requires a caller key. A model can be enabled for anonymous use with Agent__FreeModel, but only after two checks:

1. The live Gateway catalogue lists the exact model with the free tag and no token price.
2. The Vercel team has paid Gateway credits. Vercel blocks restricted free models for teams that have not moved to the paid-credit tier.

For example, Agent__FreeModel=alibaba/qwen3.8-27b met the first check on 17 August 2026 but returned HTTP 403 on the free Vercel tier. Do not set it until the account meets both checks. When enabled, the API authenticates anonymous requests with the deployment's short-lived OIDC token and does not let the browser select a different model.

A Facilitator can enter their own Vercel AI Gateway API key to use the configured premium model. The page keeps the key only in component memory and sends it in the X-Agent-Api-Key header for explicit AI actions. The API does not put it in Redis, logs, analytics, URLs, or the Initiative record.

Keep automatic Gateway credit top-up disabled. Model prices and availability can change. If the configured free model stops being free, remove Agent__FreeModel and redeploy; the cockpit will then require caller keys.

Apply the non-secret variables to Production and Preview only where AI access is required, then redeploy the API.

openai/gpt-5.4-mini is the initial production choice because the advice is short and structured. The model remains an environment setting so it can change without a code deployment.

Cost and request controls

• The API limits each model response to 1,200 tokens.
• The API rejects Initiative prompts over 24,000 characters before it calls the provider.
• The API cancels a model request after 30 seconds.
• Configure a small AI Gateway budget and leave automatic top-up disabled until normal usage is known.
• Review usage by model in the AI Gateway dashboard. The API records model, endpoint, status, duration, and token counts through tracing. It does not record prompt or response content.

Failure and recovery

The cockpit shows whether the Agent Advisor is available. If it is not configured, AI controls are disabled and all manual paths remain available. A provider error appears as an initiative.agent.* error and does not change the Initiative.

To recover:

1. Check the API deployment logs for the HTTP status and trace. Do not log or paste prompt content.
2. Check AI Gateway usage, credit balance, and model availability.
3. Confirm Agent__BaseUrl and Agent__Model. If anonymous free access is enabled, also confirm the live price and Agent__FreeModel.
4. Change Agent__Model to another available text model if needed, then redeploy.
5. Remove Agent__BaseUrl to disable AI safely while manual facilitation continues.

For local development, use .NET user secrets or a local environment file that Git ignores. Automated tests use fake HTTP handlers and need no provider credentials.