AI Studio and AI agent platform

AI Studio is the in-product Gluesync AI workspace. Use it to chat with governed Spark agents, publish reusable AI assets, run immutable agent versions, route work across customer-managed models, and control programmatic access and spend.

Overview

AI Studio sits alongside Query Studio and the embedded Core Hub MCP server:

  • Settings → LLM providers stores encrypted BYO provider credentials for OpenAI, OpenAI-compatible endpoints, Anthropic, Azure OpenAI, and Ollama, optional token prices, and estimated spend for the current month.

  • AI Studio (/ai-studio) has five workspaces: Chat, Build & publish, Runs, Models & routing, and Governance & developer API.

  • Settings → AI agents (MCP) remains a separate surface for connecting external MCP clients (for example Cursor, Claude Desktop, or Windsurf) to the embedded Core Hub MCP server. It is not replaced by AI Studio.

In the Control Plane UI, the AI Studio side-navigation item is shown when the signed-in user has Query Studio read capability. Without that capability, /ai-studio is not offered and navigates away to Pipelines.

Configure LLM providers

Bring-your-own credentials live under Settings → LLM providers (OpenAI, OpenAI-compatible endpoints, Anthropic, Azure OpenAI, Ollama). Super admins administer the vault; managers can review providers and estimated spend.

For fields, cloud egress, Ollama bind addresses, Docker/localhost pitfalls, and connection tests (tool calling required), see AI models and LLM providers.

  1. Open Settings in the Control Plane.

  2. Open the LLM providers tab.

  3. Super admins select Add provider to connect a model.

The table lists each saved provider with its Name, Provider type, Default model, Credential status, and estimated spend for This month. Super admins also get Test connection, Edit provider, and Delete provider.

Estimated spend

The tab shows This month per provider and a footer Estimated spend this month.

  • Totals come from Core Hub (GET /ai-studio/usage/summary) for the current calendar month in UTC.

  • Cost is estimated from input/output token counts reported by each provider, using either a bundled catalogue price or the optional per-provider override. It will not match the vendor invoice exactly.

  • Amounts below one cent are shown as less than $0.01 so light usage is not rounded to free.

  • Completions that cannot be priced (unknown model and no override) are tagged Partly unpriced. Set input and output prices on that provider to include them.

  • Ollama is treated as zero-priced in the bundled catalogue.

  • Providers with no chat usage in the month show No usage. Providers deleted mid-month still appear in the recap under the name recorded at call time.

Who can see and manage providers

  • Settings → LLM providers is visible to Super admin and Manager. Viewer and Monitor never see the tab: they may still chat in AI Studio when they have Query Studio read capability, but spend and credentials stay out of reach.

  • Managers use the tab read-only: review configured providers and follow estimated spend. They cannot add, edit, test, price, or delete a provider.

  • Super admins administer the vault (credentials, prices, connection tests, model refresh, add/edit/delete). Core Hub provider write APIs match that rule.

  • Agent create / edit / delete controls in AI Studio are Super admin only.

  • Authorized users who can open AI Studio (Query Studio read capability) may still chat with agents that a Super admin has already configured.

You cannot delete a provider that is still linked to an AI Studio agent. Remove or reassign the agent first.

Use AI Studio

  1. From the side navigation, open AI Studio (/ai-studio).

  2. If no LLM provider exists yet, follow Open LLM provider settings and add one.

  3. Select New / Create agent.

Agent settings

Field Notes

Name

Required.

LLM provider

Required. Choose a configured provider from Settings → LLM providers.

System prompt

Required instructions for the agent.

MCP tool allow-list (toolAllowList)

Multi-select of Core Hub MCP tools the agent may call. The Control Plane loads this catalog from Core Hub (GET /ai-studio/mcp/tools) — the same embedded MCP tool set, not a forked catalog. The agent can call only the tools selected here. Persist/API field name is toolAllowList.

The editor reminds you that each tool call still uses the current user’s Core Hub permissions (the caller’s bearer token is forwarded through existing Core Hub MCP/REST authorization).

Spark agent use cases

The Build & publish workspace surfaces five starter patterns for chat agents:

  • Query — inspect connected data with approved query tools and return a structured answer.

  • Automate — publish immutable agent versions and run them through the durable run API.

  • Report — send INFO, WARNING, or CRITICAL notifications through Core Hub webhooks and SMTP email, including configuration, tests, delivery logs, and on-demand reports. See Core Hub MCP server for send_webhook_notification and send_email_notification.

  • Route — preview model policy decisions before a real run spends tokens.

  • Investigate — use read-only pipeline, notification, metric, and log tools to explain what happened.

Chat and tool traces

  • Send messages in the studio chat composer.

  • The chat header Model picker lists configured LLM providers (shown as model · name). The agent’s default provider is used unless you pick another for This conversation only.

  • Core Hub returns chat results with a toolCalls array (name, arguments, result, isError). The Control Plane maps those calls into the AI Studio Tool traces pane (inputs/outputs as rendered in the UI).

  • Conversations are persisted for admin testing and audit on Core Hub.

