AG Studio is provider-agnostic - it does not bundle a connection to any LLM. The adapter is the seam between Studio and your provider. You implement the AgAiAssistant interface, which translates between Studio's request format and your chosen LLM.
The example below ships a complete OpenAI adapter. Copy it as a starting point and adapt it to your provider.
The AgAiAssistant Interface Copy Link
The adapter is a plain object. Its one required method is executeTurn.
Execute a single turn of conversation with the AI. A turn consists of sending input and receiving a streamed response.
|
The set of agents the active runtime runs — each agent is instructions + tools + a delegation graph. When omitted, the built-in runtime uses AG's default agents. Supply your own (compose with agStudioDefaultAgents to keep AG's) to fully control the set. This is orchestration policy interpreted by the active runtime: the built-in runtime runs these as its agents; a custom runtime may own its own agents and ignore this field.
|
Type of the agent the conversation starts from. Defaults to 'lead'. Interpreted by the active runtime alongside agents.
|
The agents and primaryAgent fields configure the agents the built-in runtime uses - see Custom Agents.
executeTurn Copy Link
executeTurn is called each time Studio needs an AI response. It receives an AgAiRequest and must return an AgAiResponseHandler synchronously. The handler exposes a live stream and a completion promise.
The Request Copy Link
Each call to executeTurn receives everything the model needs for one turn.
Conversation history to send to the AI, providing context.
|
System instructions for this specific turn, overriding defaults.
|
Tools available for the AI to use during this turn.
|
Strategy for how the AI should choose tools. |
Output format configuration controlling response structure.
|
The Response Copy Link
executeTurn returns an AgAiResponseHandler - a stream of incremental events and a complete promise that resolves with the final response.
Async iterable of stream events for real-time updates. Events are yielded as they arrive from the AI provider.
|
Promise that resolves when the response is fully complete. Contains the final, consolidated response data.
|
Stream Events Copy Link
The stream yields AgAiStreamEvent values. Each has a type and an event discriminator:
| Type | Event | Description |
|---|---|---|
status | created | The provider has created the response object. |
status | in_progress | The model is actively generating. |
status | completed | Generation finished. Includes the final AgAiResponse. |
status | failed | Generation failed. |
error | api, network, timeout, etc. | An error occurred. Includes code and message. |
item | added | A new output item (message, tool call, reasoning) started. |
item | done | An output item finished. |
part | added | A content part within an item started. |
part | done | A content part finished. |
delta | update | Incremental content to append. |
delta | done | Final content for a part. |
Tool Calls Copy Link
The adapter does not execute tools. It only:
- Passes the
AgToolSchema[]inrequest.toolsto the LLM. - Relays the tool-call output items from the LLM back through the stream.
The runtime intercepts those tool calls, executes them, and feeds the results back as function_call_output items on the next turn. Your adapter never needs to know what view_schema or configure_widget do.
Keeping Keys Off the Client Copy Link
executeTurn runs in the browser, so calling a provider directly exposes your API key. For production, point executeTurn at your own backend endpoint instead: forward the AgAiRequest, call the provider server-side with your secret key, and stream the response back. The adapter contract is unchanged - only the URL it calls differs.
Interface Reference Copy Link
Unique identifier for this response.
|
Timestamp when the response was created (milliseconds since epoch).
|
Error details if the response failed.
|
Details about why the response was incomplete. Present when the AI couldn't fully complete its response.
|
Output items produced by the AI (messages, tool calls, reasoning).
|
Current status of the response.
|
Tool name.
|
Human-readable description for the LLM.
|
JSON Schema describing the tool's parameters.
|
Next Steps Copy Link
- Module Setup - Register the module and show the panel.
- Default Agents - The agents and tools the runtime drives.