Guide
Learn to build agents, connect tools, and use your projects in conversations and applications.
Start here
Agent Studio is a platform for prompt, agent, and image projects. Read this guide without signing in. To start a conversation, sign in and choose an existing agent in Chats; to build your own, follow the steps below.
1. Sign in and check your access
Open the address provided by your organization and use the sign-in method shown. Profile shows your tier, usage, and limits. New accounts normally start as guest; if project creation is unavailable, ask an administrator to change your tier in Members.
2. Create a small first project
In Projects, choose New project, enter an identifier and display name, and choose a type. For a first test, use llm for a prompt template or agent for a conversational assistant. Start with a short task whose expected answer you can judge before adding tools.
3. Save, run, and inspect
In Playground, select an available model and write the instructions. Save the version, enter a test input, and run it. Check the answer, warnings, usage, and tool activity. Run uses the saved version, so editing without saving does not test your new settings.
4. Publish and connect
Publish the tested version from Versions. For an HTTP caller, issue a project token in Integrations and follow API Reference. Publishing selects a default version; it does not create a separate application or freeze the configuration.
Choose the project type
A project groups versions, visibility, integrations, and usage under one identifier. A version holds the model, prompts, capabilities, and execution limits. Choose the type for the output and workflow you need.
llm: a prompt template
Use llm for summarization, classification, or rewriting in one model response. Put placeholders such as {{topic}} in the user prompt template and supply their values when running it. A system prompt sets the standing instructions. This type does not call tools or continue a tool loop.
agent: conversation and tools
Use agent when a task requires conversation, searches, tool calls, or delegation. Write its role, task boundaries, and expected output in the system prompt, then send the task as a message. The model chooses whether to use the tools made available to it; enabling a tool does not guarantee a call.
image: generation and editing
Select an image generation model and describe the desired picture. Attach source images to edit them; without source images, the project generates a new picture. The system prompt supplies a recurring style. Test in Playground or Compare, and call the predict API for integration. Chats and chat completions do not run image projects.
Configure, compare, and publish versions
Treat a version as a named, editable configuration. For an experiment, choose + New version in Playground's version selector: it copies the current editor contents, and Save creates the new version. Use this path when callers already depend on the current configuration.
Model and fallback
Select a model that supports the task: tool calling for agent projects, image input for reading pictures, or image generation for an image project. For llm and agent projects, configure a fallback model if needed. A fallback still needs the capabilities required by the request; it cannot make an incompatible model read an image.
Preview and save are different
Use Prompt preview to inspect the prompt assembled from the current draft. It does not generate an answer, but a supplied request can call memory recall, contact MCP servers, and call embedding/rerank services for dynamic discovery. Save before using the run panel: its request executes the saved version. An agent receives user messages directly; llm template variables are not an agent input mechanism.
Control run size
Set output length, agent turn limits, and other parameters exposed by the editor to match the task. Turn and output limits can end a run with a partial answer; a deployment deadline can stop it with an error. Read the completion reason and warnings before accepting the output. Reasoning trace controls the displayed reasoning, not whether the model reasons.
Compare with the same input
Save the candidate version, open Compare, choose two saved versions, and run the same input. Compare answer quality, warnings, duration, and usage. Both sides make real calls and count toward usage and concurrency limits; the comparison is not a free preview.
Understand what changes after Publish
In Versions, Publish points the project default at the selected version. Requests using published follow that pointer; requests naming a version keep using that name. Saving changes to a published version affects its next run immediately. To revert the default, publish a known good version; named-version callers must be updated separately.
Add skills, tools, and other agents
Administrators register capabilities on Skills, Tools, Agents, and Plugins. Project owners bind the available entries to a version, save, and test a task that needs them. Registration alone does not expose every capability to every run.
Skills: reusable instructions
Have an administrator create the skill on Skills with a clear description, then bind it in the version editor. The model initially sees the name and description and can load the full instructions when needed. Use skills for repeatable procedures and domain guidance, and verify that the task actually causes the intended skill to be loaded.
MCP: discover and select tools
Have an administrator register the server on Tools and check that discovery lists the expected tools. Bind the server to the version, select the tools to expose, and save the version. If calls fail, inspect the server status, required headers, and run warnings. A reachable server can still return no usable tools or require authorization.
MCP connection settings have different scopes
Tool selections and header overrides belong to the version and require its Save action. OAuth Connect, Disconnect, and OAuth client credentials belong to the project and are saved separately; all its versions share that connection. Complete authorization before testing a tool that requires OAuth.
Delegate to another agent
Bind a published local project or an external agent registered on Agents. External registrations use an OpenAI-compatible or A2A endpoint and its credentials. Give each delegate a description that makes its role clear. Delegated activity is labelled by author, while its usage remains part of the originating run's accounting.
Import and synchronize plugins
An administrator imports skills and MCP definitions from a configured repository or an uploaded checkout archive in Plugins. Use archive upload when the repository is unreachable. Inspect skipped/invalid entries and bind imported capabilities to your version. Imported skill content and MCP URLs/descriptions are maintained at the source and synchronized again; configure credentials separately in the console, because MCP headers are not imported. Sync does not delete orphaned entries automatically; review and remove them explicitly from its results.
Dynamic discovery and memory
Dynamic discovery matches the system prompt and current request against capability names and descriptions, then adds relevant skills, MCP servers/tools, and external agents without changing saved bindings. A precise description is the routing signal: say when the capability should be used and what it returns. It needs a working capability catalog and embedding setup; ask an administrator if results are missing. Memory recall is separate and needs a bound MCP server offering recall.
Image generation, URL reading, and files
Enable the built-in capabilities needed by the version, such as image generation, URL reading, or Slack history. Their provider, network access, or bot setup must also be available. SaveFile is offered automatically when artifact storage is configured and lets an agent produce downloadable text files. Inspect generated files before using or sharing them.
Conversations and attachments
Chats keeps conversations with agent projects. Use Playground for configuration tests and Chats for continuing work over multiple messages.
Choose the agent and version behavior
Start a new chat and select an accessible agent project. Chats uses the published version when one exists, otherwise the latest saved version. llm and image projects are not chat choices. Publishing or editing a version can therefore change the behavior of later turns in an existing conversation.
Conversation history has limits
The thread retains messages and tool activity, but the model receives a bounded history. A long conversation or large tool result can be shortened and produce a warning. Older images may remain visible in the thread without being sent in a later turn; attach the relevant image again when needed. Restate essential constraints and start a new conversation when the task changes substantially.
Images and documents
Attach PNG, JPEG, GIF, or WebP images to a model that supports image input. Text and PDF documents are extracted into text; Office and similar document formats need a bound MCP read_document tool. Check the attachment control for size and count limits and resolve unreadable-file errors before sending. Stored chat documents preserve extracted text, not an archive of the original file.
Closing the page does not stop a chat run
Use the chat's stop control to request cancellation. Navigating away or closing the browser tab only disconnects the view; reopen the conversation to read the saved result. Cancellation cannot undo actions a tool has already completed. A server interruption can still prevent an active run from finishing.
Call a project over HTTP
API Reference is built into each project and fills in its address and published version. It contains request fields, response shapes, error codes, and curl or SDK examples. Use it alongside the steps here; no source checkout is needed.
Prepare the project and credential
Publish a tested version so execution examples appear. The owner or an administrator issues the token in Integrations; the owner's tier must allow API tokens. Replace $PROJECT_API_TOKEN in the example with that token and send Authorization: Bearer <token>. It is a project credential, not the LLM provider key, and it only runs that project.
Choose a fixed version or published
Execution URLs use /api/projects/{name}/versions/{version}/ followed by the endpoint. The generated examples name the version currently published. Keep that name to target it explicitly, or use published to follow future Publish changes. Confirm the host is the Agent Studio address reachable from the calling system.
Match the input to the project type
For llm predict, send variables matching the user prompt template, such as {"variables":{"topic":"meeting notes"},"stream":false}. For agent predict, send messages, such as {"messages":[{"role":"user","content":"Summarize these notes"}],"stream":false}; variables are ignored. For image predict, send prompt and optionally source images for editing. Begin with a non-streaming request and inspect its response.
OpenAI-compatible clients
Use chat/completions for llm and agent projects and copy the Python or JavaScript example from API Reference. Set the SDK base URL to the version's URL shown there and the API key to the project token. The saved version selects the model and sampling parameters; sending model, temperature, or max_tokens does not override them. Image projects use predict instead.
Streaming and conversation history
For text predict or chat/completions, stream:true returns SSE; agent also provides an endpoint for streaming text and tool activity. Keep the connection open and handle warning, error, and completion events, because HTTP 200 alone does not prove the run succeeded. HTTP callers send their own message history. X-Conversation-Id can preserve downstream MCP/A2A conversation identity, but does not load past messages for you.
Check the result and protect the token
Inspect usage, warnings, and the completion reason as well as the answer. turn-limit or output-limit on predict means a partial result; chat completions reports length for limit stops. Download file results before their links expire. Keep tokens in the calling server's secret storage. Regenerating or revoking a project token invalidates the old token immediately, so update every caller.
Bots, protocols, and automation
Project owners and administrators configure integrations. Publish a version first and verify one real call after setup. External platforms need their own credentials and network connectivity; they are optional in an offline installation.
Slack
For an agent project, copy the app manifest from Integrations, create and install the dedicated Slack app, and save its bot token and signing secret. Enable events, check the displayed events URL, and run Test connection. Invite the bot to the target channel and mention it. A successful credential test does not prove Slack can deliver events to the application.
Telegram and Teams
In an agent project's Integrations, save and enable the Telegram bot token; enabling registers its webhook. Use Register webhook again after an application URL change. For Teams, enable the Azure Bot's Teams channel, save its application ID and client secret (plus tenant ID for a single-tenant app), and set its messaging endpoint to the displayed URL. Test in a direct conversation before trying group mentions.
A2A and AG-UI
A2A exposes published public projects to compatible agents; administrators configure shared or named client keys in Settings, and callers use X-A2A-Key. Check the Agent Card URL in Integrations. AG-UI runs a published project inside your own interface using the project token. Copy its client example from Integrations and let your application manage the message thread and render protocol events.
Receive a webhook
In project Settings, configure and enable the webhook, copy its URL, and send the secret in X-Trigger-Secret. Choose message payload mode for an agent message or variables mode for template fields. HTTP 202 acknowledges delivery, not a finished answer; inspect the trigger's run history for success, output, skips, or failures. Concurrent deliveries are skipped unless allowed.
Schedule a recurring task
In project Settings, add a schedule with a five-field cron expression, an IANA time zone such as Asia/Seoul, and the message or variables to run. Select any delivery destinations and enable it. Schedules use the published version and require the deployment's external ticker. Check both run status and delivery results: a generated answer can succeed even when sending it to a bot fails.
Results, usage, and limits
Find and retain generated files
Personal Artifacts lists your results. Project Artifacts is for the owner and administrators and includes results from bots and automation too. Storage must be configured for persistent files. Reopen the artifact view to refresh an expired download link, and download files you need to retain. Deleting an artifact can break earlier links; deleting a chat does not automatically delete its artifacts.
Understand usage and attribution
Use project Usage to inspect the selected period and model/provider breakdown; owners and administrators can inspect caller details. Profile shows personal usage. Project-token calls are accounted to the project rather than the owner's personal budget. Prices come from provider-reported cost or catalog pricing; a zero estimate is not proof that the provider charged nothing.
Alerts, blocks, and concurrent runs
Project Settings separates daily/monthly alert and block thresholds. Alerts notify when a destination is configured; blocks refuse new runs until the UTC day or month resets, even without notifications. Personal tier limits and caller concurrency limits also apply where relevant. Costs can arrive after a run finishes, so thresholds are not a prepaid balance that guarantees no overspend.
Investigate a run in Traces
Owners and administrators can open project Traces to inspect preparation, model calls, tools, delegates, durations, usage, and warnings. Traces is a diagnostic record, not a complete archive of prompts and tool output. Agent runs are traced, while llm and image tracing can be sampled. A missing trace can also mean the request was refused before execution started.
Access and sensitive data
Choose access rules before sharing a project or connecting data sources. The console, model provider, tools, and file store are separate places where information may be processed.
Public, private, and editing rights
A public project is accessible to signed-in users of this installation; it is not anonymous access to every API. Private projects limit access to the owner, invited emails, and administrators. Invitations allow viewing and running, not editing. Owners and administrators manage versions, settings, integrations, traces, and project-wide artifacts. Machine credentials have their own access rules.
Secrets and shared links
Do not put API keys in prompts, skill text, browser code, screenshots, or support messages. Use the dedicated credential fields. A masked value is a display placeholder, not a working key to copy. Treat signed artifact links as credentials: someone holding a link may read the file until it expires. If a token leaks, revoke or regenerate it and update its callers.
PII filtering is a limited protection
A version's PII filtering replaces recognized patterns before sending model text and restores them in user-facing output. It is not complete anonymization: restored information can appear in tool arguments, saved answers, reasoning, and files. Discovery embedding/rerank queries and memory recall queries are outside this filter. Use approved model and tool services for sensitive work.
Private services need explicit network access
Ask the deployment operator to allow the specific internal DNS suffix when a legitimate internal service is blocked. MCP servers use MCP_INTERNAL_HOST_SUFFIXES; URL reading uses URL_FETCH_INTERNAL_HOST_SUFFIXES. They are different settings. A declared host must still be reachable and authorized; an allow entry does not supply credentials or open a firewall.
Administrator settings
Members, Settings, Models, and Audit serve different purposes. Changes here can affect multiple projects, so verify the affected path after saving. Registry pages are available to members and administrators; creating and maintaining their entries is an administrator task.
Manage member tiers
In Members, find the user and change the tier when they need project creation or API-token access. Profile is where the user checks their resulting limits. Administrators listed in ADMIN_EMAILS have a fixed admin tier; removing an email from the list does not automatically demote its stored tier. Members is not an account-creation or password-reset screen.
Settings overrides and deployment values
Settings manages the public base URL, artifact access mode, access lists, LLM channels, plugin repository, and A2A credentials. Saved values override deployment environment values, which override defaults. Saving an empty field removes that override and falls back to the environment; for a secret, this is not a guarantee that the service becomes disabled. Database, encryption, sign-in provider, storage connection, retention, and internal-host settings remain deployment configuration.
Connect and verify models
Configure the default LLM or provider channel URL and credentials in Settings, including the API base path required by the endpoint. When changing a URL, enter its matching key too; the old masked key cannot be reused for a new destination. In Models, inspect capabilities and availability, run Test, then run a short project. A catalog entry describes a model; it does not install or serve it.
Catalog and retrieval in an offline deployment
Upload a model catalog document in Models when remote synchronization is unavailable. Use Self-hosted declarations for models actually served by your internal endpoint. Capability discovery requires CATALOG_ENABLED=true in the deployment and a working embedding setup; rerank is optional. Changing embedding requires rebuilding the index. Unknown model IDs follow the deployment's allow/refuse policy and may lack cost estimates.
Choose how users reach artifacts
Set PUBLIC_BASE_URL to the application's user-facing address. In Settings, proxied artifact access sends bytes through the application and suits a store that browsers cannot reach. authenticated returns an expiring storage URL, so browsers need direct storage access. public requires public-read storage policy and lets anyone with the URL read it. Validate by generating, reopening, and downloading a file from a user's network.
Review administrative changes
Use Audit to inspect the selected date range, actor, action, target, and details. Credential reveal operations are recorded as well. Use these records to identify who changed configuration or accessed an issued secret, and use project Traces for execution diagnostics. Retention limits apply to both kinds of record.
Install without source code
This section is for the deployment operator. An ordinary console user only needs the application address and an account. Obtain the release image and the deployment-specific launch, secret, ingress, and backup settings from the package provider; source files and development commands are not prerequisites for using the image.
1. Prepare the services and image
Use a versioned release image, PostgreSQL with pgvector (the deployment baseline is PostgreSQL 18), and a reachable OpenAI-compatible LLM endpoint. Mirror the image into an internal registry before entering an isolated network. Add an S3-compatible object store if files must persist. The deployment owns service addresses, credentials, volumes, TLS, and routing.
2. Supply required configuration
Supply DATABASE_URL, LLM_BASE_URL, LLM_API_KEY, and AES_ENCRYPTION_KEY through the deployment's secret/configuration mechanism. AES_ENCRYPTION_KEY must encode 32 bytes in base64 and remain stable across restarts. Set STAGE explicitly (prod for production); alpha/prod also requires ADMIN_EMAILS and a sign-in method. Set BETTER_AUTH_SECRET to a stable session secret and BETTER_AUTH_URL and PUBLIC_BASE_URL to the user-facing application address in the deployment environment before configuring callbacks.
3. Configure sign-in
For offline operation, configure internal OIDC or password sign-in. OIDC needs OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET; register the application's /api/auth/callback/oidc callback with the identity provider. Password bootstrap uses AUTH_PASSWORD=true, BOOTSTRAP_ADMIN_EMAIL, and BOOTSTRAP_ADMIN_PASSWORD; include that email in ADMIN_EMAILS. Changing the bootstrap password does not reset an existing password account.
4. Connect persistent file storage
For persistent files, create a bucket and set S3_BUCKET_NAME. For a non-AWS store, also set S3_ENDPOINT, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY. AWS S3 can use the deployment's AWS credential or role configuration. Grant the storage identity read, write, and delete access to artifacts/* in that bucket. Keep non-AWS storage keys in the S3 fields rather than AWS_* variables used by other providers. Select the artifact access mode in Settings and verify downloads from the user's network.
5. Start and verify the full path
The application validates configuration and applies database migrations on startup. Check health and readiness, sign in as the administrator, test a model, and create and run a small project. If storage is configured, reopen a generated file. Test internal MCP and any enabled integrations individually; a reachable console alone does not validate them.
Operate, retain, and upgrade
The deployment operator owns monitoring, scheduled calls, backups, and rollouts. Configure these alongside the application rather than assuming that saving a console setting starts background infrastructure.
Health is not a successful model run
GET /api/health checks process liveness. GET /api/ready checks database and default LLM reachability and returns 503 when unavailable or draining. LLM reachability only requires an HTTP response, so even a 401 or 404 from its models endpoint can pass. Verify credentials and model support with Models Test and a real project run.
Run the external ticker
Set SCHEDULE_SCAN_TOKEN and configure an external scheduler to POST /api/triggers/scan with X-Scan-Token at least once per minute. Setting the token alone starts nothing. This call drives schedules and expired database-row cleanup. A missing deployment token returns 503; an absent or incorrect request token returns 401. Check scan results and trigger histories after enabling it; long outages do not replay every missed occurrence.
Refresh the capability index
If capability discovery is enabled, configure a separate hourly POST /api/catalog/reindex with the same X-Scan-Token credential. The schedule scan does not perform this reindex. A successful response starts background indexing; inspect the server log for indexed, removed, or undiscovered entries, then test a question that should discover a newly registered capability.
Database retention and file lifecycle
Set TRACE_RETENTION_DAYS, USAGE_RETENTION_DAYS, CHAT_RETENTION_DAYS, ARTIFACT_RETENTION_DAYS, TRIGGER_RUN_RETENTION_DAYS, A2A_TASK_RETENTION_DAYS, and AUDIT_RETENTION_DAYS in the deployment as needed. Keep artifact retention at least as long as chat retention. Expired rows can be excluded from reads before physical deletion; without the ticker they remain stored. Object bytes need a separate bucket lifecycle for artifacts/image/, artifacts/document/, and any legacy images/. Align file and record retention to avoid records pointing to deleted files.
Back up data and recovery keys
Back up PostgreSQL, stored objects, deployment configuration, and the encryption/session secrets under restricted access. Restore them together in a separate environment and verify sign-in, credential decryption, project runs, and file access. Losing or arbitrarily replacing AES_ENCRYPTION_KEY makes stored credentials unreadable. An application image is not a data backup.
Upgrade with a recovery plan
Record the current image version and verify backups before changing the image. Allow active runs time to drain during shutdown, then check startup migration logs and repeat the basic sign-in/run/file checks. Reverting the image tag does not downgrade the database schema. Confirm schema compatibility and the deployment's restore procedure before relying on rollback.
Troubleshooting
Start with the failing surface, the exact error, and whether the run began. Change one relevant setting at a time, then repeat the smallest request that demonstrates the problem.
Sign-in fails or a control is unavailable
Check the configured sign-in method, allowed email domain, and account with the administrator. A missing create/edit control can be a tier or ownership restriction. For API 401, check the token and project name; for 403, check current owner tier and permissions. A private or inaccessible project can return 404, so do not assume the URL alone is wrong.
A model is missing or a call fails
In Models, check hidden and availability states and run Test. Ask the administrator to confirm the provider URL, base path, credentials, and model ID, then save the intended model in the project version. For 400, compare the request fields and image/tool requirements with API Reference. For provider errors such as 502, inspect the reported upstream error; retrying unchanged does not fix a wrong model or URL.
429, timeout, or an incomplete answer
For 429, inspect concurrent runs, project daily/monthly blocks, and personal tier usage; follow Retry-After on API responses. For a timeout or stream error, inspect the provider, slow tools, and deployment deadline. For turn-limit, output-limit, or length, narrow the task or adjust the saved version's appropriate limit. Avoid blind retries when a tool may already have changed external data.
A tool or memory is not used
Confirm the capability is bound to the saved version and visible in Prompt preview. Check tool selection, discovery, OAuth connection, and run warnings. Ask a question that actually requires the tool. For internal-host blocks, involve the deployment operator; for memory, verify a bound server offers recall. A document reader must be explicitly bound, not merely discoverable.
A bot or schedule is silent
Check the published version, integration enabled state, credentials, and callback reachability. Test a direct bot message or explicit mention. For schedules, also check enabled state, cron time zone, and the external ticker. Inspect skipped/failed runs and delivery results in project Settings; a successful model run with a failed destination is a delivery problem.
Attachments or downloads fail
Check supported file type and upload limits first. An image needs a model that can read it; an Office document needs the bound reader tool. For generated files, inspect storage warnings and reopen Artifacts to refresh the link. If the console opens but files do not, have the operator check the artifact access mode, public base URL, browser-to-storage connectivity, and retention policy.
What to send for support
Record the application version, project and saved version names, surface, time and time zone, error/status code, trace ID if available, and a minimal input that reproduces the issue. Include what you expected and whether the failure occurs in Playground too. Remove tokens, cookies, private file links, and sensitive content. Installation-specific startup and recovery problems belong with the deployment operator or package provider.