Build and publish reusable assets

The Build & publish workspace separates authoring from execution. A Manager or Super admin can publish skills and agent versions. Published versions are immutable; make a change by publishing a new version instead of editing an existing snapshot.

Skills

A skill is reusable behavior referenced by one or more published agents. Its stable lowercase slug and positive version identify an immutable manifest.

Field Purpose

Purpose

INSTRUCTION, TOOL_BUNDLE, or KNOWLEDGE.

Instructions

Text appended to an agent’s system instructions at run time.

Input and output contracts

JSON Schema objects that describe the skill boundary.

Required capabilities

Model capabilities needed by the skill.

Tool capabilities

Tool names requested by the skill.

Approved resources and provenance

Optional references and source or ownership metadata.

The 2.3 runtime executes TEXT-only published agents. You can publish instruction and knowledge skills, but an agent version that references a tool bundle, declares capability bindings, or requires a non-TEXT capability is rejected. Tool-enabled published runs and run approvals are not available in this runtime.

Published agent versions

A published agent combines:

  • a stable slug and server-assigned monotonically increasing version;

  • system instructions and exact skill-version references;

  • a routing policy with model/provider allow-lists and required capabilities;

  • an optional JSON output contract;

  • maximum steps, duration (1 second to 1 hour), and optional estimated-cost limit;

  • publisher, publication time, and a content hash.

The Craft with Spark helper can draft or improve system instructions from a behavior brief. It uses an enabled vaulted provider, records provider usage, and adds an audit event. Review and edit the proposal before inserting it into the agent editor; insertion does not publish it.

Run published agents

The Runs workspace starts asynchronous executions and keeps their state and evidence in Core Hub.

  1. Select a published agent.

  2. Optionally pin a version; leave it empty to use the latest version.

  3. Enter the run input as JSON.

  4. Optionally provide a duplicate-protection key and correlation ID.

  5. Start the run, then open it from Recent runs.

Run status progresses through QUEUED, ROUTING, and RUNNING, then ends as SUCCEEDED, FAILED, CANCELLED, or AMBIGUOUS. WAITING_APPROVAL is reserved for a future tool-capable runtime. The detail view shows the immutable agent version, selected model, routing decision, redacted error, input, output, correlation ID, and ordered event timeline.

Idempotency and ambiguous outcomes

Supply an idempotencyKey in the request or an Idempotency-Key HTTP header when callers may retry run creation. The namespace is the authenticated owner or platform API key:

  • the same key with the same agent version and canonical JSON input returns the existing run;

  • the same key with different content returns 409 Conflict;

  • an AMBIGUOUS provider outcome is not retried automatically. Verify the provider outcome before deciding whether to create new work.

Active runs can be cancelled. The event stream is Server-Sent Events (SSE), accepts Last-Event-ID or after, and closes after terminal events have been delivered or after approximately two minutes; reconnect with the last sequence to continue.

Runs cannot be replayed in place. To repeat terminal work, create a new run and use a new idempotency key.

Manage models and preview routing

The Models & routing workspace is the model-gateway view over the providers in Settings → LLM providers.

Canonical model catalog

A canonical model records its provider and upstream model name, capabilities (TEXT, TOOLS, JSON, VISION, STREAMING), context window, token prices, residency, health, observed latency, and quality, reliability, and locality scores.

Sync providers creates or refreshes provider-backed catalog entries and removes entries for disabled or deleted providers. Provider-backed models currently default to TEXT, a 128,000-token context window (32,768 for Ollama), and the configured or bundled token price. Synced health starts as HEALTHY; it is catalog metadata, not a live provider probe. Use the separate provider connection test to check current reachability. Only a Super admin can sync, directly edit, or delete canonical models.

Deterministic routing

Routing preview evaluates a workload without calling a provider. It filters out models that violate model/provider allow-lists, required capabilities, minimum context, residency, health, price, or estimated-cost constraints. Eligible models are ranked deterministically by weighted quality, cost, latency, reliability, and locality; a model ID breaks a score tie.

The preview shows the selected model, ranked fallback candidates, and the inclusion or exclusion reason for every candidate. The fallback list explains the routing order; 2.3 does not automatically replay a failed provider request against every fallback.

Governance and developer API

The Governance & developer API workspace combines usage visibility with access and spend controls.

Usage and audit

For Super admins, the overview summarizes completion count, input and output tokens, and estimated cost for the current month. Usage is an estimate based on provider-reported tokens and configured or catalog prices. The audit tab records administrative and execution actions with owner, resource, result, timestamp, and a safe detail. Other roles cannot read these global usage and audit endpoints.

Budgets

A Super admin can assign a time-bounded budget to an owner or a platform API key. A policy can define:

  • soft and hard estimated-cost limits;

  • request, input-token, and output-token limits;

  • a policy name and optional cost center.

The platform reserves estimated usage before invocation. Crossing a soft limit allows the request with a warning; crossing a hard or volume limit rejects it with 402 and code BUDGET_EXCEEDED. API-key budgets take precedence over an owner budget for requests authenticated by that key.

