Skip to content

The AI gateway

A builder that needs a model, an agent, a generator that asks for help, a fix-up pass, does not have to hold a model credential of its own. With the AI gateway, which arrived in builder protocol version 2, it sends the call to Studio. Studio runs it on the AI providers the organization configured under Settings > AI, and records the tokens.

This page is the contract. The cratis build run --ai studio option of the Cratis CLI implements it, and presents it to agents as the OpenAI and Anthropic APIs they already speak. See Run the Cratis builder locally. A builder that talks to Studio without the CLI implements the request below.

  • Usage is counted where the organization counts it. Every call lands in the organization’s usage under the provider and model that answered, beside the calls Studio makes itself.
  • Pooling and limits apply. The agent and provider pool the organization chose for code generation decide which model answers, and a provider that is rate limited stops being picked.
  • No credential on the builder’s machine. A build server, a container or a laptop needs only the builder’s own token.
  • Every builder gets it the same way. The protocol carries the call, so the packaged Cratis builder, the Axon builder, an Eventmodelers builder and a builder you write all use the same endpoint.

The gateway belongs to protocol version 2. A builder names 2 in the protocolVersions of its hello. When the agreed protocolVersion in the welcome is 2 or higher, the gateway is there. A builder that agreed version 1, because it or Studio is older, must not call it, and one that needs it should stop and say so rather than fall back to a credential of its own.

POST /work/<sliceId>/ai/chat
Authorization: Bearer <builderId>.<token>
Content-Type: application/json

The call is made for a slice the builder holds, under the same credential and with the same refusals as a lease renewal: once the lease is lost, or the build was cancelled, the call is refused with 410 Gone. The body is at most 4 MiB.

{
"orderId": "6f0c3d5e-2b1a-4f7e-9a51-0d2c8e4b7a10",
"messages": [
{ "role": "system", "text": "You complete method bodies." },
{ "role": "user", "text": "Complete PlaceOrder.Handle." },
{
"role": "assistant",
"toolCalls": [ { "id": "call-1", "name": "read_file", "arguments": { "path": "PlaceOrder.cs" } } ]
},
{ "role": "tool", "toolCallId": "call-1", "text": "public class PlaceOrder { }" }
],
"tools": [
{
"name": "read_file",
"description": "Reads a file of the project.",
"parameters": { "type": "object", "properties": { "path": { "type": "string" } }, "required": ["path"] }
}
],
"maxOutputTokens": 8192,
"temperature": 0.2
}
Member Required Meaning
orderId yes The order being built
messages yes The conversation so far, at most 400 messages. A role is system, user, assistant or tool
messages[].text no The text of the message
messages[].toolCalls no On an assistant message: the tool calls the model made, each with an id, a name and arguments as an object
messages[].toolCallId with tool On a tool message: the id of the call the text answers
tools no The tools the model may call, at most 64: a name, a description and parameters as a JSON Schema object
maxOutputTokens no At most 32768. Defaults to 8192
temperature no Between 0 and 2

200 OK:

{
"message": {
"role": "assistant",
"text": "I will read the file first.",
"toolCalls": [ { "id": "call-2", "name": "read_file", "arguments": { "path": "PlaceOrder.cs" } } ]
},
"finishReason": "toolCalls",
"model": "claude-sonnet-5-5",
"usage": { "inputTokens": 1204, "outputTokens": 86 }
}

finishReason is stop when the model is done, toolCalls when it wants the builder to run the tools in message.toolCalls and ask again with their results, or length when the answer was cut at maxOutputTokens. usage is what the provider reported; a count the provider did not report is null. Studio does not stream: the answer comes whole.

The builder runs the tool loop. Studio never runs a tool for it, and never sees the project.

Status Body When
400 { "reason": "…", "problems": ["…"] } The request cannot be read. problems names each one
401, 403 { "reason": "…" } The credential is unknown, removed, declined or still awaiting approval, as everywhere in the protocol
410 { "reason": "…" } The builder does not hold that slice, or its lease is lost. Stop building
502 { "reason": "…" } The AI provider could not answer. Ask again in a moment
503 { "reason": "…" } The organization has no AI provider configured. Ask a maintainer to configure one under Settings > AI

The call is attributed to the organization, as code generation, and counted in its AI usage in tokens and cost per provider and model. Studio does not keep the messages. The builder’s token is never part of a call to a provider, and no provider credential is ever sent to the builder.