Guide
Learn to build agents, connect tools, and use your projects in conversations and applications.
Start here
Agent Studio manages Agents that answer requests and use tools. Read this guide without signing in. To start a conversation, sign in and choose an 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 and enter an identifier and display name. Start with a short task whose expected answer you can judge before adding tools.
3. Save, run, and inspect
Set a model and instructions in the Playground, save, and try a short request. Check the answer, warnings, usage, and tool activity. The Run panel uses saved settings.
4. Connect callers
Saved Agent settings are ready for Chat and configured integrations. For HTTP calls, issue a project token in Integrations and follow API Reference.
Work with an Agent
Every project is an Agent. Its current settings hold the model, system prompt, capabilities, and execution limits. Visibility, integrations, and usage belong to the project.
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 tools
Enable image tools and select an image model. Ask the Agent to generate an image, or attach a picture and request an edit. The same Agent can handle these requests in Playground, Chat, and execution APIs.
Configure an Agent
Edit the Agent’s current settings in the Playground and save them. To experiment independently, clone the project and configure the copy.
Model and fallback
Select a text model with tool calling support. Reading pictures also requires image input. Configure a compatible fallback if needed. Image generation and editing use the separately configured image tool model.
Preview and save are different
Prompt preview assembles the current draft. It does not generate an answer, but memory recall and capability discovery can contact configured services. Save before running; the Run panel uses saved settings.
Control run size
Set output length and agent turn limits to match the task. Presence penalty is an optional control for repeated tokens when the selected model supports it. Turn and output limits can leave a partial answer; a deployment deadline can stop the run with an error. Read completion reasons and warnings. Reasoning trace controls displayed reasoning, not whether the model reasons.
When saved settings take effect
The next run uses the saved settings. Each Agent keeps the settings read when it is prepared; a local subagent reads its settings when called. Queued Audio jobs retain their submission-time settings. Pending approvals reject changed settings or connections. Concurrent edits produce a conflict; reload before saving again.
Add skills, tools, and other agents
Administrators register capabilities on Skills, Tools, Agents, and Plugins. Project owners bind the available entries to an Agent, 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 Agent settings 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 Agent, select the tools to expose, and save the settings. 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 Agent settings and require Save. Refresh tools after changing headers. Masked values preserve stored secrets; clearing the map removes overrides. Administrators configure the OAuth app in Tools and owners connect the project account. A reachable tool does not prove access to its resources.
Delegate to another agent
Bind a configured local Agent or a registered external Agent when the task benefits from a specialist. Give each delegate a precise description. Delegated activity is labelled by author, with usage attributed to the originating run.
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 Agent. 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, audio, URL, and file tools
Enable image generation, audio processing, URL reading, or Slack history when needed and configure the corresponding services. With file storage configured, File reads, creates, and edits supported documents, while SaveFile creates text files. Audio uses a private source store and a separate worker. Document processing itself is built in and needs no MCP binding.
Conversations and attachments
Chats keeps conversations with agent projects. Use Playground for configuration tests and Chats for continuing work over multiple messages.
Choose an Agent
Start a chat and select an accessible configured Agent. Each new turn uses its current saved settings; changes can affect later turns in an existing conversation.
Conversation history has limits
Display messages and the model’s encrypted SDK Session are separate. The Session supplies bounded prior turns, tool results and recent images; Memory is an optional long-term source. Omitted history produces a warning. If the Session has expired, visible messages are not rebuilt into model history. Restate essential constraints when starting again.
Images and documents
Attach PNG, JPEG, GIF, or WebP images to a model that supports image input. PDF, UTF-8 text, DOCX, XLSX, PPTX, HWP 5.x, HWPX, ODT/ODS/ODP, and RTF are read by the built-in document engine. Attach up to four documents of 10 MiB each. The conversation retains bounded extracted text; configured storage also keeps the originals. Check extraction and storage warnings after sending.
Create a new document
In an agent conversation, ask “Create a DOCX report from these notes” or “Make an XLSX budget table.” DOCX, PDF, PPTX, HWPX, and XLSX creation is built in. Plain text, Markdown, CSV, JSON, HTML, and SVG use SaveFile. File tools require configured storage. Download the result from the response and review its contents and layout. HTML previews run immediately in an isolated frame. Stop and Restart control execution; preview changes are not saved to the original.
Edit an attachment and keep the original
Attach the source, then ask “Inspect this document and change the heading to Quarterly results” or “Set Summary!B2 to 150.” DOCX, PPTX, and HWPX support selected text changes; XLSX supports cell changes; UTF-8 text supports unique substring replacement. The agent inspects targets and returns a new file. Follow-up requests can use the original or revised file.
Know the editing limits
Reading a format does not guarantee editing it. PDF, HWP, ODT/ODS/ODP, and RTF have no source-preserving editor. Signed documents and macro workbooks are rejected for editing. Document text edits cannot add paragraphs or line breaks, and formulas are not calculated. Text changes may alter layout; review the downloaded result. Extracting text and rebuilding a document does not preserve its original formatting.
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.
Tool approval and resuming a chat
An Agent can require approval before selected tools run. Review the agent, tool and arguments in the chat, then approve or reject. An SDK approval pauses new messages until resolved or discarded. Changing the settings or connection can invalidate a pending checkpoint. Workspace Git reviews are separate: approve the exact Git action in its Workspace; the result resumes its source chat.
Workspaces and isolated execution
A Workspace retains files and a runtime session. A Sandbox is the temporary compute that runs them. The agent chat coordinates work, while a separate Workspace view shows execution, diffs, checks and Git reviews.
1. Confirm execution is enabled
Enable Workspace tools in the Agent settings. Its Workspace tools tab manages repositories, access mode and default runtime. Select native runtime models in Settings → Models → Model usage. The operator connects the Sandbox backend and worker; skills and GitHub connections do not enable tools on their own. Signed-in members can use enabled agents or the Workspace selector in Chats.
2. Pick the task workflow
Use task skills for PR review, issue fixes, feature implementation, refactoring, dependency upgrades, CI investigation, security remediation and project generation. File conversion, data analysis and scripted automation also use Workspaces. Read-only repository investigation can use MCP without creating compute. A skill supplies instructions; the offered tools and deployment determine what can execute.
3. Continue the selected Workspace
An agent chat keeps one selected Workspace per project. Start creates it once; repeating Start returns the selection without running another task. Use Run for follow-up work and select an existing owned Workspace only when you intend to switch. The Workspace link opens a web page; file paths belong to its workdir. The home and sidebar label Chats and Workspaces separately.
4. Choose a coding runtime or an exact script
Codex, Claude and OpenCode accept complete natural-language tasks and validation instructions when configured. Command executes an exact non-interactive shell script; prose and numbered instructions are not commands. The selected runtime cannot change during Run. A task can be Git-free, including reports, file processing and experiments.
5. Prepare the repository before cloning
Register existing repositories in the project’s Workspace tools tab. There is no default repository. The default mode permits registered repositories plus new repositories created through Workspace create_repository; successful creation registers them automatically. The owner or an administrator can choose fixed repositories, selected owners or all accessible repositories. Check the returned base branch and select both repository and branch for Git work.
6. Review publication one action at a time
Commit, commit-and-push, PR creation, merge and direct main push are distinct reviews. Each approval applies only to the reviewed action and exact changes. The result returns to the originating chat, which prepares the next requested review. When CI waiting is registered for a PR, its exact HEAD is watched for up to 30 minutes and the chat resumes when checks settle. Failed checks, changed HEADs and uncertain outcomes are not permission to publish. Direct main push is fast-forward only; branch protections still apply.
7. Distinguish execution, checks and artifacts
Queued and running do not mean completed. Inspect the final run state, output and diff. Configured Workspace checks, commands run by the coding runtime, GitHub checks and deployment status are different evidence. A Workspace file is not automatically a downloadable Artifact or public preview. Report checks that could not run and use only returned Workspace, repository or Artifact links.
8. Pause, close and recover
Cancel stops the current task. Close ends compute while preserving the selected Workspace and its checkpoint; later work can restore it. Idle cleanup saves files and session state before removing the Sandbox. Checkpoint limits can prevent cleanup from completing. Deleting its Workspace chat requests cleanup and prevents resurrection. Workspace count is not the same as worker concurrency; capacity, retention and configured limits determine what can run.
Execution surfaces do not share every capability
Execution surfaces share the Agent settings. Authentication, conversation history, personal context, Workspace access, and approval interfaces follow each surface’s rules.
Chats: persistent history and approval return
The signed-in chat owner receives a persistent SDK Session and tool approval UI. Enabled Workspace actions and their CI updates return to the source chat. The Workspace runtime has its own session and files; it does not inherit all of the parent agent’s skills or account connections.
Playground and APIs: saved input, caller-owned history
Playground runs saved settings. A signed-in member can use enabled Workspace tools, but without a source Chat it cannot receive automatic approval continuation. HTTP clients supply their own history. A project API token uses a service actor and passes the owner’s email to MCP; it is not a browser session and does not enable Workspace tools or the persistent Chat approval UI.
Messengers: platform identity and replies
Slack, Telegram and Teams reply on their own platforms and use their platform actor identities. Personal MCP context is available only when that surface resolves a verified email. These bot calls do not receive the user-only Workspace builtin or the browser Chat approval UI. Configure the bot and verify delivery separately from its credential test.
Webhooks and schedules: machine actors
A valid webhook signature authenticates delivery; it does not grant the sender a personal session or Workspace access. Results go to trigger history, not a Chat. Schedules may explicitly use the current owner’s personal context for supported MCP/audio tools after rechecking authorization, but retain the schedule actor and do not gain Workspace tools. Audio postprocessing has its own restricted worker workflow.
Audio processing and personal records
One Agent can handle collection, transcription, summaries, and requested records with reusable skills. A separate worker continues long jobs after the Agent response or browser page ends.
Enable audio tools
Ask an administrator to configure private file storage, transcription, and the audio worker. Enable Audio processing tools in the Agent settings. The project owner can then use the Audio processing tab.
Keep one Agent and reusable skills
With the workspace plugin, bind audio-processing for the workflow, meeting-minutes for summaries, and personal-records for requested Document or Memory storage. Keep the system prompt short. Connect the recording source to this Agent and authenticate there. Separate download, transcription, and recording agents are not required.
Choose processing settings
Choose a transcription model, language, retention, and an optional postprocessing Agent, then save. Each submitted job keeps a snapshot of the current postprocessor and destination settings. Later edits apply only to new jobs.
Start a job or schedule collection
Upload an audio file on the project page, or ask the Agent to collect a recording through its connected tool. For recurring collection, configure a schedule with a search range and maximum number of new recordings. Enable Run with my personal context as the owner. The worker and schedule ticker must be running; turning on audio tools alone does not schedule anything.
Read private Artifacts
Original audio, transcript JSON, summary Markdown, speaker dialogue, and structured results appear as the selected stages finish. Open them from the job or Artifacts. A submitted or duplicate request may still refer to an unfinished job: check the job status. Completed remains completed even when its last stage says Cleaning intermediate files. Review names, numbers, missing passages, and unknown speakers.
Save to Memory or Documents only when requested
The default result is private Artifacts. Specify which Artifact to save and whether you want a personal Document or Memory. The Agent reads that result and checks the destination service response. For unattended collection, leave the external destination empty. Saving a personal record does not delete the Artifact; the destination service has its own retention policy.
Retry without starting completed stages again
A waiting job resumes automatically. For failed jobs or jobs needing attention, fix the cause and use Retry. A manual retry starts a new 24-hour execution window while keeping completed stages, record IDs, and the original file expiry. Cancellation does not undo external records already created. A deleted or expired source may require a fresh import.
Deleting files is not a processing reset
Deleting Artifacts removes their files, but completed job history and duplicate-prevention records remain. To repeat one recording, explicitly ask the Agent to reprocess it. A full project reset is an administrator maintenance operation: pause scheduling, wait for active work to stop, and clear job history and duplicate-prevention records together. There is no reset-all button on this page.
Call a project over HTTP
API Reference is built into each project and fills in its address. 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
Save the tested Agent settings and issue a project token in Integrations; the owner’s tier must allow API tokens. Send it as Authorization: Bearer <token>. It is scoped to that project’s execution, uses a service actor and passes the owner’s email to bound MCP servers. Treat it as access to those configured tools, not as a browser login or a way to obtain Workspace tools.
Use the Agent address
Execution URLs start with /api/projects/{name}/ and use the Agent’s current saved settings. Send the task in messages. Use the Agent Studio host reachable from the calling system.
Send the task as messages
Send {"messages":[{"role":"user","content":"Summarize these notes"}],"stream":false} to predict. Include supported inline image parts when needed. Images are generated or edited by the Agent’s image tools. Begin with one request and inspect its answer, warnings, and usage.
OpenAI-compatible clients
Use chat/completions and the Python or JavaScript examples in API Reference. Set the SDK base URL to the project address and the API key to its token. Saved Agent settings determine the model and sampling parameters; model, temperature, and max_tokens do not override them. Set PROJECT_API_TOKEN and CONVERSATION_ID in the calling process environment before running the examples.
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. Inspect token totals in collected OpenAI responses or the Studio Usage page.
Bots, protocols, and automation
Project owners and administrators configure integrations. Save the Agent settings 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 cards for configured public projects; a configured shared or named key can call the addressed project, including private projects under the key’s contract. AG-UI embeds Agent runs in your interface using its project token. Supply the message history and render protocol events in that client; neither protocol creates a browser Chat or Workspace approval UI.
Receive a webhook
Enable the project webhook in Settings. Generic callers send X-Trigger-Secret; GitHub uses the same secret to sign X-Hub-Signature-256. The JSON payload becomes a user message. HTTP 202 acknowledges delivery; check Trigger history for execution and skipped runs. With overlap disabled, deliveries arriving during a run are skipped.
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 to run. Select any delivery destinations and enable it. Schedules use the current Agent configuration 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 originals and generated files
Personal Artifacts includes files attributed to your email, including personal-context automation. Project Artifacts also includes outputs without a personal owner. Private audio originals and results can only be read or deleted by their owner. Reopen an ordinary artifact to refresh an expired signed link; this does not restore an expired or deleted file. Download files you need beyond retention. Deleting a chat does not 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 inspect preparation, model calls, tools, delegates, durations, usage, and warnings in project Traces. Every Agent run is traced; prompts and tool output are not stored in full. A missing trace can mean the request was refused before execution started or the trace could not be stored.
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 Agent settings, integrations, traces, and project-wide artifacts. Machine credentials have their own access rules.
Secrets and shared links
Saved keys display four characters at each end; values of eight characters or fewer remain hidden. Replace opens a separate draft, and clearing or cancelling the draft keeps the saved key. Reset to environment explicitly removes a settings override. Studio-issued project, Webhook and A2A credentials share Show, Hide, Copy and supported generation or revocation controls. Copy appears only while plaintext is shown; replacement and revocation require confirmation. Browser preferences do not store credentials. Treat signed artifact URLs as credentials too.
PII filtering is a limited protection
The Agent’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.
Settings overrides and deployment values
Settings groups General, Plugins, Models and Keys. General manages public access, artifact access and execution with unpriced registered models. Plugins manages the repository; Models manages provider connections and selected models; Keys manages GitHub and A2A credentials. Only changed fields are saved. Deployment settings still own the database, encryption, sign-in providers, storage and retention.
Connect and verify models
In Settings → Models → Providers, register the provider type, a unique connection name, its API base URL and key. Self-hosted connections use the same flow and may omit a key. A changed credential destination requires a matching new key. In Model usage, choose the default, Workspace and search models from registered compatible models.
Browse, select and maintain models
Model selection always loads the provider’s complete list. Compare output types, independent Tools/Vision/Reasoning badges, context limits and prices; sort by name or price. Add model registers immediately. Selected models only narrows the view and allows deletion; Registered models offers editing and availability checks. Provider, search, filters and ordering are remembered in this browser. Models is the read-only list of saved selections. A successful listing does not prove that inference will succeed; verify with a short project run.
Catalog and retrieval in an offline deployment
Saved models and internal provider connections work without the public internet. Bundled published metadata only fills missing facts; it does not register models. The deployment operator can refresh that metadata from a local catalog file. Capability search requires an enabled search service and a registered embedding model; rerank is optional. Changing embedding rebuilds the index. Unregistered models are always refused; General controls whether registered models with unknown prices may run.
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 Agent Studio
This section is for the deployment operator. Console users need the application address and an account. Obtain the release image and the deployment-specific launch, secret, ingress, and backup settings from the package provider.
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 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. Model connections are registered after sign-in. 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 Keycloak, standard OIDC, or password sign-in. Keycloak needs KEYCLOAK_ISSUER (the realm URL), KEYCLOAK_CLIENT_ID, and KEYCLOAK_CLIENT_SECRET; register /api/auth/callback/keycloak with the client. Standard OIDC uses OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET with /api/auth/callback/oidc. Google can be enabled alongside either provider using GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. 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/* and source-files/* in that bucket, plus multipart upload permissions for private files. 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 schema migrations on startup. Check health and readiness, then sign in as the administrator. In Settings → Models, register a provider connection and the models to use, then choose the default model in Model usage. Create and run a small project. If storage is configured, reopen a generated file. Test internal MCP and each enabled integration.
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
Database retention settings control trace, usage, chat, artifact, trigger, A2A, and audit rows. Keep ordinary artifact retention at least as long as chat retention and configure matching object lifecycle rules. Private audio files use their own day or calendar-month expiry, inherited by derived outputs and enforced by the audio worker. Do not apply blanket object expiration to source-files/ in the shared Artifacts bucket: deletion barriers must remain. Deleting or expiring audio Artifacts does not clear job history or duplicate-prevention records.
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 app and worker image versions and verify backups before deployment. Prepare any data migration required by the target release and stop the app and workers while applying it. Keep the HTTP app, audio worker and Workspace worker on compatible schemas and configuration, and supply the matching Sandbox image. Recheck sign-in, runs, files and approval continuation. Recovery uses a compatible image and database backup. Retain current and recovery images; clean unused caches when disk capacity requires it.
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
Check the selected model in Models. In Settings → Models, reset filters, discover the provider’s complete list, and use Registered models to edit or check availability. Confirm the provider URL, base path, key and exact model ID before saving the Agent configuration. For 400, compare the request and image/tool requirements with API Reference. For upstream errors such as 502, inspect the reported error; repeating a wrong model or URL does not fix it.
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 settings'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 settings 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
A webhook 202 may mean accepted, duplicate, disabled, busy, no Agent configuration or ping; inspect the response and trigger history. GitHub uses its Secret field to produce X-Hub-Signature-256, while generic callers use X-Trigger-Secret. A successful delivery does not grant Workspace execution. Schedules require a running ticker; Workspace approval/CI continuation requires its worker. Check each result at the surface that owns it.
Attachments or downloads fail
Check the file type and upload limits first. An image needs an image-capable model; Office reading uses the built-in engine. Password-protected files, scans needing OCR, and unsupported edits require another workflow. If File is unavailable or the original was not kept, ask the operator to check storage configuration. For download failures, reopen Artifacts and check storage warnings, access mode, public base URL, connectivity, and retention.
What to send for support
Record the application version, project, execution surface, time and time zone, error/status code, trace ID, and a minimal reproducing request. Include the expected result and whether Playground also fails. Remove tokens, cookies, private file links, and sensitive content.