Platform API keys

Platform keys begin with gsa_ and are intended for applications and automation. Only a Super admin can create, list, or revoke them. The plaintext secret is shown once; Core Hub stores its hash.

Limit each key with:

  • scopes: models:invoke, agents:invoke, and/or runs:read;

  • agent and model allow-lists;

  • requests per minute;

  • an optional expiry.

Revoked and expired keys are rejected. Runs created by an API key remain isolated to that key, and allow-lists restrict visible models, invocable agents, and visible runs.

Native agent API

The versioned base path is /api/ai/v1. The Control Plane links to the complete OpenAPI document at /api/ai/v1/openapi.yaml.

GET  /api/ai/v1/models
POST /api/ai/v1/agents/{slug}/runs
GET  /api/ai/v1/runs/{id}
GET  /api/ai/v1/runs/{id}/events
GET  /api/ai/v1/runs/{id}/events/list
POST /api/ai/v1/runs/{id}/cancel

Managers and Super admins can invoke the platform with their signed-in bearer token. Applications use a gsa_ bearer key and are restricted by its scopes, allow-lists, rate limit, expiry, ownership, and budget.

OpenAI-compatible model API

Existing OpenAI SDKs can use:

GET  /v1/models
POST /v1/chat/completions
POST /v1/embeddings
POST /v1/responses

Choose a canonical model ID or use model: "auto" for policy routing. POST /v1/chat/completions supports non-streaming JSON and SSE streaming when stream is true. For platform gsa_ keys, budgets, and SDK examples, see Use Gluesync as your AI model gateway. Function tool definitions and tool_choice are forwarded to the provider, and tool_calls are returned to your application (including in SSE deltas); Core Hub does not execute tools on this endpoint. Including tools requires a TOOLS-capable catalog model; otherwise Core Hub returns HTTP 404 (Model '<id>' is not available).

Roles and access

Role AI Studio access

Super admin

Full provider vault, chat-agent administration, model-catalog administration, published assets, runs, budgets, platform API keys, usage, and audit.

Manager

Read provider configuration and provider spend, publish skills and agents, draft instructions, and invoke and inspect runs. Cannot manage provider secrets, canonical models, budgets, platform API keys, or read global platform usage and audit.

Viewer / Monitor

May use configured chat agents when Query Studio read capability grants access to AI Studio. They cannot publish or invoke the external AI platform. Provider and governance administration remains hidden.

MCP client Settings (separate from AI Studio)

Keep using Settings → AI agents (page title AI agents (MCP)) when you want to connect an external MCP client to Core Hub:

  • Copy Streamable HTTP (/mcp/http) and SSE (/mcp) endpoints for your Core Hub origin.

  • Paste client configuration (Cursor, Claude Desktop, Windsurf, and similar) using a bearer token from Account settings.

  • Review the built-in tool catalog and open the full MCP documentation.

That Settings tab is not the BYO LLM providers screen and not the AI Studio agent builder. Full transport, configuration, and tool-catalog detail lives in Core Hub MCP server.

Gluesync Connect hosted chat

Gluesync Connect’s hosted assistant uses the hosted Anthropic metered path. It does not use the on-premises bring-your-own LLM vault.

When the assistant invokes on-prem Core Hub tools through mcp_invoke:

  • Authentication role. Connect authenticates to the selected site as the signed-in Connect user, but the on-prem Core Hub bearer always uses the MONITOR role—even when the Connect user has a higher role. The bearer token is never returned to the model or the chat UI.

  • Discovery and allow-list. Before each call, Connect requests tools/list from that site’s Hub. A tool is callable only when it is both advertised by the site and present in the hosted-chat read allow-list. Discovery or policy failures are fail-closed (the call does not proceed).

  • SQL and dynamic database tools. When execute_sql or dynamic db_* tools are advertised and allowed, Connect forces readOnly: true. SQL is limited to a single statement that is SELECT, WITH, SHOW, DESCRIBE/DESC, or EXPLAIN. Statements that use FOR UPDATE, INTO, or REPLACE INTO are blocked. Read-only SQL function forms such as REPLACE() and EXPLAIN ANALYZE SELECT remain allowed.

  • No nested catalog ask. catalog_ask is blocked inside the hosted assistant tool loop so it cannot start a nested LLM call or a second credit debit.

  • Tool activity. The chat shows and persists a Tool activity trace with tool name, site, status, and a redacted SQL summary when applicable. Traces do not include the Core Hub bearer token, raw MCP error bodies, or result rows.

  • Billing. The outer Anthropic chat turn remains the single LLM call and credit debit for that turn.

The MONITOR role and SQL readOnly enforcement described above apply to on-prem mcp_invoke into Core Hub. Do not confuse them with other Connect catalog paths.

Connect limitations

  • Connect bring-your-own LLM / vault

  • Channels or embed widget surfaces

  • Quill-style mirrored customer SQL data plane in Connect

Related