ai block creates an embedded @frogbotai/gateway instance when FrogBot starts. Local operations use AI SDK v7 against that in-process gateway, so no separate proxy service is required. To limit each user’s models and monthly spend, add the AI policy plugin.
Configure providers
Add at least one provider. Set a provider totrue to use its SDK’s standard environment credentials.
openai, anthropic, google, bedrock, vertex, groq, mistral, cohere, togetherai, fireworks, deepinfra, xai, perplexity, cerebras, voyage, replicate, typesafe-ai, openrouter, and vercel. See TypeSafe AI setup for its server-side credential and evaluation-only models.
Model IDs use <provider>/<model>, where <provider> is the exact key you used under ai.providers, such as bedrock/... or togetherai/.... Replicate’s apiKey maps to its apiToken option. Bedrock uses bearer tokens first, then explicit SigV4 keys, then the AWS default credential chain.
Use { apiKey: process.env.CUSTOM_KEY } only for an alternate credential. Explicit keys must be non-empty. Bedrock accepts true, { region }, paired { accessKeyId, secretAccessKey, sessionToken? } overrides, or a custom credentialProvider. In Node.js, the default chain supports AWS profiles and IAM Identity Center, web identity, ECS task roles, and EC2 instance profiles. Install the optional @aws-sdk/credential-providers peer dependency to use this fallback. Edge runtimes must provide an edge-compatible credentialProvider instead.
Vertex AI serves Gemini and Claude through one vertex entry, using Google Cloud Application Default Credentials (ADC) instead of an API key:
vertex/gemini-3.5-flash and Claude as vertex/claude-sonnet-4-6. vertex: true reads the project and location from GOOGLE_VERTEX_PROJECT and GOOGLE_VERTEX_LOCATION. Locally, ADC uses the credentials from gcloud auth application-default login. In deployment, it uses the attached service account or workload identity, so no key file is needed. Pass googleAuthOptions, such as { keyFilename } or { credentials }, to use another identity. ADC needs Node.js, so the vertex provider doesn’t run on edge runtimes. Before calling Claude, enable each Claude model for the project in the Vertex AI Model Garden, accepting Anthropic’s terms there, and make sure the project has quota for it in the Claude location.
Add an OpenAI-compatible endpoint with any non-built-in key. Its models list is required for validation, and calls use the custom key as the provider prefix.
internal/legal-summary-v2. The chat model picker labels it Legal Summary, and its reasoning selector offers Default, Low, and High; built-in models take their names and reasoning levels from the model catalog. Built-in provider entries accept an optional models allowlist to restrict their catalog IDs; this is different from a custom provider’s required model definitions.
A provider’s models list decides what the app can use, while an agent’s model.options decides what users can pick for that agent.
AI options
Built-in provider options
Passtrue to use the provider’s standard environment credentials, or an object:
Bedrock provider options
Passtrue to use bearer tokens or the AWS default credential chain, or an object with region, explicit keys, or a credentialProvider:
Vertex provider options
Passtrue to read the project and location from the environment, or an object with both:
An
apiKey or any other key fails startup: Vertex API keys (express mode) don’t work for Claude, and the google provider already takes a Gemini API key.
Custom provider options
Custom model options
Add aliases
Routers are pure aliases from a stable slug to one model ID.hidden exists on RouterConfig but is reserved for future admin integration.
Router options
Local operations, agents,
defaultModel, and smallModel resolve aliases, and the chat manifest advertises the model behind a transcriptionModel alias; the mounted gateway HTTP routes expect provider-prefixed model IDs.
Choose a utility model
FrogBot uses a small chat model for internal work such as naming new chats. By default, it chooses a recent low-cost model from the same provider as the active agent model. If no catalog candidate is available, it uses the active model. SetsmallModel to pin these calls to a configured model or alias:
Call operations
Call methods on aFrogBot instance or req.frogbot. Text generation accepts either prompt or messages, never both. Messages are sent to the model as given; only agent turns prepare attachments for the model.
Shared options
Text generation options
generateText and streamText accept these options. Text generation uses the AI SDK v7 option names.
streamText also accepts these callbacks:
Embedding options
embed takes a single value; embedMany takes values.
Image options
Speech options
Transcription options
Video options
Rerank options
Each method returns the result from its AI SDK v7 counterpart.
streamText performs asynchronous access and hook setup, so await it before consuming textStream or another result stream.
Evaluate state
Usefrogbot.evaluate() to ask named boolean, choice, and score questions about shared state. Configure ai.providers['typesafe-ai'] with a server-side key first; TypeSafe AI setup covers the options. State, instructions, and criteria can contain structured JSON.
result.rounding records that precision. When provided, confidence for choice and score questions is separate from their answer probabilities at result.providerMetadata?.typesafe?.confidence. Evaluation uses the AI SDK’s experimental API, which may change in patch releases.
typesafe-ai/jev is FrogBot’s shorthand for upstream jev-latest; typesafe-ai/jev-latest also works. Local router slugs can target either model, while HTTP requests use provider-prefixed IDs.
Evaluate options
evaluate accepts the shared options plus:
Question options
Request output
AI SDK v7 handles structured data throughgenerateText and an Output specification. Read the validated value from result.output; there is no generateObject method.
Output.text, Output.array, Output.choice, and Output.json through the same Output object.
Control access
Configure access by operation category. Each rule receives{ req, model }, where model is the model ID or alias slug the caller asked for. Every category defaults to Boolean(req.user).
FrogBot runs the matching rule before every AI operation and HTTP request. A rule that returns
false rejects the call with AIAccessError (status 403). To send your own status and message, throw an error with a numeric status and a code; HTTP routes return it as { error: { message, type: code } } with that status.
Chat also runs the generate rule for each of an agent’s models when a signed-in user lists agents or picks a model. A model whose rule returns false or throws an error with a numeric status is hidden from that user, a request without a model uses the agent’s default if allowed or else the first allowed model, and an agent with no allowed model is hidden and rejects their requests.
An in-process call with req enforces access unless overrideAccess: true is set. A server-side call without req bypasses access by default, since there is no user to check.
The AI policy plugin builds on these rules to limit each user’s models and monthly spend. Replace it with your own rules, such as credits, on the same seam.
Observe calls
Register arrays of hooks for the five-phase lifecycle. FrogBot creates one lifecycle for each direct operation, local agent run, agent HTTP call, and mounted/api/v1/* request.
All phases share
requestId, operation, startedAt, mutable context, and mutable otel. The per-phase arguments match the gateway hook phases. FrogBot adds these fields to every hook argument:
FrogBot executes
beforeOperation and afterOperation and does not pass them into the embedded gateway. It passes only beforeUpstream, afterUpstream, and afterError to createGateway.
Gateway HTTP handlers continue to execute upstream hooks inline. In-process model resolvers execute them around the returned model’s doGenerate, doStream, or equivalent calls.
Mutate messages, params, headers, and providerOptions in place during beforeUpstream; system and tools are read-only. afterUpstream, afterError, and afterOperation isolate hook failures so later hooks still run.
Access failures happen before the lifecycle and run no hooks. A thrown beforeOperation stops the call before an operation lifecycle is returned, so afterOperation does not run for that failure.
Trace calls
Telemetry is enabled by default and registers@ai-sdk/otel when that optional peer dependency is installed. Set a deployment ID or add span attributes without replacing FrogBot’s defaults.
deploymentId defaults to FROGBOT_DEPLOYMENT_ID, then local. When @ai-sdk/otel is absent, registration quietly does nothing.
enrichSpan receives:
Call over HTTP
The standalone server mounts the embedded gateway at/api/v1. Canonical /api/v1/* requests are authenticated through frogbot.auth, and requests without a resolved user receive 401 before reaching the gateway.
Use @frogbotai/sdk in browser and application clients. AI methods use the SDK’s configured base URL, headers, and fetch, so cookie and bearer authentication wrappers apply without separate AI credentials.
transcribe returns parsed transcription JSON. chat returns the raw Response so the caller can consume either JSON or an SSE stream. speech returns the audio as a Blob; leave out voice to use the provider’s default.
Each accepted request gets one FrogBot lifecycle around the gateway handler. FrogBot runs the operation hooks, while the gateway handler runs the configured upstream hooks inline.
Pass credentials accepted by your configured auth collection. HTTP bodies use provider-prefixed model IDs because router aliases are resolved by FrogBot’s local operation layer, not by the gateway handler. After authentication, mounted operation routes run the matching
ai.access rule with the body’s model. A denied request receives 403 with { "error": { "message": "...", "type": "permission_error", "code": "permission_denied", "param": null } }, or the status and code of an error the rule throws, in the same four-field body; on /api/v1/messages errors use Anthropic’s { "type": "error", "error": { "type", "message", "param" } } shape; GET /api/v1/models lists only the models the caller may use: each model is checked with the ai.access rule for its kind (generate for chat, image, speech and video models; embed, transcribe, rerank or evaluate otherwise), and a model whose rule returns false or throws an error with a status is left out. Keep the TypeSafe upstream key on the server; clients authenticate to FrogBot instead. See the evaluation JSON contract for a request and response shape.