Studio agent workbench - AgentKit 文档

AgentKit Studio uses the same service and complete UI as VeADK Frontend. It provides chat, search, session history, the resource library hub, video creation, automation integrations, and agent creation, testing, deployment, and management, and opens on the chat view by default. The agent workspace renders multi-agent topologies as a canvas, surfaces deployed Runtime versions and deployment status, and supports iterating on the same Runtime. Intelligent development, custom configuration, code-package deployment, and existing-project migration are the available project-creation flows. You can preview and edit generated files, run them in a temporary test process, download a ZIP, or deploy to AgentKit. Studio also supports cloud Runtime selection, multiple skill sources, multimodal conversations, automation integrations, and centralized deployment task status and retries.

When selecting an agent in the workspace, Studio prepares the session list, agent information, capabilities, and automatic evaluation statuses before changing the visible selection, eliminating intermediate loading states during the switch.

When you send a message or run a test agent, Studio receives responses over a streaming endpoint. If no first event arrives within 30 seconds, Studio aborts the stream and prompts you to check shared public egress network configuration and retry, preventing the request from hanging indefinitely.

Find a task

Task	Guide
Start and connect to cloud agents	Start and connect to cloud agents
Create or import a project	Create or import a project
Migrate an existing application	Migrate an existing application
Configure storage	Configure storage
Deploy Studio itself	Deploy Studio itself
Upgrade a deployed workbench	Upgrade a deployed workbench

Version and availability

This page covers released VeADK 1.1.13 features and the next Preview. API key status and model-permission filtering, the migration home layout, session artifacts, GitLab MR review, MCP credential editing, and new Studio deployment resource defaults were added after 1.1.13. A regular PyPI installation does not include those additions Use the following commands in a separate virtual environment to reproduce this Preview. The source revision is pinned for consistent UI and behavior. Release-package users can proceed to local startup

git clone https://github.com/volcengine/veadk-python.git veadk-preview
cd veadk-preview
git checkout 763865db9fb3b643e9fc0f04e2e0790ea5a4fc65
python -m venv .venv
source .venv/bin/activate
pip install -e .
cd frontend
npm ci
npm run build
cd ..

Python and Node.js are required; see Installation. When starting from this source directory, pass --frontend-dir ./frontend/dist to use the UI you just built

Start locally

Install VeADK and prepare credentials for the selected cloud account. This command starts the workbench with cloud Runtime selection:

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio --provider volcengine --open

--open opens http://127.0.0.1:8000 after the service is ready. Without it, Studio starts the service without opening a browser. Volcengine credentials are used for models, cloud-resource queries, and AgentKit deployment from the workbench. In production, provide them through environment variables or a secret manager rather than project files. To use BytePlus as the cloud provider, pass --provider byteplus and supply credentials via BYTEPLUS_ACCESS_KEY, BYTEPLUS_SECRET_KEY, and the optional BYTEPLUS_SESSION_TOKEN environment variables. Runtime listings default to the region in BYTEPLUS_REGION or ap-southeast-1. Without an explicit --provider, the CLI reads AGENTKIT_CLOUD_PROVIDER then CLOUD_PROVIDER to determine the cloud provider, falling back to Volcengine when neither is set. Complete BytePlus startup example:

export BYTEPLUS_ACCESS_KEY="your-access-key"
export BYTEPLUS_SECRET_KEY="your-secret-key"
veadk studio --provider byteplus --open

To debug local agents, use veadk studio --dev --agents-dir ./agents --open; see VeADK Web for the layout. --dev selects the local list; --agents-dir only supplies its directory After startup, confirm that the home page opens, then select an available agent and send a message to verify the model and Runtime connection. If the cloud list is empty, check provider, region, and permissions before changing local agent directories

Studio persistent storage

Studio capabilities such as video creation, automatic evaluation, intelligent-development project versions, and artifact persistence require persistent object storage to save reference assets, generated results, optimization snapshots, and conversation artifacts. Studio uses TOS as the persistent storage backend. When no dedicated publish storage is configured, skill publishing also reuses the persistent storage bucket; see Skill publish storage.

Cloud deployment

During veadk studio deploy, a private TOS bucket named veadk-studio-<account ID> is automatically created or reused in the deployment region. The bucket name is derived from the cloud account ID, making repeated deployments idempotent. Administrators can also specify an existing bucket name with the VEADK_STUDIO_TOS_BUCKET environment variable; when specified, the bucket must already exist in the deployment region, otherwise the deployment fails. A bucket created in one region cannot be recreated under the same name in another region. When switching deployment regions, Studio reuses the bucket if it already exists in the target region; otherwise you must explicitly specify a bucket available in that region.

The TOS bucket is created using the deployer’s Volcengine credentials. The deployed Studio accesses the bucket using temporary credentials from the bound IAM Role and never sends TOS credentials to the browser.

Local startup

When starting locally, configure persistent storage with the following environment variables:

Environment variable	Default	Description
`VEADK_STUDIO_TOS_BUCKET`	—	TOS bucket name used by Studio.
`VEADK_STUDIO_TOS_REGION`	—	Region of the storage bucket.

Both variables must be set for Studio to enable persistent storage. When not configured, features that depend on persistent storage (such as video reference asset upload) are disabled and the corresponding UI shows “管理员未配置持久化存储”; text-only features are unaffected. Local Studio uses the configured Volcengine or BytePlus AK/SK to access the bucket.

The older VEADK_VIDEO_TOS_* and DATABASE_TOS_* environment variables remain as a temporary compatibility fallback: when both VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION are unset, Studio attempts to read the bucket, region, and endpoint from the legacy variables. New deployments only need the two VEADK_STUDIO_TOS_* variables.

When using Volcengine as the cloud provider without a custom TOS endpoint, Studio probes the default public endpoint (tos-<region>.volces.com) on first access. If the probe encounters a transport-level network error, Studio automatically switches to the corresponding intranet endpoint (tos-<region>.ivolces.com) and continues using the selected endpoint for subsequent requests. Authentication failures, permission errors, and other non-network TOS service errors do not trigger fallback. Browser-facing signed URLs always use the public endpoint to ensure external accessibility. BytePlus and custom endpoints are unaffected by this mechanism.

Studio objects use a user-first, versioned key layout with the path format veadk-studio/v1/users/<encoded-user-ID>/<namespace>/<scope>/<resource-ID>/. Video reference assets use the video/<asset-role>/<asset-ID>/ namespace and store file content and metadata.json below it. Optimization snapshots produced by automatic evaluation are stored at veadk-studio/v1/evaluation-optimizations/<Runtime ID>/<app name>.json, with the latest snapshot retained for each Runtime application. Intelligent-development project versions are stored at veadk-studio/v1/users/<encoded-user-ID>/intelligent-development/projects/<project-ID>/versions/<version-ID>/. Each version contains an immutable source ZIP, validation report, and commit marker. Viewing, downloading, and deploying a saved version do not depend on the original Sandbox; the project summary is only an index. Evaluation sets and samples are stored at veadk-studio/v1/evaluation/<Runtime ID>/: the sets/ subdirectory holds evaluation sets (including the default Good Case and Bad Case sets), and the samples/ subdirectory holds individual samples with their set ID and source marker. Conversation thumbs-up/thumbs-down feedback and automatic evaluation cases use the same TOS records. App names, projects, and cloud regions are not part of the storage identity; use separate buckets for local and production installations.

Customize branding

Use --site-title to set a system name of up to 16 characters and --site-logo to provide a local image or HTTP(S) image URL. The logo appears in the sidebar, login page, and browser favicon. The browser tab title changes dynamically with the active view: the new-conversation home shows only the system name; an open conversation shows the conversation name; other pages such as Automation, System info, Create agent, Resource library, and Search show the form “System name - Page name”. Omitting --site-title uses the default AgentKit Studio name.

veadk studio \
  --site-title "TeamAI" \
  --site-logo "./logo.png"

The logo can be up to 5 MB in PNG, JPEG, GIF, WebP, AVIF, or ICO format. The equivalent environment variables are VEADK_SITE_TITLE and VEADK_SITE_LOGO. The deployment command accepts the same options; remote images are downloaded and bundled so that the deployed site does not depend on the original URL.

Interface language

Studio supports two interface languages: Simplified Chinese (zh-CN) and English (en-US). On first visit, Studio automatically detects and selects the interface language that matches your browser language settings; when no supported language matches, it defaults to English. Your language choice is persisted in browser local storage, so subsequent visits keep your last selected language. You can also switch the interface language at any time from the Language submenu in the sidebar account menu. The change takes effect immediately without reloading the page.

Create an agent

On the Agents page, click Create agent and choose Create from scratch to enter custom configuration, select “Intelligent development” to describe a goal and let Codex build it, choose “Add and deploy from a code package” to upload an existing project, or choose “Migrate an existing project” to migrate LangChain, Dify, or other framework projects to VeADK.
Configure the model, instruction, tools, memory, and knowledge base, and add skills from Skill Hub, a local upload, or an AgentKit SkillSpace. Multi-agent projects can also use sequential, parallel, loop, or A2A nodes, and the canvas lets you inspect and arrange the agent topology.
Review the generated files and run them in a restricted temporary process; download a ZIP if you need to work offline.
In the Optimization step, optionally enable Harness Sidecar optimizations for the agent; this step is optional and no Sidecar starts when nothing is selected.
In the Environment step, select a pre-built runtime environment image, or use the default AgentKit runtime environment; this step is optional.
Select AgentKit deployment and monitor the build-image, deploy, and publish stages from the workspace. After deployment, the agent appears as published in the workspace and can be updated on the same Runtime.

In addition to the custom creation flow above, Studio supports a DeepSeek Harness creation mode: select “Quick create” from the creation menu, then choose “DeepSeek Harness” in the agent type dialog to enter the DeepSeek Harness configuration page. Configure DeepSeek model service, custom model providers, command execution, sub-agent model selection, and other parameters, then preview, export, or deploy as an AgentKit Runtime. See DeepSeek Harness creation and deployment.

Resource pickers in custom creation (such as agent centers and knowledge-base collections) support local keyword filtering: type in the dropdown to filter the currently loaded options. Filtering applies only to the loaded list and does not change the region, project scope, or refresh behavior.

When deployment enters the build-image stage, Studio streams build logs in real time within the deployment progress card. Logs are redacted and length-bounded on the server before being sent to the browser. The panel shows the sync status (syncing, synced, or read failed) and line count, and can be expanded, collapsed, and copied; logs are syntax-highlighted and auto-scroll to the bottom by default — scrolling up pauses auto-follow, and scrolling back to the bottom resumes it; on a build failure Studio retries syncing the final build log and marks it as failed, so the real failure cause is visible at the end of the log. Log syncing depends on the Volcengine credentials used for deployment; if logs cannot be read, the panel shows a failed status without interrupting the deployment. Both custom creation and code-package deployment support this.

When a connection is interrupted during deployment and the final status cannot be confirmed, Studio marks the task as “Deployment status unconfirmed,” displaying a distinct status icon and a warning banner in the workspace and deployment progress card, and disabling the deploy or update button to prevent duplicate deployments. You are prompted to check the same task in AgentKit or Code Pipeline. Previously this situation was displayed as “Deploy failed.”

While a deployment is in progress, the workspace detail page focuses on the deployment progress: it keeps the agent heading and a scrollable deployment panel visible and hides the other detail tabs and content; the normal detail tabs return after the deployment ends. Custom creation, code-package deployment, and updating a deployed agent all follow this behavior.

When deploying to AgentKit, the root agent description is automatically normalized to a Runtime-compliant single-line description (at most 255 bytes, with line breaks, control characters, and unsafe symbols removed); the full description is kept in the project and is only used to produce the Runtime description. If the normalized description is rejected by Runtime, Studio retries creation without the description, leaving other configuration unaffected.

The agent instruction (system prompt) is limited to 40,000 characters; generating or testing a project with a longer instruction will fail.

The instruction editor provides a WYSIWYG Markdown editing experience. When the content contains Markdown syntax the editor cannot parse, it automatically switches to a plain-text mode so you can still edit and save the instruction.

Custom creation supports a “quick create” mode: when enabled, the generated agent project includes the CreateAgentToolset dynamic agent delegation toolset, allowing the main agent to collect resources, create sub-agents, and delegate execution at runtime. In quick mode the generated requirements.txt pins veadk-python 1.1.13 and includes a compatibility module to ensure dynamic delegation works on the current deployed version. When deploying to AgentKit, if the Runtime uses a Studio-generated default service role, Studio automatically attaches the AgentKitFullAccess policy to that role so sub-agents can access AgentKit resources; custom service roles are not modified and must be configured with the required permissions manually.

When editing an agent name in custom creation or the quick-create wizard, Studio validates and shows name errors immediately on input or blur (such as naming-rule violations or non-unique names within the structure), without waiting for submission.

Model selection

When configuring an LLM agent, you can browse the Ark models activated under the current account in the model selector and choose a target model. The model list is fetched by the Studio server from Ark and includes only LLM and VLM models that support agent calls, showing the model name, display name, vendor, and activation status. The list is cached server-side; use the refresh button to retrieve the latest status. The model source falls into one of the following categories, determined automatically by whether the model API base URL is the official Ark endpoint for the current cloud provider:

Model source	Credential provided by Studio	Debug run	Deployment
Ark (blank or using the official Ark endpoint for the current cloud)	Official Ark endpoint with a Studio-managed Ark API Key	Supported	No additional input required
Custom (non-official Ark endpoint)	No credential	Not supported	You must provide the agent’s API Key on the publish page

Debug runs do not support custom model endpoints. Agents using a non-official Ark endpoint will fail at debug time. Use the official Ark endpoint for the current cloud, or deploy first and test through the Runtime.

When using Ark models, the Studio server selects an Ark API Key from the current account’s key list for debug runs and deployment. The default selection matches MODEL_AGENT_API_KEY_NAME; if no match is found, the first enabled key in the list is used. You can also manually select a specific Ark API Key in the deployment configuration area: the selected key’s raw value is resolved by the Studio server and injected into the runtime environment without ever being sent to the browser. When the list is empty, create an API Key in the Ark console first. The API Key list is read live from the cloud provider on each page load and is not cached server-side. Each API Key in the selector shows its name, status, and permission scope: the status distinguishes “Enabled” and “Disabled”, and the permission scope distinguishes “All permissions” and “Custom permissions”. Disabled API Keys remain visible in the list but cannot be selected. The search matches names, statuses, and permission scopes, and supports multiple keywords. When the selected API Key has “Custom permissions”, the model list is annotated according to that key’s model permissions: models outside the permitted scope still appear in the list but are disabled and annotated with the reason (such as “Not permitted by this API Key”, “Shut down”, “Video generation model”, “Not a chat model”, or “Not activated”). Video generation and shut-down models explicitly granted by the API Key also appear in the searchable model dropdown but remain disabled. When switching API Keys, previously selected models and fallback models that are no longer permitted by the new key are automatically cleared.

Overlapping identical model-option requests share a single in-flight cloud query, avoiding redundant concurrent overhead; subsequent reads still fetch the latest cloud data. When model metadata is cached, permission information is recomputed and re-applied for the currently selected API Key.

When using a custom model endpoint, the publish page displays a “Custom model credentials” group in the environment-variables area, providing a required API Key input for each agent that uses a custom endpoint; model provider and model API base URL are also available as optional inputs. The credentials are used only for that publish and are not saved in the draft. Generated project code reads the configuration from the following environment variables, and .env.example lists them as placeholders:

Environment variable	Description
`CUSTOM_MODEL_<agent_name>_PROVIDER`	Model provider (e.g. `openai`); generated only when provided.
`CUSTOM_MODEL_<agent_name>_API_BASE`	Model API base URL; generated only when provided.
`CUSTOM_MODEL_<agent_name>_API_KEY`	Model API Key; required.

Model fallback configuration

When configuring an LLM agent, you can add ordered fallback models for each agent. When the primary model is unavailable, VeADK tries the fallback models in order. Fallback models fall into two categories:

Same-provider fallbacks: Specify only the model name; the fallback automatically reuses the primary model’s provider, API base, and API key. The generated project code implements fallbacks through the model_name list.
Cross-provider fallbacks: Specify a separate model provider, API base, and API key for each fallback endpoint. The generated project code uses ModelFallbackEndpoint objects passed via the model_fallbacks parameter.

For the full parameter reference and usage restrictions for model fallbacks, see Model.

API keys for cross-provider fallbacks are passed through environment variables and are not stored in plain text in the generated source or draft. Each fallback endpoint corresponds to an environment variable named FALLBACK_MODEL_<agent_name>_<index>_API_KEY, listed as a placeholder in .env.example:

Environment variable	Description
`FALLBACK_MODEL_<agent_name>_<index>_API_KEY`	API key for a cross-provider fallback model, numbered from 1 in fallback order.

Configure deployment settings

In the deployment configuration area, select the region and network mode, and optionally set Runtime instance counts. Instance settings appear only when creating a new Runtime; they are hidden when updating an existing Runtime. When updating an existing Runtime, the region and network mode are read from the existing Runtime and remain unchanged.

Setting	Default	Description
Region	`cn-beijing`	Runtime deployment region.
Network mode	Public	Choose public, VPC, or public + VPC; VPC mode requires a VPC ID.
Min instances	`1`	Minimum number of Runtime instances; can be set to `0` to scale to zero.
Max instances	`5`	Maximum number of Runtime instances; defaults to `1` when using in-memory short-term memory.
Access authentication	API Key	Access authentication for a new Runtime. Choose API Key or a VeIdentity user pool; updating an existing Runtime keeps its current authentication.
Auto-create evaluation sets	Disabled	Automatically creates Good Case and Bad Case evaluation sets in Studio persistent storage for the agent after deployment succeeds. Disabling skips this step. If creation fails, a warning is shown in the deployment result without affecting the deployed Runtime.

The minimum instance count must be a non-negative integer and the maximum a positive integer; the minimum cannot exceed the maximum. When the agent’s short-term memory backend is local (in-memory) or unconfigured, Studio defaults the maximum instance count to 1 and warns that multiple instances, process restarts, or rolling updates can cause session loss; a database-backed short-term memory store is recommended. When creating a new Runtime, the minimum and maximum instance limits are set during creation; after deployment, Studio waits for the configured number of instances to become ready before reporting success, preventing the first conversation from landing on a temporary startup instance. When creating a new Runtime, Studio auto-generates a Runtime name from the root agent name (composed of letters, digits, underscores, and hyphens, 4–64 characters), keeping agent and Runtime naming consistent and predictable. The Runtime name can be edited manually; Studio validates the name format and checks for conflicts with existing Runtimes in the selected region before deployment. If the name is already in use, deployment fails with a prompt to choose a different name. The deployment result returns both the agent name and the Runtime name. When creating a new Runtime, access authentication defaults to API Key. To use user identity verification instead, select a VeIdentity user pool in the deployment configuration area. The Studio server loads the user pools visible to the current account with its own Volcengine credentials, so the browser never receives them. The picker marks the user pool used for the current Studio login: selecting it lets Studio forward the validated login JWT to the Runtime, so callers do not need to obtain a token separately; selecting another user pool means callers must use a JWT issued by that pool to access the Runtime. The user-pool region is determined by the VEIDENTITY_REGION environment variable. In Volcengine mode, when VEIDENTITY_REGION is not set it falls back to the REGION environment variable and then the default cn-beijing; BytePlus mode is fixed to ap-southeast-1.

Configure build resources

When deploying to AgentKit, Studio uses the following cloud resources for image building and publishing:

TOS bucket: Stores the source code package for the cloud build service to fetch.
Container Registry (CR): Stores the built image, comprising an instance, namespace, and repository.
CodePipeline: Manages the cloud build pipeline, comprising a Workspace and a Pipeline.

Each resource group supports three configuration modes:

Mode	Description
Auto create	Creates the required resources automatically during deployment. Resource names are generated by Studio based on the account ID and deployment region. After deployment, the selected resources are recorded as Runtime tags.
Specify names	Enter resource names; Studio creates or reuses resources with those names during deployment.
Select existing	Choose from existing resources in the current account. Studio loads the resource list using its own server-side Volcengine credentials.

All resources default to “Auto create.” When using “Specify names” or “Select existing,” complete resource information is required: TOS needs a bucket, CR needs an instance, namespace, and repository, and CodePipeline needs a Workspace and Pipeline. Missing fields fail validation before deployment.

Build-resource configuration appears only when creating a new Runtime. When updating an existing Runtime, Studio reads the resources from the Runtime tags and preserves them; the configuration area is not shown.

The naming rules for auto-created resources are:

Resource	Auto-created name
TOS bucket	`agentkit-platform-{account ID}`; a region suffix is appended for regions other than cn-beijing
CR instance	`agentkit-platform-{account ID}`
CR namespace	`agentkit`
CR repository	`{agent name}-{random characters}`
CodePipeline Workspace	`agentkit-cli-workspace`
CodePipeline Pipeline	`{agent name}-{random characters}` (same name as the Runtime)

The account ID and random characters are resolved at deployment time; the UI shows only the name template. When using “Select existing,” the Studio server loads existing resources for the current account in the selected region using its own Volcengine credentials. TOS buckets and CR resources are displayed and selected by name. CodePipeline Workspaces are selected by ID; after selecting a Workspace, the Pipelines within it are loaded, showing only entries compatible with AgentKit build pipelines. Lists support searching by name and paginated loading, and can be reloaded on failure.

Before selecting existing resources, confirm that the chosen TOS bucket, CR repository, and CodePipeline are in a usable state and accessible with the current credentials. Using an incompatible CodePipeline causes build failures.

Symptom	Check
Resource list is empty	Confirm that the current account has created the corresponding resources in the selected region and that the credentials have view permissions.
Resource list fails to load	Check the Studio login session, network connectivity, and credential permissions, then retry.
Deployment reports a resource validation error	Verify that the selected or entered resources are complete; for example, CR requires an instance, namespace, and repository.

Configure agent optimizations

Custom creation adds an Optimization step between Debug and Environment for enabling Harness Sidecar optimizations. Harness Sidecar runs agent-enhancement behavior in a separate managed runtime; the application process itself does not load the related plugin implementations.

Harness Sidecar optimizations support Volcengine accounts only. BytePlus accounts cannot use optimization items; keep them empty to continue deployment. Ordinary BytePlus agents are unaffected.

In the Optimization step, first choose an optimization scenario, then select optimization components as needed:

Scenario	When to use	Default selected components
Custom	Select components on demand; no Sidecar starts when nothing is selected	—
Operations	Operations diagnosis, databases, logs, and monitoring MCP	Context governance, answer verification and repair, Goal-task control, MCP-resilience governance

Selecting the Operations scenario automatically loads SQL read-only protection. Optimization components are grouped into three categories:

Group	Component	Purpose
Improve answer quality	Context governance	Governs context assembly, task anchoring, and the context budget.
Improve answer quality	Answer verification and repair	Verifies evidence and answers, running repairs or alerts on failure.
Reduce running cost	Context and result compression	Compresses long context and large tool results to lower token cost.
Enhance stability	Goal-task control	Manages Goal-task progress, resumption, and end conditions.
Enhance stability	MCP-resilience governance	Governs connection, timeout, empty results, large returns, and call budget; includes SQL read-only protection by default.

After enabling optimization items, the Publish step requires the runtime settings they depend on:

When Context governance, Context and result compression, Answer verification and repair, or Goal-task control is selected and a Volcengine Ark model is used, model-gateway settings are required. Studio fills in the model provider, model API base, and model name automatically; the Ark API Key is injected from the selected API Key and does not need to be entered manually.
When MCP-resilience governance is selected, Studio injects MCP configuration automatically from the HTTP MCP tools configured earlier in the Add MCP Tool step—no manual entry is needed. At least one MCP tool using HTTP transport must be configured with a valid service URL; a Bearer Token is only required when the service requires authentication, and each HTTP MCP tool may use its own credential. If these conditions are not met, the Publish step directs you back to the Add MCP Tool step to complete the configuration before republishing. MCP tools using stdio transport are not supported for MCP-resilience governance.

After enabling Harness Sidecar optimizations, the related enhancement behavior runs in a managed runtime and accesses the model and MCP gateway. Confirm that the configured model credentials, MCP gateway address, and access scope meet your data-handling and security requirements.

Configure the cloud environment

The custom-creation lifecycle follows five steps: Architecture, Debug, Optimization, Environment, and Publish. The Environment step sits between Optimization and Publish and lets you select a pre-built runtime environment image. The step is optional: choosing “Default environment” uses the default AgentKit image build and the generated project contains no Dockerfile. In the Environment step, select a successfully built runtime environment from the dropdown. The dropdown shows the environment name, operating system, Python version, and build status (preparing, queued, building, scanning, available, or failed); only environments with “available” build status are selectable. Once selected, the environment image is used as the base image for the agent image build during deployment, and the chosen environment version is pinned to that deployment. When no environment is selected, the default AgentKit runtime environment is used.

Runtime environments must be pre-created and built in the Environments tab of the Workspaces page. Once the build status reaches “available,” the environment appears in the Environment step dropdown. See Manage runtime environments.

Workspaces

The Studio sidebar provides a “Workspaces” entry for organizing reusable runtime environments into workspaces by purpose. A workspace can contain multiple environments, and the same environment can belong to multiple workspaces; deleting a workspace only removes the association and does not delete the environments. Agent creation and deployment still directly select a specific environment and its build version — workspaces only organize and manage environments. The workspaces page provides “Workspaces” and “Environments” tabs that you can switch between. The workspaces list shows each workspace’s name, description, the number of environments it contains, and the number of available environments. Click “Manage” to open the workspace detail, where you can add or remove environments. Each environment card also shows the number of workspaces that reference it.

Workspace metadata is stored in the same Studio-private TOS bucket as environments. Workspaces require persistent storage to be configured by an administrator. When persistent storage is not configured, workspace features are unavailable.

Environments referenced by workspaces cannot be deleted directly. Before deleting an environment, remove it from all workspaces that reference it.

Manage runtime environments

In the “Environments” tab of the Workspaces page, you can create, manage, and build reusable runtime environments. A runtime environment is a configuration definition containing an operating system, Python version, command-line tools, skills, and a Dockerfile. After building, it produces a container image that can be selected as the base image when deploying an agent. Environment definitions, generated Dockerfiles, build versions, log metadata, and image references are stored in the Studio-private TOS bucket.

Environment management requires persistent storage to be configured by an administrator. When persistent storage is not configured, environment-related features are unavailable.

Create a runtime environment

After clicking “Create environment” in the Environments tab, choose a creation method:

Creation method	Description
Custom configuration	Select the operating system, Python version, command-line tools, and skills; Studio auto-generates the Dockerfile. You can review and edit the generated content on the “Dockerfile” tab.
Upload Dockerfile	Upload an existing Dockerfile file directly, skipping tool and skill selection. You can continue editing the file content after upload.
Build from Git repository	Provide a public HTTPS Git repository URL; Studio inspects the repository for Dockerfiles and builds the image via CodePipeline.
Bind existing CR image	Select an existing image already pushed to Container Registry and bind it directly, with no build required.

All four methods require an environment name and description. “Custom configuration” and “Upload Dockerfile” build images from Studio-managed Dockerfiles; “Build from Git repository” fetches a Dockerfile from an external repository and builds it; “Bind existing CR image” uses an existing image directly without triggering a build.

Custom configuration

After selecting “Custom configuration”, fill in the following settings:

Setting	Options	Description
Environment name	Free text, up to 128 characters	A unique name for the environment.
Description	Free text, up to 2000 characters	A description of the environment’s purpose.
Base environment	AIO Sandbox, Codex Sandbox, Ubuntu	The base image type, determining whether the image includes the Sandbox Shell or Codex task delegation capability. See Base environment types.
Operating system	Ubuntu 22.04, Ubuntu 24.04	The base image operating system. Fixed to Ubuntu 22.04 when AIO Sandbox or Codex Sandbox is selected.
Python version	Python 3.10, Python 3.12	The Python version in the image. Fixed to Python 3.12 when AIO Sandbox or Codex Sandbox is selected.
Command-line tools	See the table below	Official tools to pre-install in the image.
Skills	Skill Hub, local upload, AgentKit SkillSpace	Skills to pre-install in the image, up to 20.
Dockerfile	Auto-generated or custom	The Dockerfile content used to build the image.

When selecting command-line tools, you can choose from the following official tools. Selected tools are pre-installed into the environment image:

Tool	Category	Description
lark-cli	Tools	Lark OpenPlatform command-line tool.
pandoc	Tools	Document format conversion tool.
opencli	Tools	Converts websites and desktop apps into command-line tools.
uv	Productivity	Fast Python package and project manager.
ripgrep	Productivity	High-performance text search tool.
jq	Productivity	JSON query and transformation tool.
GitHub CLI	Productivity	Manage GitHub workflows from the terminal.
Playwright	Browser automation	Browser automation and end-to-end testing.
Chromium	Browser automation	Headless browser runtime.
Git	System & media	Version control.
curl	System & media	Network requests and file downloads.
FFmpeg	System & media	Audio and video transcoding and processing.
ImageMagick	System & media	Image conversion and batch processing.

When creating or saving an environment, Studio auto-generates a Dockerfile based on the operating system, Python version, and selected tools. When no custom Dockerfile is provided, the auto-generated version is used. The image is built on the official Ubuntu image for the selected operating system, installs the Python runtime and system dependencies for the selected tools, and pre-installs VeADK runtime dependencies. Volcengine builds use the Volcengine APT mirror, Aliyun PyPI mirror, Huawei Cloud Python source mirror, and npmmirror for Playwright browsers; BytePlus builds use the corresponding official sources. Cross-version Python combinations (e.g., Ubuntu 22.04 + Python 3.12) are compiled from pinned source releases instead of depending on GitHub-hosted binaries.

The generated Dockerfile never contains access keys or credentials. Provide any tokens or credentials the tools need as runtime environment variables after deployment; do not write them into the Dockerfile.

Never write access keys, tokens, or other credentials into the Dockerfile. The Dockerfile is submitted to the cloud build service together with the project and may be readable by anyone with access to the build artifacts.

Base environment types

When creating an environment, you can choose from the following base environments:

Base environment	Description
AIO Sandbox	Built on the AIO Sandbox image, preserving the built-in `/opt/gem/run.sh` startup chain and port 8080 to provide the Sandbox Shell API. When selected, the operating system is fixed to Ubuntu 22.04 and Python is fixed to 3.12, with Studio dependencies isolated in a separate virtual environment. After the image build completes, Studio automatically creates an associated AgentKit Sandbox Tool so the environment can be mounted to conversations for shell command execution. New environments default to this type.
Codex Sandbox	Built on the Codex Sandbox image, exposing task delegation through its Codex App Server instead of the generic Sandbox Shell tool. When selected, the operating system is fixed to Ubuntu 22.04 and Python is fixed to 3.12. After the image build completes, Studio automatically creates an associated AgentKit Sandbox Tool so the environment can be mounted to conversations for delegating complete tasks to Codex.
Ubuntu	Built on the official Ubuntu image, installing the runtime based on the selected operating system and Python version. Does not support being mounted to conversations for shell command execution. Environment records created before the base-environment field was introduced are treated as this type.

When an uploaded Dockerfile contains aio.sandbox, Studio automatically detects it as an AIO Sandbox base environment; when it contains /codexenv:, Studio automatically detects it as a Codex Sandbox base environment.

When the AIO Sandbox base environment is selected, Studio automatically creates an associated AgentKit Sandbox Tool (a private tool with the /opt/gem/run.sh entrypoint on port 8080) after the image build and injects model-related environment variables. Tool creation runs asynchronously; the environment version only becomes fully available after the Tool is ready. While the Tool is not ready, the environment version cannot be mounted to a conversation for command execution. When the Codex Sandbox base environment is selected, Studio also automatically creates an associated AgentKit Sandbox Tool and injects model-related environment variables after the image build. Once the Tool is ready, the environment version can be mounted to conversations, and the agent delegates complete tasks to the Codex App Server via the delegate_to_codex_sandbox tool instead of executing commands through the Sandbox Shell directly. Each environment version exposes a read-only Manifest, accessible via the GET /web/environments/{environmentId}/builds/{versionId}/manifest endpoint. The Manifest includes the image reference, base environment, operating system, Python version, pre-installed packages, capabilities, and the associated Sandbox Tool status. The environment card can open the same version-bound Manifest as YAML for inspection and copying.

Upload Dockerfile

After selecting “Upload Dockerfile”, drag a file onto the upload area or click it to choose a local Dockerfile file. After uploading, you can continue editing the content in the preview area. The uploaded Dockerfile must satisfy the following requirements:

Requirement	Constraint
File size	At most 128 KiB
Content	Must not be empty
Instruction	Must contain a `FROM` instruction

When uploading a Dockerfile, operating system, Python version, command-line tools, and skills are not selected; those are determined by the uploaded file content. The environment name and description are still required.

Build from Git repository

After selecting “Build from Git repository”, provide a public HTTPS Git repository URL and an optional branch, tag, or commit. Studio inspects the repository and automatically discovers files matching Dockerfile, Dockerfile.*, and *.Dockerfile naming patterns. After candidates are found, select one as the build entry; if no matching files exist, the environment cannot be created. Studio saves the following information for the build:

Setting	Description
Git repository URL	A public HTTPS Git repository URL. Must not contain a username, password, or token.
Ref	Optional branch, tag, or commit SHA. When left blank, the repository’s default branch is used.
Dockerfile path	The relative path of the selected Dockerfile within the repository.

During the build, CodePipeline uses the repository root as the build context and builds the image with the selected Dockerfile. The build version records the checked-out commit SHA for traceability. You can optionally specify a target Container Registry repository for the build result, including the following fields:

Setting	Description
Region	The region of the CR resource; may differ from the Studio deployment region.
Registry instance	The CR instance name.
Namespace	The CR namespace.
Repository	The CR repository name.

When no target CR repository is specified, Studio uses managed CR resources. The version tag for each build is recorded by Studio in the build result. Switching region clears the selected Registry, Namespace, and Repository to prevent invalid cross-region combinations. The server validates CR resources in the selected region and pushes the Git build result to the target Repository in that region.

Only public HTTPS Git repository URLs are supported; the URL must not point to a private network, localhost, or include a username, password, or token. The repository must not contain Git submodules or symbolic links. The file count must not exceed 20,000 and the size must not exceed 200 MiB. Private repositories, SSH URLs, and Git credentials are not supported.

Bind existing CR image

Select “Bind existing CR image” when the image has already been built by your own pipeline and pushed to Container Registry. Select the region, Registry instance, Namespace, and Repository in turn, then enter the Tag or Digest. Studio uses the image directly without starting a CodePipeline build. Studio saves the following information:

Setting	Description
Region	The region of the CR resource where the image resides.
Registry instance	The CR instance name.
Namespace	The CR namespace.
Repository	The CR repository name.
Tag or Digest	The image version identifier. Supports a Tag (e.g. `1.0.0`) or a full Digest starting with `sha256:`.

After selecting a region, Studio loads the Registry instances, Namespaces, and Repositories in that region through the server-side resource API in a cascading picker. Switching region clears the selected Registry, Namespace, and Repository. When the environment is created, Studio validates that the selected CR resources exist and resolves the image reference; once validation passes, an available version is created directly.

When binding an existing image, skills cannot be selected at the same time. Any skills needed in the image must be pre-installed in the image pipeline.

Git repository build and existing image binding cannot be configured at the same time. Git builds generate an image via CodePipeline and push it to the target CR repository; existing image binding uses the current image directly without triggering a build.

Build environment images

After creating or saving an environment, click “Build” to start an asynchronous image build. Studio uploads the build context to the TOS bucket, runs the build pipeline through CodePipeline, and pushes the resulting image to Container Registry. The build proceeds through preparing, queued, building, and scanning phases, with a final status of “available” or “failed.” Environments built from a Git repository also build images via CodePipeline and push the result; the build version records the checked-out commit SHA. Environments that bind an existing CR image do not require a build — an available version is created at creation time. After the build completes, the environment list shows the latest version’s build status and image reference. You can view build steps, progress, and logs on the environment detail page. Logs are syntax-highlighted and auto-scroll to the bottom by default — scrolling up pauses auto-follow, and scrolling back to the bottom resumes it. When the build fails, the end of the log shows the error message to help locate the failure cause. When the AIO Sandbox or Codex Sandbox base environment is selected, an additional “Create AgentKit Sandbox Tool” build step runs after the image build completes. This step asynchronously creates the associated private Sandbox Tool and injects model-related environment variables; the environment version only becomes fully available after the Tool is ready. While the Tool is being created, the environment status shows “building”; it changes to “available” once the Tool is ready, or “failed” if Tool creation fails. The environment version cannot be mounted to a conversation for command execution until the Tool is ready.

On the first environment image build, Studio automatically creates or reuses managed CodePipeline Workspace, Pipeline, and Container Registry resources. When using the account-level default TOS bucket, Container Registry reuses the account’s agentkit-cli-<account-id> instance and creates the runtime-environments/base-images repository inside it.

Environment build resources

When deploying Studio, you can specify existing environment build resources using the following flags:

veadk studio deploy \
  --vefaas-app-name <app-name> \
  --environment-cp-workspace <workspace-id-or-name> \
  --environment-cr-repository <registry/namespace/repository>

Both flags can be used independently. --environment-cr-repository must use the registry/namespace/repository format; each segment must not contain spaces or ./... When omitted, Studio creates or reuses managed resources. These settings are not read from environment variables and take effect only in the deploy command. After deployment, the System Information page shows the resolved CodePipeline and Container Registry names, source, and console links; these values are resource identifiers and do not contain credentials.

Environment build resources are managed independently from agent deployment build resources. Environment image builds use the CodePipeline and Container Registry described above; agent deployments use the resources managed in “Configure build resources.” When an agent selects a pre-built environment, deployment builds the agent image into the Container Registry namespace of the environment’s base image, ensuring the build credential can both pull the base image and push the agent image.

Environment configurations can be exported as share codes and imported into another Studio user’s environment list, enabling cross-instance sharing of environment configurations. Share codes are prefixed with akenv://v1/ and are self-contained, versioned data with no server-side sharing records. In the environment list, each environment card provides an entry to export a share code. The exported share code contains the environment name, description, system, language, components, Dockerfile, Git/CR source, and portable skill configuration. Local skill files are written directly into the share code. If the source environment has an available version, the share code also carries its image, Sandbox Tool, and version-level skill snapshot, so that importing into a Studio on the same cloud provider makes it available for mounting directly.

Share codes may contain Dockerfile and local skill source code; only send them to trusted recipients. Environment IDs, owners, creation/update timestamps, build logs, run records, and cloud credentials are not included in share codes. Importing across Volcengine and BytePlus does not mark an image version as available.

When the browser blocks automatic copying, the share dialog retains the full share code for manual copying. The environment list detects when the clipboard starts with akenv:// and prompts to import. Click “Import environment” in the environment list and paste one or more share codes. Share codes can be separated by English commas, Chinese commas, or newlines, with a maximum of 20 per batch. Studio first inspects and lists the validity of each share code, then imports them one by one. Duplicate share codes are automatically ignored. A failure on one entry does not roll back environments that were already added successfully. The import behavior varies depending on the share code content:

Share code content	Import behavior
Contains an available version and the cloud provider matches	Creates the environment and binds the image version; can be mounted directly.
Contains an available version but the cloud provider differs	Creates the environment configuration without reusing the image or Sandbox Tool.
Custom configuration, Dockerfile, or Git source	Creates the environment configuration without starting a CodePipeline build.
Existing image binding	Re-validates and binds the specified CR image.

After import, the results show each share code’s status (created, duplicate, or failed), the environment name, and the failure reason.

Intelligent development

Intelligent development is a goal-driven creation flow: on Add Agent, select “Intelligent development” and describe the problem your agent should solve in natural language. Codex in the sandbox handles each request directly within a single turn — for questions, clarifications, or explanations that do not require project changes, it answers naturally; for development requests, it builds the project, debugs it, and performs a temporary cloud validation, producing a deployable source artifact.

Intelligent development requires a configured Dev Sandbox Tool (SANDBOX_DEV or --sandbox-dev-tool-id) with model credentials configured on that Tool (a model ID, an API Key, and a model API base URL pointing to the current cloud’s official Ark endpoint). When the Tool is not configured, the entry shows “Unavailable.” When the Tool is configured but model credentials are missing or do not match, the entry is also unavailable and prompts you to redeploy Studio. veadk studio deploy creates this Tool and completes the model configuration automatically by default; for local startup you can specify an existing Tool ID manually.

The “Intelligent development” page provides a model selector below the goal input, used to specify the model Codex uses for the current intelligent-development session. The model list is fetched by the Studio server from Ark models activated under the current account, showing only models that the current cloud provider allows for intelligent development, with their display name, ID, vendor, and lifecycle status, and supports search filtering. The default is the model configured on the Dev Sandbox Tool; after selecting a different model, the selected model’s name, provider, and API base URL are injected into the session environment by the Studio server without sending model credentials to the browser. The model list can be reloaded on load failure.

Workflow

Describe the goal

Enter a goal description on the “Intelligent development” page, for example “Create an agent that reads sales data, generates weekly reports, and validates the output format.” Codex handles the request directly within a single turn; if key information that may affect the result is missing, it asks one necessary clarification first.

Build and validate

Studio creates an intelligent-development sandbox session where Codex outlines the goal and implementation, then writes, runs, and validates the agent code. During the build, progress messages appear as a separate progress indicator in the conversation, distinct from the assistant’s text output; the indicator disappears automatically when the current turn completes. For requests that change the deliverable, delivery summaries follow a structured Markdown format: a one-sentence outcome summary first, followed by sections for Completed, Validation, and Remaining issues; for questions or explanations that do not require project changes, Codex answers naturally without this structured format and does not modify the project code. The development environment is retained for up to 8 hours and can be iterated on within the same session.

Inspect and deploy the artifact

After the build completes, a delivery card appears in the conversation showing the agent name, entry-point file, file count, artifact size, and validation status. Artifacts that have passed cloud validation are marked “Validated delivery” with the number of passed checks; unvalidated artifacts are marked “Generated agent source.” From the card you can view the source files, download a ZIP, or deploy directly to an AgentKit Runtime.

Deploy validated source

When deploying from intelligent development, the source is materialized server-side from the validated delivery artifact or a saved project version; browser files cannot replace it and only a new Runtime can be created. The deployment page shows the Runtime name (editable; must be 4–64 characters containing only letters, digits, underscores, and hyphens), the entry-point file, artifact checksums, and supports selecting the deployment region and network mode. The Runtime name is taken from the agent name in the delivery artifact, and resource tags record the source as intelligent development.

Source that has not passed cloud validation can still be deployed, but confirm the Runtime configuration before proceeding.

Session management

Intelligent-development sessions run in the current browser session and do not appear in the sidebar history list. An in-progress session shows a “Building” status; you can switch to other pages and return to resume the current session. When you try to navigate away during a build, Studio prompts that leaving will stop the current build, but the session is preserved. When resuming a session, the conversation history shows only user messages and assistant responses; internal intent-gate and task-scheduling steps are not displayed.

Tool calls, thinking content, and progress messages from intelligent development are redacted server-side before being sent to the browser: task credentials and private paths are removed and never appear in the browser.

During quiet periods, the intelligent-development stream sends a heartbeat every 15 seconds to keep the connection alive without resetting Codex’s inactivity timeout. Request deadlines and process restarts still apply; the heartbeat does not provide background delivery or stream replay. When a Codex turn is interrupted — including interruptions Studio discovers after reconnecting — Studio reports the interrupted status explicitly; it does not publish a new version or wait for the inactivity timeout. Active turns resume on the same Thread after a connection drops. New task progress resets the recovery allowance; reconnecting and reading unchanged state do not extend the inactivity deadline or restart the task.

Re-entering intelligent development from the create entry returns to the home page and clears the previous deployment page’s navigation state; saved project versions can still be selected from the version library for redeployment.

Project version library

Each completed build or optimization is saved as an immutable project version in the private Studio TOS bucket. Saved versions do not depend on the original Sandbox environment — viewing, downloading, and deploying remain available even after the Sandbox session expires. Versions are grouped by project and listed by creation time.

Project version persistence requires the administrator to configure Studio persistent storage (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION). When persistent storage is not configured, build artifacts are only available within the current Sandbox session and are not saved as project versions. See Studio persistent storage for configuration.

Open the project version library from the intelligent-development creation page to browse saved projects and their versions. Each version displays the creation time, intent summary, validation status, agent name, entry-point file, file count, and artifact size. The following operations are available:

Operation	Description
View source	Browse files in the version using an IDE-style file tree in the code browser, with light and dark theme support.
Download ZIP	Download the complete source archive for the version.
Deploy to AgentKit	Materialize the source from a saved version and deploy to a new Runtime without depending on the original Sandbox.
Restore to new session	Restore a saved version into a new intelligent-development session as a baseline for further iteration.
Delete version	Delete the version and its source artifacts; deletion is irreversible.

Optimization builds expose before/after changes directly in the delivery, viewable in the source browser.

Version comparison

Select any two versions of the same project in the project version library to compare file differences between them. The comparison is presented in a side-by-side diff view, showing additions, deletions, and modifications per file. Version comparison does not produce additional stored artifacts.

Add and deploy from a code package

Code-package deployment is an independent creation flow: on Add Agent, select “Add and deploy from a code package” and upload an existing Agent project archive. You can then inspect or edit its files in Studio and deploy directly to AgentKit without configuring the model, tools, or skills individually. It suits getting an externally authored VeADK project online quickly, or re-deploying an existing project after small adjustments.

Upload the code package

On the Add Agent menu, choose “Add and deploy from a code package” and click the upload area or drag a file to select a .zip archive. The archive can be up to 50 MB and contain no more than 800 files after extraction. The entry point defaults to app.py at the root; if the root contains an agentkit.yaml that declares common.entry_point, the declared file is used as the entry point instead.

Review or edit files

After a successful upload, Studio reports the recognized file count and derives a project name from the archive file name (following Google ADK naming rules: starting with an ASCII letter or underscore, containing only ASCII letters, digits, and underscores, never using the reserved name user, and at most 64 characters). Use “View files” to preview or edit file contents in the code browser; re-upload the archive to replace the contents.

Configure deployment

Select the region and network mode in the deployment configuration area, the same as the custom-creation deploy page. Code-package deployment does not show the agent topology or the Feishu channel toggle.

Deploy to AgentKit

After selecting “Deploy”, Studio reports progress across four stages: upload code package, build image, create Runtime, and publish service. Each stage reports its completion or failure in the deployment progress area.

Studio sanitizes the archive: it ignores __MACOSX directories and .DS_Store files, and when all files share a single top-level directory it strips that wrapping directory before validating the entry. Entries with absolute paths, empty segments, ., .. segments, or null bytes are rejected, and duplicate file paths raise an error. The entry point file must be in the root after the wrapping directory is removed.

The uploaded app.py runs inside the deployed AgentKit Runtime and can call external services or access data available to the runtime. Deploy only trusted projects and give Studio restricted credentials.

Check	Limit	Description
Archive size	50 MB	Maximum size of a single uploaded archive.
File count	800	Maximum number of files retained after extraction.
Uncompressed size	50 MB	Maximum total size after extraction.
Entry point	`app.py`	Default entry file. If the root contains an `agentkit.yaml` that declares `common.entry_point`, that value is used instead; otherwise `app.py` at the root is required.
Path safety	—	Absolute paths, `.` / `..` segments, and null bytes are rejected; `__MACOSX` and `.DS_Store` are ignored.
Wrapping directory	Single level	When all files share one top-level directory, that level is stripped automatically.
Project name	64 characters	Derived from the archive file name and follows ADK naming rules.

Migrate an existing project

Existing-project migration is an independent creation flow: on Add Agent, select “Migrate an existing project” and upload an archive of an existing agent project. Studio automatically analyzes the project framework and entry point in a Dev Sandbox and generates a deployable VeADK project.

The migration workspace uses a single-column layout without a side navigation. The home page shows the project upload entry at the top, followed by recent migrations displayed in a table (five entries by default, expandable in place to show all); expired migration environments are offered as view-only. The “Migrated projects” entry in the top navigation bar opens the saved-project library. Returning home or opening the project library never stops a running migration. Capability and session-list load failures are reported separately so the upload entry stays usable, and each failure offers its own retry.

The following frameworks are supported:

Framework	Migration method
LangChain	Structured migration via `ak migrate`
LangGraph	Structured migration via `ak migrate`
Google ADK	Structured migration via `ak migrate`
Strands	Structured migration via `ak migrate`
AgentCore	Structured migration via `ak migrate`
Dify	Agentic migration via `ak migrate --execution in-place` in a Dev Sandbox
Any (generic)	Agentic migration via `ak migrate --execution in-place` in a Dev Sandbox; suitable for projects that do not fit the above frameworks

Upload the project archive

On the Add Agent menu, choose “Migrate an existing project” and upload a .zip archive of up to 20 MiB (20 MiB maximum after extraction).

Automatic analysis

Studio creates a user-owned Dev Sandbox Session (1-hour TTL) and invokes the preinstalled Codex to perform read-only analysis of the uploaded project, identifying the framework, entry file, and migration boundary. The analysis includes confidence scores with evidence (file paths and line numbers) for each framework, a recommended framework and entry, open questions for the user, and the migration boundary (included and excluded files).

Confirm migration parameters

After analysis, confirm the framework, entry file (required for Structured frameworks), and application name, answer any open questions, and confirm the migration boundary to start the migration.

Run migration

Structured frameworks run ak migrate for direct conversion; Dify and Any run ak migrate --execution in-place with Codex assistance in the same Dev Sandbox Session. All state, logs, and artifacts remain within the Session.

Preview, download, or deploy

After migration completes, preview the migrated files in Studio, download a ZIP, or deploy directly to AgentKit. During deployment, Studio resolves and verifies the migration artifact from the current user’s Session server-side, without relying on browser-submitted files.

Migration runs in a Dev Sandbox Session with a 1-hour TTL. Once the Session expires, preview, download, and deployment from the temporary migration environment are no longer available; saved source versions in persistent storage are unaffected and remain accessible from the “Migrated projects” page for viewing, downloading, deploying, or restoring. When persistent storage is not configured, migration artifacts are only available within the Session TTL. The entry-point file in the migrated artifact runs inside the deployed AgentKit Runtime — deploy only trusted projects.

When deploying a migration artifact to AgentKit, Studio automatically adapts model environment variables (MODEL_AGENT_API_BASE, MODEL_AGENT_NAME, and MODEL_NAME) to the current cloud provider, ensuring the migrated project uses the correct model endpoint and model name in the target cloud environment.

When deploying a migration artifact to AgentKit, the default Dockerfile generated by Studio uses the entry point specified in common.entry_point in the migration artifact’s agentkit.yaml as the startup command. If common.entry_point is not declared, Studio falls back to the startup entry point returned by the migration tool. This also applies when deploying saved migration versions.

Before deploying a migration artifact to AgentKit, the migration tool must confirm the artifact is deploy-ready to Runtime. If deploy readiness has not been confirmed, deployment is rejected with a message that the migration artifact has not been confirmed as deploy-ready to Runtime; retry after the migration completes.

During analysis and migration, the “Codex activity” panel renders Codex’s progress in a structured form: analysis and migration plans show per-item completion status and progress, with the first incomplete plan step automatically marked as in progress; command execution, file updates, external tool calls, web searches, and sub-task coordination each display their input, output, and exit code or error details, and activity items that fail are automatically expanded to show error details. The panel header shows a live status label for the current migration phase (analyzing the project, running the migration, verifying the migration, packaging the migration, reviewing the delivery). Progress is pushed through a live event stream that reconnects automatically on connection loss and resumes the progress display. All activity content is redacted server-side before reaching the browser; keys, tokens, and other sensitive fields are removed.

When Codex needs user input during migration, the “Codex activity” panel shows the pending question. The user’s answer continues the current step without restarting it. Pending questions support selecting preset options or entering a free-form answer.

The migration composer includes a model selector next to the archive upload button, used to specify the model the Dev Sandbox Codex uses for migration analysis and conversion. The model list is fetched by the Studio server from Ark models activated under the current account, showing only models that the current cloud provider allows for intelligent development, with their display name, ID, vendor, and lifecycle status; the list supports search filtering. The default model comes from the migration capabilities; when none is configured, the first available model is selected. The list can be reloaded on load failure. Once a task is created, the model cannot be changed. The selected model’s name, provider, and API base URL are injected into the migration session environment by the Studio server without sending model credentials to the browser.

After a successful migration, the source is automatically saved as an immutable project version in the private Studio TOS bucket, sharing the same persistent storage as intelligent-development project versions. Saved versions do not depend on the temporary migration environment — even after the Dev Sandbox Session expires, the standalone “Migrated projects” page lets you view, download, deploy, delete, or compare versions, and restore any version into a new intelligent-development session for another intent-driven iteration. Saving source versions requires the administrator to configure Studio persistent storage (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION); when not configured, migration artifacts are only available within the Session TTL. See Studio persistent storage for configuration.

Check	Limit	Description
Archive size	20 MiB	Maximum size of a single uploaded archive.
Uncompressed size	20 MiB	Maximum total size after extraction.
Session TTL	1 hour (2 hours when evaluation is enabled)	Lifetime of the Dev Sandbox Session; artifacts in the temporary migration environment become unavailable after expiry.
Framework selection	—	Structured frameworks (LangChain, LangGraph, Google ADK, Strands, AgentCore) require an entry file; Dify and Any do not accept a Structured entry.
Application name	63 characters	Lowercase letters, digits, and hyphens only; must start and end with a letter or digit.
Artifact safety	—	Each file in the migration ZIP is verified against the manifest by size and SHA256; path traversal, symlinks, and files that modify Agent runtime methods are rejected.
Delivery content	—	When downloading a ZIP or deploying a migration artifact, the delivery includes configuration files from the project’s `.agentkit/` directory (such as `agentkit.yaml` and `Dockerfile`) but excludes build artifacts and migration session state within that directory.

Migration effect evaluation

Migration effect evaluation is an optional step in existing-project migration. When enabled, Studio automatically deploys a temporary Runtime, executes evaluation cases against the migrated agent, scores the behavioral differences between the original and migrated agents, and generates a viewable and downloadable HTML report. Evaluation is off by default and does not affect the migration flow when disabled. Evaluation failure or cancellation does not hide or roll back the migration artifact; saved source versions remain fully usable.

Migration effect evaluation requires the administrator to configure Studio persistent storage (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION). When not configured, the evaluation toggle shows “Migration effect evaluation is unavailable in this environment” while migration itself is unaffected. See Studio persistent storage for configuration.

Enabling evaluation

When creating a migration task, the “Migration effect evaluation” toggle in the migration workspace is off by default. When enabled, the workspace shows two tabs — “Migration” and “Evaluation” — letting you configure evaluation cases while migration is in progress. Enabling evaluation extends the Dev Sandbox Session TTL from 1 hour to 2 hours to accommodate temporary Runtime deployment, case execution, and evaluation analysis.

Configuring evaluation cases

Before migration completes, fill in evaluation cases on the “Evaluation” tab. Cases are locked once upload starts and cannot be modified. Two input methods are supported:

Input method	Description
Manual	Add cases one by one, entering user input, expected outcome, and requirements.
Paste multiple	Enter one case per line as user input for quick bulk addition.

Each evaluation case includes:

Field	Required	Type	Limit	Description
User input	Yes	`str`	Conversation text per case up to 32 KiB; at most 20 messages per case	The real user request the migrated agent should handle.
Expected outcome	No	`str`	Up to 16 KiB	Describe what the agent should accomplish; exact wording is not required.
Requirements	No	`list[str]`	At most 20 items; each up to 2 KiB	Specific conditions the agent output must satisfy.

The total normalized dataset must not exceed 10 MiB, with 1–100 cases.

Evaluation dimensions

Evaluation dimensions determine which aspects of behavioral consistency are checked in the report. Two modes are supported:

Mode	Default dimensions	Description
Standard evaluation	Semantic fidelity, output contract, workflow/tool fidelity	Suitable for most migrations; dimensions cannot be changed.
Custom dimensions	User selects from the dimensions below	Choose one or more dimensions based on business risk.

Available dimensions:

Dimension	Description
Semantic fidelity	Checks whether intent, conclusions, and key facts remain consistent.
Output contract	Checks required fields, structure, language, and formatting constraints.
Workflow and tool fidelity	Checks observable workflow branches and tool-driven behavior.
Context and memory fidelity	Checks supported multi-turn context and memory behavior.
Boundary and error fidelity	Checks invalid input, missing information, and dependency failures.
Safety and refusal fidelity	Checks existing authorization, refusal, and sensitive-data boundaries.

The evaluation method and dimensions cannot change after upload starts.

Evaluation workflow

Once the migration artifact is deployable, evaluation runs automatically in the following order:

Prepare evaluation environment: Validate the migration artifact and evaluation cases.
Provide environment variables (only when required): If the migration artifact declares required or optional environment variables, Studio pauses evaluation and prompts for input. Submitting the variables resumes evaluation.
Deploy temporary Runtime: Deploy a temporary Runtime from the migration artifact to execute evaluation cases.
Execute cases: Send each evaluation case to the temporary Runtime and capture output and raw Runtime observations.
Run evaluation analysis: In a single resumable Codex thread, score the behavioral differences between the original and migrated agents per dimension, generating evidence and gap descriptions.
Generate evaluation report: Aggregate per-dimension scores, evidence coverage, and execution results into an HTML report.

The temporary Runtime deployed during evaluation is always cleaned up before evaluation completes or is cancelled. Regardless of whether evaluation succeeds or fails, Studio reconciles Runtime cleanup on completion or cancellation, ensuring no cloud resources are left behind.

If migration does not produce an evaluable artifact (migration failed or was cancelled), evaluation is automatically cancelled and does not execute.

Evaluation report

After evaluation completes, the “Evaluation” tab shows a report summary including overall fidelity score (0–100), evidence coverage, execution success rate, N/A count, lowest-scoring cases, execution issues, and critical evidence. The report does not issue a pass/fail verdict; it presents quantitative scores and difference evidence. Click “View report” to preview the full HTML report in a side drawer, with download support. The report and the locked evaluation dataset are stored as immutable assets in the private Studio TOS bucket, accessible only to the task owner.

Report field	Description
Overall fidelity	0–100 score; N/A when evidence is insufficient.
Evidence coverage	Ratio of dimensions with evidence to total dimensions.
Execution success	Ratio of successfully completed cases to total cases.
N/A count	Number of dimensions with insufficient evidence, excluded from scores.
Lowest-scoring cases	Cases with the lowest scores and their difference evidence.
Execution issues	Cases that failed to execute and their error details.
Critical evidence	Evidence entries with Critical severity.
Evaluation limitations	Known limitations affecting the evaluation conclusion.

Scores are deterministic: each raw dimension score is rounded half up to a 0–100 integer before aggregation. Case scores and dimension averages are computed from those integers, and the overall score is the average of rounded dimension averages. Each average rounds half up and excludes N/A values, ensuring that scores at every level are consistent with report validation and lowest-scoring case rankings.

Evaluation states

The migration task list and the “Evaluation” tab display the current evaluation state:

State	Description
Evaluation is off	Migration effect evaluation is not enabled.
Waiting for evaluation cases	Evaluation is enabled but cases have not been saved yet.
Evaluation starts automatically after migration	Cases are saved; waiting for migration to complete.
Preparing the evaluation environment	Validating the migration artifact and evaluation cases.
Runtime environment variables are required	The temporary Runtime needs environment variables to start.
Deploying a temporary Runtime	Deploying the temporary Runtime for evaluation.
Running evaluation cases	Executing evaluation cases and capturing output.
Running evaluation analysis	Scoring per dimension and generating evidence.
Aggregating evaluation results	Summarizing scores and evidence, generating the report.
Evaluation completed	The report is ready for viewing and download.
Evaluation incomplete	An error occurred during evaluation.
Evaluation requires attention	The migration artifact is not deployable or session time is insufficient; resolve and retry.
Evaluation cancelled	The user manually cancelled evaluation, or migration did not produce an evaluable artifact.

Failed evaluations can be retried. Retrying reuses the same locked dataset and dimension configuration, redeploys the temporary Runtime, and re-executes. If the migration artifact declares environment variables, they must be re-entered on retry.

When evaluation fails, the progress bar highlights the failed stage (preparing the evaluation environment, deploying the temporary Runtime, executing cases, evaluation analysis, or aggregating results). The failure panel shows diagnostic information including the failure stage, error code, task ID, evaluation attempt, Runtime name, and error details. Error details are derived from the temporary Runtime deployment or evaluation execution output, redacted and truncated on the server before display, and can be expanded or collapsed.

Add skills

When creating an agent, add skills from the following sources. Skill files are written to the generated project’s skills/ directory:

Skill Hub: Search the public Volcengine skill repository by keyword and add a skill.
Local upload: Drag in a folder or select a ZIP archive. Each skill directory must contain SKILL.md. Studio checks file presence, count, size, and path safety, and automatically ignores macOS metadata files inside __MACOSX directories; ADK performs full frontmatter and skill-format validation at load time. The generated skill directory uses the name field from SKILL.md or the uploaded directory name.
AgentKit SkillSpace: Browse skill spaces visible to the current account, then select a skill and version.

Browsing AgentKit SkillSpaces and their skills is performed by the Studio server using its own configured Volcengine credentials; the browser never sees credentials. For a local Studio, grant access through VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY. A VeFaaS deployment uses temporary credentials from its bound IAM role. When SSO login is enabled, you must be signed in to Studio before browsing skill spaces. The skill-space list returns every space visible to the current account across all regions by default. After you select a space, Studio loads its skills in the space’s region. Use the refresh button to reload a list.

Symptom	Check
Studio reports missing Volcengine credentials	For a local Studio, check `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`. For VeFaaS, check the bound IAM role. Credentials remain on the server and are never delivered to the browser.
Studio prompts you to sign in	When SSO is enabled, sign in to Studio before browsing skill spaces.
The skill-space or skill list is empty	Confirm that the current credentials can view skill spaces in the corresponding region and that the selected space contains skills; use the refresh button when necessary.
A list does not load	Check the Studio login session, network access, and credential permissions, then use the refresh button to retry.

Local uploads no longer enforce SKILL.md name and description format or require the directory name to match name at import time. If a skill fails at runtime, check that the SKILL.md frontmatter meets ADK skill requirements.

When adding a skill from AgentKit SkillSpace, Studio downloads SKILL.md, scripts, references, and assets when the cloud version provides a complete package; otherwise it uses SKILL.md only. There is no fixed limit on the number of skills added to one agent.

Generate an agent draft from a requirement

The custom-creation build canvas offers a “smart generate” entry above the canvas. Describe your goal in one sentence, for example “Create a short-video production agent that performs trend research, script writing, asset production, video generation, and quality review in order,” and select “smart generate”. Studio calls the doubao-seed-2-0-lite-260428 model to produce a validated, complete agent-configuration draft that is loaded onto the canvas. Generation consumes tokens.

The generated result replaces the current canvas and property configuration. When the canvas has unsaved changes, Studio asks for confirmation before continuing.

Structure of the generated draft

The generated configuration follows these rules:

The root agent is preferably an LLM agent so it can reason and respond directly to the user. An orchestrator is used as the root only when strict workflow control is essential to the requested result, not merely because the requirement involves multiple tasks or steps.
Orchestrator agents (sequential, parallel, loop) only schedule sub-agents and do not carry a model, instruction, tools, memory, knowledge base, or tracing configuration.
LLM agents are always leaf nodes. Their name, description, instruction, model, and tools are populated automatically, and they cannot contain sub-agents.
Every generated LLM agent uses the doubao-seed-1-6-250615 model.
The iteration limit for orchestrator agents defaults to 3; loop agents use the limit stated in the requirement.
All agent and custom-tool names are globally unique snake_case Python identifiers.
Tools are enabled only when the requirement needs them; review-only agents are not given media-generation tools.
Smart generation does not configure memory, knowledge base, or tracing. These capabilities are always disabled in the generated draft, with their backends left at the defaults (memory uses local; the knowledge base uses viking). To enable them, configure them manually on the canvas after generation.

The generated agent can select from these built-in tools:

Tool identifier	Description
`web_search`	Searches the public Internet through the fused information search API.
`parallel_web_search`	Runs several web searches in parallel.
`link_reader`	Reads and parses the web content of given URLs.
`image_generate`	Generates images from text prompts.
`image_edit`	Edits an existing image.
`video_generate`	Generates video from text or image inputs.
`run_code`	Executes code in a sandbox.

The generated configuration does not assign an enterprise knowledge-base search tool to an LLM agent. Memory, knowledge base, and tracing can be enabled on the canvas after generation; see the corresponding component pages for each backend’s full parameters.

When BytePlus is the cloud provider, web_search and parallel_web_search are not shown in the built-in tool list for custom creation or smart generation; Volcengine mode is unaffected.

Unresolved items

The result lists real resources or identifiers that still need to be provided (such as instance IDs, URLs, credentials, MCP servers, or skill IDs). Studio does not invent them; after generation, supply the actual resources on the canvas as needed.

Steps

Enter the requirement

Describe the goal in natural language in the input above the build canvas. The input is limited to 8,000 characters.

Generate the configuration

Select “smart generate”. The input is dimmed during generation; when it finishes, the new draft is loaded onto the canvas along with a one-sentence summary.

Review unresolved items

Check the unresolved-items list in the result and supply the actual resources or identifiers on the canvas as needed.

Adjust and test

Review and edit the configuration as in custom creation, then generate the project and start a temporary test, download a ZIP, or deploy to AgentKit.

After generation you can select “regenerate” to produce a new configuration from the same requirement.

Permissions and failure handling

When role-based access control is enabled, smart generation is available only to developer and admin users. On failure, Studio shows an error dialog. Common cases include:

Symptom	Check
Generation timed out	Generation is limited to 180 seconds on the server. On timeout it returns a timeout prompt; retry after shortening the requirement.
Model call failed	Check the Volcengine credentials and model access permissions. Error details are credential-redacted.
Access denied	Confirm the current account has the `developer` or `admin` role.

Add a remote agent

Remote agents are discovered and invoked through an AgentKit agent center. Use them to connect specialized capabilities that have already been published to a center. A remote agent can only be a sub-agent, not the root agent; the root must use the LLM, sequential, parallel, or loop type. Before using this capability, make sure that:

Studio has cloud-provider credentials that can access AgentKit (Volcengine or BytePlus). For a VeFaaS deployment, the bound IAM role must have the corresponding permissions.
The default project in the target region contains at least one AgentKit agent center visible to the current account, and that center contains an invokable remote agent.
If Studio role-based access is enabled, the current user has the developer or admin role.

Configure the root agent

Create an LLM or orchestrator root agent and complete the required model, description, and instruction settings.

Add a remote-agent node

In the agent structure, add a sub-agent to the root or another local agent, then select Remote Agent as its type. The remote-agent type is unavailable on the root node.

Select an agent center

Studio initially lists centers visible to the current account in the default project in the Volcengine Beijing region (ap-southeast-1 for BytePlus). For another region, set the region under More options before selecting a center from the dropdown. Use the refresh button to reload the list.

Configure discovery scope

Set the recall count and OpenAPI endpoint when needed. The remote agent’s name, description, and capabilities come from the Agent Card returned by the center, so you do not enter a separate name or A2A URL.

Test the invocation

Generate the project, start a temporary test, and enter a request that requires a specialization available in the selected center. If the response uses information returned by a matching agent in the center, discovery and invocation are working.

For each turn, the parent agent discovers remote agents in the selected center that match the user’s request and makes them available for invocation.

Studio setting	Generated-project setting	Type	Required	Default	Description
AgentKit agent center	`REGISTRY_SPACE_ID`	`str`	Yes	—	Center used to discover remote agents; selected from a dropdown in Studio.
Agent recall count	`REGISTRY_TOP_K`	`int`	No	`3`	Maximum number of matching agents recalled for each turn; the effective range is 1–20.
AgentKit agent center region	`REGISTRY_REGION`	`str`	No	Volcengine: `cn-beijing`; BytePlus: `ap-southeast-1`	Region that contains the agent center. Changing it reloads the dropdown for the new region. The default follows the selected cloud provider.
AgentKit agent center OpenAPI endpoint	`REGISTRY_ENDPOINT`	`URL`	No	Volcengine: `https://open.volcengineapi.com/`; BytePlus: `https://agentkit.ap-southeast-1.byteplusapi.com/`	OpenAPI endpoint used by the generated project to reach the center. Change it only when another public endpoint is required. The default follows the selected cloud provider.

For example, create an LLM root agent named support_router, add a remote-agent child, select the Customer Service agent center, and keep the recall count at 3 and the region set to the Volcengine Beijing default. During testing, enter “Investigate this order’s delivery exception and recommend a resolution.” If the center contains a matching capability, the root agent invokes the corresponding remote agent to complete the task.

Troubleshoot remote agents

Symptom	Check
Studio reports missing cloud-provider credentials	For a local Studio, check the credentials for your cloud provider (`VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY` for Volcengine, `BYTEPLUS_ACCESS_KEY` and `BYTEPLUS_SECRET_KEY` for BytePlus). For VeFaaS, check the bound IAM role. Credentials remain on the server and are never delivered to the browser.
The dropdown is empty	Confirm that an agent center exists in the `default` project in the selected region and that the current credentials can view it.
The agent-center list does not load	Check the Studio login session, network access to the AgentKit OpenAPI, and credential permissions, then use the refresh button to retry.
Project generation or testing cannot start	Confirm that the remote agent is below the root agent and that an agent center is selected.
Testing does not discover an available agent	Confirm that the center contains an invokable agent matching the test request; adjust the recall count when necessary.
Discovery succeeds but remote invocation fails	Check the region, OpenAPI endpoint, agent status in the center, and the runtime’s AgentKit permissions and network access.

The temporary test process is retained for 1,800 seconds by default and can be changed with --generated-agent-test-run-ttl. Each logged-in user can run at most 3 generated-agent test processes concurrently; exceeding the limit returns 429 with a prompt to close unused debug pages and retry. Studio reclaims test processes left behind after a page refresh, and a single test run accepts at most 300 project files. Generated code can call external services or access data available to Studio, so test only trusted projects and give Studio restricted credentials.

Test runs validate tool discovery for HTTP MCP tool endpoints configured on a generated agent over Streamable HTTP. If Studio cannot reach the MCP server to discover tools, the test returns an error with a specific troubleshooting hint based on the failure reason, including authentication rejected, the address does not provide a usable MCP service, rate limiting, service temporarily unavailable, connection succeeded but no tools found, connection timeout, network connection failure, or the service response does not conform to the MCP protocol; the original URL saved on the canvas is not modified.

Debug runs support only the official Ark model endpoint for the current cloud provider. Agents configured with a custom model endpoint cannot start in a debug run; use the official endpoint or test through a deployed Runtime instead.

When Studio is deployed in the cloud (running on VeFaaS), debug runs validate MCP and A2A endpoint addresses: only private endpoints within the VPC attached to the Studio function are allowed; private addresses outside that VPC, loopback addresses, link-local addresses, and cloud metadata addresses are blocked. Locally started Studio is unaffected and still allows local resources. If Studio cannot determine the VPC ranges (for example, when VPC is not enabled on the function or the function role lacks VPC and subnet read permissions), the debug run fails with guidance to check VPC configuration and IAM permissions. VPC range information is cached for 5 minutes on the Studio server.

Configure memory

After enabling long-term memory for an agent, select one of these backends in Studio:

Backend	When to use
Local vector store	In-process vector store for local debugging; not persistent and requires an embedding model.
OpenSearch	Uses a self-managed or managed OpenSearch cluster with your embedding model.
Redis	Uses Redis vector retrieval with your embedding model.
VikingDB Memory	Managed Volcengine VikingDB memory store (supports user profiles) using Studio’s Volcengine credentials.
OpenViking	OpenViking long-term memory that stores and retrieves preferences, events, and entities per user.
mem0	Mem0 hosted memory service.

Connection and embedding-model parameters for the local, OpenSearch, Redis, and mem0 backends are written to the generated project as environment variables. VikingDB Memory and OpenViking use the Volcengine credential chain, forwarded by the Studio server to debug runs and AgentKit runtimes, so AK/SK do not need to be re-entered on the creation page. For full parameters, defaults, and limits, see each backend’s component page. When you select VikingDB Memory, Studio lists memory collections visible to the current account in the current cloud provider’s region via server-side credentials. The list queries collections from the projects specified by the DATABASE_VIKINGMEM_PROJECT and VEADK_STUDIO_PROJECT environment variables, then the default project. Selecting an existing collection uses its name as the long-term memory collection index, and Studio automatically fills the project, region, and memory types (mapped to the DATABASE_VIKINGMEM_PROJECT, DATABASE_VIKING_REGION, and DATABASE_VIKINGMEM_MEMORY_TYPE environment variables, which are not shown on the creation page). If you do not select an existing collection, the collection name is auto-generated from the agent name, and the collection is created at runtime if it does not exist. Use the refresh button to reload the list. For a local Studio, provide access through VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY. A VeFaaS deployment uses temporary credentials from its bound IAM role. Credentials remain on the server and are never delivered to the browser. When you select OpenViking, Studio collects the following settings on the creation page and writes them to the generated project’s environment variables:

Studio setting	Generated env var	Required	Default / placeholder	Description
OpenViking service URL	`DATABASE_OPENVIKING_URL`	Yes	`https://api.vikingdb.cn-beijing.volces.com/openviking`	OpenViking service URL, available in the console.
OpenViking API key	`DATABASE_OPENVIKING_API_KEY`	Yes	—	OpenViking API key, available in the console.
Memory owner ID	`DATABASE_OPENVIKING_USER_ID`	No	`default`	The `user` segment in `viking://user/<this value>/peers/<requesting user>/memories`; isolates agents, tenants, or business scenarios.
Memory policy	`DATABASE_OPENVIKING_MEMORY_POLICY`	No	—	Memory extraction and isolation policy as JSON; when left blank the OpenViking service applies its official default, with the structure following the OpenViking session API.

The OpenViking memory owner ID (DATABASE_OPENVIKING_USER_ID) and the runtime user identifier (Runner.user_id) are distinct concepts: the former isolates memories per application or tenant, while the latter serves as the OpenViking peer ID to isolate end-user memories. See Store memory in OpenViking.

Enabling OpenViking long-term memory writes conversation data to an external OpenViking service. Confirm that data processing, access control, and retention meet your requirements before enabling it.

Configure a knowledge base

After enabling a knowledge base for an agent, select one of these backends in Studio:

Backend	When to use
VikingDB Knowledge	The default. Uses the managed Volcengine knowledge base service for server-side splitting, embedding, and retrieval, without local embedding configuration.
OpenSearch	Uses a self-managed or managed OpenSearch cluster with your embedding configuration.
Context Search	Uses the Volcengine Context Search service for retrieval.
OpenViking Knowledge	Uses the OpenViking resource-tree knowledge base with server-side resource processing and retrieval, without local embedding configuration.

Studio does not offer the local backend because its creation flow cannot add documents to the in-process vector store. For local development, use the VeADK SDK to configure a local knowledge base. When you select VikingDB Knowledge, Studio lists collections visible to the current account in the default project in Beijing. Selecting an existing collection uses its name as the knowledge base index. If you do not select an existing collection, the index name defaults to <agent_name>_kb. Use the refresh button to reload the list. For a local Studio, provide access through VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY. A VeFaaS deployment uses temporary credentials from its bound IAM role. Credentials remain on the server and are never delivered to the browser. When you select OpenViking Knowledge, Studio collects the following settings on the creation page and writes them to the generated project’s environment variables:

Studio setting	Generated env var	Required	Default / placeholder	Description
OpenViking service URL	`DATABASE_OPENVIKING_URL`	Yes	`https://api.vikingdb.cn-beijing.volces.com/openviking`	OpenViking service URL, available in the console.
OpenViking API key	`DATABASE_OPENVIKING_API_KEY`	Yes	—	OpenViking API key, available in the console.
Knowledge owner ID	`DATABASE_OPENVIKING_USER_ID`	No	`default`	OpenViking owner/context used to build the default resource URI `viking://user/<this value>/resources/<resource index>/`.
Knowledge resource URI	`DATABASE_OPENVIKING_TARGET_URI`	No	—	Resource URI used for ingestion and retrieval; when left blank it is auto-generated from the knowledge owner ID and resource index. When set, this URI is used directly with the highest priority.

Studio also provides a “Resource index” field that sets the KnowledgeBase index. When left blank, the generated project auto-generates the index from the agent name (e.g., my_agent_kb). When DATABASE_OPENVIKING_TARGET_URI is not configured, the resource URI is built as viking://user/<knowledge owner ID, or "default" if not set>/resources/<resource index>/; once DATABASE_OPENVIKING_TARGET_URI is set, that full URI is used directly.

The OpenViking knowledge owner ID (DATABASE_OPENVIKING_USER_ID) and the runtime user identifier (Runner.user_id) are distinct concepts: the former isolates resource trees per application or tenant, while the latter identifies the end user. See Store knowledge in OpenViking.

Enabling the OpenViking knowledge base sends imported documents to an external OpenViking service. Confirm that data processing, access control, and retention meet your requirements before enabling it.

Symptom	Check
The knowledge base list is empty	Confirm that the `default` project in Beijing contains a VikingDB knowledge base collection and that the current credentials can view it.
The knowledge base list does not load	Check the Studio login session, network access to VikingDB Knowledge, and credential permissions, then refresh the list.
Project generation or testing fails	Confirm that the knowledge base configuration is complete and that the runtime can access the selected backend.

Add the code-execution tool

Selecting Code execution in the custom agent’s built-in tools adds the run_code tool to the generated Python and reveals the sandbox configuration it depends on, below the built-in tool list. The code, language, and timeout are supplied by the agent at runtime from the run_code tool signature, while tool_context is injected automatically by ADK and does not need to be set in Studio.

Studio setting	Generated-project env var	Type	Required	Default	Description
Code-execution sandbox ID	`AGENTKIT_TOOL_ID`	`str`	Yes	—	AgentKit code-execution sandbox ID used by `run_code`, e.g. `t-xxxxxxxx`.
AgentKit Tools region	`AGENTKIT_TOOL_REGION`	`str`	No	`cn-beijing`	Region for calling AgentKit Tools. In Volcengine mode, when unset it falls back to the `REGION` environment variable and then defaults to `cn-beijing`; BytePlus mode does not read `REGION` and uses the BytePlus default region.

Both values apply to local debug runs and deployed runtimes, and the generated .env.example includes both variables. The sandbox ID and region are used only on the Studio server and are never delivered to the browser.

For the full parameters, shell execution, and credential requirements of run_code, see the Code sandbox.

View sub-agent handoffs

In multi-agent projects, the root agent can hand a task off to a sub-agent for execution. When a handoff occurs, Studio shows the sub-agent’s replies in a dedicated card labeled “Agent handoff” that displays the sub-agent’s name and description, instead of mixing the sub-agent’s output into the root agent’s reply bubble. The sub-agent’s name and description come from the agent configuration in the project structure. If the sub-agent has no description, the card shows a default note. After the sub-agent finishes, subsequent replies continue to appear as the root agent’s messages.

This presentation applies to both local sub-agents and remote agents. A remote agent can only be a sub-agent and cannot be the root agent.

Conversation traces and issue feedback

On the conversation page, each assistant reply provides trace and issue-feedback controls to help investigate a single turn. These controls are available only in regular agent conversations and are not shown in built-in Codex agent conversations.

View the call trace

The “Tracing flame graph” button next to an assistant reply opens the call-trace observation panel, which renders the session’s execution trace as a span tree with a detail panel and uses the reply’s end time as the query cutoff when opened.

Local debug sessions read the ADK debug trace directly.
For a connected cloud Runtime, the Studio server queries APMPlus for the session trace using its own cloud-provider credentials; the browser never touches the credentials. The APMPlus OpenAPI endpoint follows the configured cloud provider: open.volcengineapi.com for Volcengine and open.byteplusapi.com for BytePlus.

Trace observation for a cloud Runtime requires enabling APMPlus tracing for the corresponding agent in the Volcengine console. Runtimes deployed through Studio have APMPlus tracing enabled by default. When the trace panel opens, Studio displays different states depending on the query result:

State	Description
Loading	Querying APMPlus for trace data.
Collecting	Trace data has not arrived in APMPlus yet; the panel shows a collecting state with a retry button. Studio retries automatically up to two times before requiring a manual retry.
Not enabled	The Runtime does not have tracing enabled; the panel prompts you to enable it in the console and retry.
Forbidden	The Studio runtime role lacks APMPlus read permission; the panel prompts you to contact an administrator to grant access.
Load failed	The trace query encountered another error; the panel provides a reload button.

When querying traces, the Studio server first locates the target trace by the POST /run_sse entry span; if no match is found, it falls back to a broad scan of the session time window and selects the trace closest to the reply end time. Trace data may be temporarily unavailable due to collection latency and should appear after a short retry.

When displaying model output in the trace panel, Studio automatically removes empty placeholders (null entries) produced during streaming progression, showing only the actual content parts.

Issue feedback

The “Issue feedback” button next to an assistant reply reports a problem for that turn. In the dialog, select an issue type and add a description before submitting. The submission includes the turn’s input, output, tool-call records, and trace information for investigation, and is redacted for credentials before being sent. Available issue types:

Issue type	Description
Slow execution	Reply generation or tool calls took too long.
Crash	Agent execution was interrupted or errored.
Inaccurate result	The reply did not match expectations or contained errors.
Tool call failure	A tool execution failed or returned an exception.
Other	Anything not covered above.

The “Issue feedback” entry in the sidebar footer (labeled Beta) reports general Studio issues: select the affected module, an issue type, and add a description before submitting. The module corresponds to the current page and can be Conversation, Agents, Automation, Search, or Other; platform issue types include slow page loading, unavailable features, display anomalies, no response, and other issues.

Issue feedback is sent to the AgentKit team to improve the product; a confirmation appears after a successful submission. Avoid entering keys, tokens, or other sensitive information in the description. Feedback may fail when the current session is unavailable; close and retry in that case.

Export a conversation

The “Export conversation” button next to an assistant reply exports all inputs and outputs up to that turn as a PNG image or PDF file. The export is generated locally in the browser without any network request. It includes every user message and assistant reply from the start of the session through the current turn, and appends a note reading “上述会话由 AgentKit Studio 导出，仅供参考” at the bottom. Once generation finishes, the export can be previewed in the dialog, and you can choose an export format:

Format	Description
PNG	Exports all inputs and outputs as a single PNG image. Supports downloading or copying to the system clipboard.
PDF	Exports all inputs and outputs as a paginated PDF file. Generation automatically breaks pages at blank areas to avoid truncating content; the PDF is generated on demand in the browser, starting only when this format is selected and download is clicked.

Copy to clipboard is available only for PNG format and relies on the browser’s clipboard write capability; when unsupported, the dialog prompts you to use Download instead.

The button is available in both normal agent conversations and built-in Codex agent conversations, and appears only after a reply is complete (not while streaming or awaiting OAuth authorization). When the conversation is too long and the resulting image would exceed the browser’s canvas limit, generation fails with a message indicating the conversation is too long; you can retry after shortening the conversation.

Use smart search

Smart search provides four retrieval sources:

Session: full-text-searches the current agent’s message history.
Web: calls the current agent’s mounted web_search tool.
Knowledge: performs semantic retrieval through the agent’s mounted knowledge base.
Memory: performs semantic retrieval through the agent’s mounted long-term memory backend.

Studio enables only the sources reported by the agent’s metadata and disables unavailable sources. Knowledge and memory results identify their index or source name and backend type.

Deployment network modes

The deploy page lets you choose a network mode for the AgentKit runtime, which determines how it is exposed to the public network:

Network mode	Description
Public	The runtime exposes a public data-plane address.
VPC	The runtime is deployed only inside a specified VPC and subnet and does not expose a public data-plane address; you can enable a shared public egress within the VPC.
Public + VPC	Both a public address and an in-VPC address are assigned.

When you select VPC or Public + VPC, you must provide the VPC ID and subnet ID. A private VPC runtime does not return a public data-plane address after deployment. Studio reaches it through the server-side runtime proxy, and the data-plane API key stays server-side and is never delivered to the browser. This is the same server-side runtime proxy described in “Select a cloud Runtime”.

After a deployment completes, Studio automatically connects to the newly created runtime. Studio retries probing the runtime endpoint for up to 60 seconds before timing out. If the runtime deployed successfully but Studio still cannot reach it after the timeout (the gateway domain may still be propagating, or the current network or DNS cannot access the runtime), the deployment task is marked “Deployed, not yet connected” and the progress card with its message stays visible. You can retry the connection from Manage Agents.

When CloudApp communicates with a deployed agent endpoint over the A2A protocol, HTTP proxy selection follows the VeFaaS SDK convention: it reads the environment variable matching the endpoint URL scheme (HTTPS_PROXY or HTTP_PROXY, uppercase preferred over lowercase) and does not use ALL_PROXY, NO_PROXY, or system proxy settings. To reach a deployed agent through a proxy, set the proxy environment variable matching the endpoint scheme.

Manage agents

Manage Agents lists the AgentKit Runtimes visible to the current user. Visibility is determined by the signed-in account role: admin sees all Runtimes, while developer and regular users see their own Runtimes and agents approved as enterprise-visible. The list defaults to the Beijing region and can be switched to Shanghai. When the visible scope includes all Runtimes, Runtimes created by the current user are marked “Created by me.” Each agent card shows its visibility status (private or enterprise-visible) and review status (pending, approved, returned, withdrawn). The list exposes:

Runtime name, ID, status, region, and creation time;
Model, description, project, version, resources, and update time;
Bound Memory, Tool, Knowledge, and MCP Toolset identifiers;
Runtime environment variables and primary-agent information.
Agent topology, remote traces, and global deployment-task state.

Studio does not store the Runtime API key in the browser. The management page therefore shows the primary-agent summary returned for the Runtime and does not load the complete sub-agent tree.

Delete permanently removes the corresponding AgentKit runtime. Confirm that it no longer serves traffic and back up required data and configuration before proceeding.

An agent with a pending review application must be withdrawn first, and a published agent must be unpublished first, before it can be modified or deleted. See Agent publication review.

Before deleting, Studio shows a confirmation dialog listing the agents or drafts that will be removed; deletion only proceeds after confirmation. While deletion is in progress, the affected agents are temporarily hidden from the list. If the deleted agent is the one in use for the current conversation, Studio clears the current selection and returns to the agent management page.

The management page can display runtime environment-variable values. Restrict Studio to authorized users and avoid storing plaintext secrets in ordinary environment variables; prefer the platform’s secret-management features. The agent workspace unifies deployed Runtimes and local drafts. Each deployed agent shows its current version number and a deployment status: deploying, update pending, not yet published, failed, or cancelled. A deployed agent can be edited directly in the workspace and updated on the same Runtime without creating a new deployment.

When a build or deployment stage fails, Studio shows the complete error message returned by the service, expanded by default and copyable, so you can locate the problem directly. Deployment and update failures can also be retried from the error panel. When a deployment fails or is cancelled, the progress card provides a “Return to edit” button that takes you back to the draft so you can adjust the configuration and start a new deployment.

Manage drafts

During custom creation, Studio saves unpublished agent drafts in the current browser, isolated by signed-in user. Drafts appear alongside deployed Runtimes in the Manage agents list, each showing its update time and a “Draft” badge. A draft being deployed shows a “Deploying” badge and lets you view its deployment progress. Drafts can be edited or deleted; deletion asks for confirmation first.

Drafts are stored only in the current browser and are not synced to the server or other devices. Clearing browser storage, using private browsing, or switching browsers discards them.

MCP tool auth tokens are converted to environment-variable references: generated source retains only the ${ENV_NAME} reference, with the token value written to deployment environment variables; YAML exports and browser drafts preserve the corresponding environment value. Updating a deployed Runtime reloads existing environment values, and entering a replacement Token overrides the previous value. When an MCP tool’s service URL is changed, the stored credential is not silently replayed; the Token input is always editable and supports a show/hide toggle.

Drafts use the browser’s local storage. When storage is full or writes are rejected, Studio shows the corresponding reason; remove unneeded drafts or clear site storage and retry.

Hand off a local task to the cloud

Local-to-cloud handoff migrates an in-progress local Codex conversation and project into a Studio cloud Codex Sandbox so the task can continue in the cloud. Use it when local compute, environment, or runtime limits make it preferable to continue a coding task on a cloud Codex. The entry point is on the Codex tab of the “Manage agents” page and is visible only to roles with agent-creation permission (admin and developer).

Handoff transfers only project code and visible conversation history. It does not copy local Codex system prompts, reasoning, tool-call logs, runtime state, SSH private keys, or global configuration. The pairing code is a one-time credential; do not share it publicly.

Install the AgentKit Studio Plugin

On first use, choose an installation method in the “Hand off to the cloud” dialog. Select “Install via Codex conversation” to copy a prompt that you paste into your local Codex conversation so it performs the installation; select “Install from terminal” to copy and run the following command in a local terminal:

codex plugin marketplace add volcengine/veadk-python \
  --sparse .agents/plugins \
  --sparse plugins/agentkit-studio \
  && codex plugin add agentkit-studio@veadk-python

Copy the handoff prompt

After the plugin is installed, click “Copy handoff prompt”. The prompt contains the current Studio URL and a one-time pairing code whose default validity is 20 minutes, shown with a countdown in the dialog. If the code expires or becomes invalid, click “Refresh pairing code” to generate a new one.

Run the handoff in local Codex

Paste the prompt into your local Codex conversation. The plugin bundles the project’s Git-tracked files and non-ignored untracked files, Git metadata, and the visible user and assistant messages from the current task (including local images attached to user messages), uploads them to Studio, creates a temporary cloud Codex Sandbox Session, restores the project, injects the conversation history, and finally sends one continuation message so the cloud Codex continues the task. After upload the cloud task runs independently and the local terminal can be closed.

Track progress and open the cloud session

The “Handoff status” panel shows progress across four stages: “Waiting for local request”, “Creating cloud Session”, “Restoring project”, and “Sending continuation task”. When handoff completes, click “Enter Codex” to open the created cloud Sandbox Session in Studio and continue the conversation.

During handoff the cloud Codex runs in the background; Studio synchronizes the cloud task’s progress and replies in the conversation view. If handoff fails after the Session is created, during project restore or upload, you can retry with the original pairing code and Studio reuses the existing Session instead of creating a duplicate. Conversation history and image migration are subject to the following limits:

Item	Limit
Visible messages	Up to 100
Characters per message	Up to 20,000
Total history characters	Up to 100,000
Images attached to user messages	Up to 10, PNG, JPEG, GIF, or WebP
Per-image size	Up to 4 MB
Total image size	Up to 8 MB
Continuation message length	Up to 20,000 characters
Cloud Session type	Temporary Session only

Handoff environment variables

Environment variable	Default	Description
`STUDIO_CODEX_PROJECT_HANDOFF_PAIRING_TTL_SECONDS`	`1200` (20 minutes)	Pairing-code validity, range 60–3600 seconds. Configured via an environment variable for local startup and written to the VeFaaS Function environment for cloud deployment.

Update a deployed agent

An agent deployed to AgentKit can be edited again in Studio and updated on the same Runtime instead of creating a new deployment each time. The update produces an incremented image version based on the Runtime’s current version and publishes it on the existing Runtime.

Select a deployed agent

In the agent workspace, select a deployed agent. Studio reads the agent’s name, description, model, instruction, tools, and sub-agent structure from the Runtime and loads them into an editable draft.

Modify the configuration

Adjust the model, instruction, tools, skills, or sub-agent structure on the canvas or in the configuration panel, using the same editing capabilities as when creating an agent.

Update and publish

Select “Update and publish”. Studio reports progress through the prepare, build-image, deploy, and publish stages; the deploy stage reuses the existing Runtime identifier and publishes an incremented version.

Verify the update

After the update completes, the agent’s version number increments in the workspace and its status returns to published. Connect the Runtime from the chat view to verify the new configuration.

Cancelling a deployment task during an update does not destroy the existing Runtime; the previous version remains available. Only when creating a brand-new deployment does cancelling the task clean up the unfinished Runtime resources.

Updates are still governed by Studio role permissions: admin can update all Studio-managed Runtimes, developer can update only their own, and regular users cannot update.

When updating a Runtime, Studio loads the existing environment variables from the Runtime and preserves them; values entered explicitly in the deployment form override the existing ones. When a Runtime target is selected for a debug test run, the Runtime environment variables are injected into the test process. MCP tool auth credentials are recovered from the published Runtime’s environment variables and injected into the debug environment for MCP endpoint discovery; if the edited MCP service URL does not match the published configuration, credentials are not recovered. MCP credentials submitted during debug testing are also applied to the deployment runtime environment. Recovered credentials remain server-side and never appear in debug output.

When updating a deployed agent that has Feishu configured, Studio restores the Feishu App ID and App Secret from the Runtime’s environment variables into the update form. Input fields for already-configured variables show “Configured, leave blank to reuse”; leaving them blank preserves the existing values. Disabling the Feishu channel during an update removes both FEISHU_APP_ID and FEISHU_APP_SECRET from the Runtime; keeping it enabled preserves or replaces them with the submitted values. Toggling the Feishu channel on or off on the deploy page regenerates the project to keep app.py, dependencies, and runtime environment variables consistent.

When updating a deployed agent, Studio rebuilds the editable draft exclusively from the Runtime’s currently deployed configuration and does not merge in locally saved drafts. If the Runtime’s agent configuration cannot be read due to a network or server error, the update entry shows a notice and disables the update temporarily; retry after a moment.

Update modes

Studio supports two Runtime update modes, selected automatically based on the Runtime’s current state:

Update mode	Description
Regenerate	Rebuilds the full project image from the edited draft and publishes it. Used for regular updates driven by the draft.
Source-preserving	Keeps the deployed source image unchanged and publishes only the edited configuration (agent draft, skills, and MCP credentials) as an overlay on top of the existing image. Used when the deployed image structure is intact and only configuration needs adjustment.

Source-preserving updates do not rebuild the image, making publication faster, and skill files already baked into the image remain unchanged. This mode only supports editing skills on the root agent; modifying skills in sub-agents is not supported.

Source-preserving update mode does not support model fallback configuration. If the agent draft contains model fallbacks, the update is rejected with a prompt to regenerate the standard project. To use model fallbacks, switch to regenerate mode and ensure the runtime uses veadk-python 1.1.10 or later.

The update mode is determined automatically by Studio based on the Runtime’s current image and configuration. If the deployed image structure does not support source-preserving updates, Studio falls back to regenerate mode.

In source-preserving mode, MCP credential updates rely on authentication references in the published draft. If MCP configuration has changed since publication, Studio prompts you to reopen the agent detail and confirm the latest configuration before updating. When an MCP tool’s service URL is changed, the stored credential is not silently replayed; the Token input is always editable and supports a show/hide toggle.

Legacy Runtime recovery

For Runtimes deployed before the update capability was introduced (missing a published configuration draft), Studio can recover the agent configuration from the deployed image and runtime environment, enabling updates for these older deployments. Recovery includes:

Rebuilding MCP tool configuration from runtime environment variables and MCP toolset;
Extracting deployed skill files from the image;
Generating an editable draft from the recovered configuration.

Legacy Runtime recovery requires the Studio runtime identity to have read-only access to the container registry that hosts the deployed image. If the current identity lacks CR read access, skill files cannot be extracted, and Studio prompts you to grant read-only access to the corresponding CR instance or repository before retrying.

Update safety checks

When updating a Runtime, Studio performs safety checks before and after publishing to prevent concurrent modifications from overwriting the live configuration:

Before publishing, Studio verifies that the Runtime’s version number and image identity match what was loaded during editing. If the Runtime has been modified by another operation in the meantime, the update is rejected and you are prompted to reopen the agent detail.
After publishing, Studio verifies that the Runtime version has incremented and the status is Ready. If the version did not increment or the status is abnormal, the update is marked as failed and you are prompted to refresh the detail to confirm the live state.

When a deployment or update task is already in progress on the same Runtime, new deploy or update requests are rejected with a prompt to wait for the current task to complete before retrying, preventing conflicts from concurrent deployments.

Deployment progress is streamed in real time. During long builds, Studio sends periodic heartbeat keepalive messages to prevent proxies or browsers from timing out on idle connections.

The update capability check may need to read runtime configuration. If the initial check takes too long, a “recovering” state is displayed and the update entry is temporarily disabled; it resumes automatically once the check completes.

Deliver agents through GitHub

Studio can deliver the source generated during custom creation to a GitHub repository with two delivery modes. “GitHub code sync” pushes the generated source directly to the target branch, while the Runtime is still published from the deploy button; “Attach continuous delivery” writes an AgentKit Runtime GitHub Actions workflow to the target branch, and subsequent pushes to that branch automatically build and publish to the bound Runtime. Both modes suit teams that need version control and continuous delivery.

“Attach continuous delivery” writes GitHub Actions Secrets to the repository and requires the github-cicd optional dependency group for encryption. See Installation. “GitHub code sync” does not write Secrets and does not require this dependency.

Delivery modes

After selecting GitHub delivery in the deployment settings, you can switch between the following modes:

Mode	Behavior	Writes workflow and Secrets
GitHub code sync	Studio pushes the generated source directly to the target branch; the branch is managed by Studio and sync fails on remote conflicts. The Runtime is still published from the deploy button.	No
Attach continuous delivery	After the first deployment succeeds, Studio initializes the target branch (writing the source and a GitHub Actions workflow); subsequent pushes to that branch trigger the workflow and update the bound Runtime.	Yes

Configure GitHub delivery

Both modes share the following form fields:

Field	Required	Default	Description
GitHub repository URL	Yes	—	Accepts `owner/repository` or a full GitHub HTTPS/SSH URL; only `github.com` is supported.
GitHub Token	Yes	—	Requires contents write and pull request permissions on the target repository; used only for the current request and never persisted in the browser.
Target branch	No	`main`	Branch the source is pushed to and the workflow listens on.
Volcengine Access Key	Required for continuous delivery	—	Written as a GitHub Actions Secret for the workflow to publish the Runtime.
Volcengine Secret Key	Required for continuous delivery	—	Written as a GitHub Actions Secret.
Volcengine Session Token	No	—	Required when using temporary credentials.

When using BytePlus as the cloud provider, the corresponding Secret names and Runtime publishing credentials are BYTEPLUS_ACCESS_KEY, BYTEPLUS_SECRET_KEY, and the optional BYTEPLUS_SESSION_TOKEN; in Volcengine mode they are VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, and the optional VOLCENGINE_SESSION_TOKEN. The region follows the publish region in the deployment settings.

Attaching continuous delivery encrypts and writes Volcengine or BytePlus credentials to the GitHub Actions Secrets of the target repository. Confirm that the repository’s access scope and collaboration permissions meet your data-security requirements, and use credentials with the least required privileges.

Attach continuous delivery during deployment

When you choose “Attach continuous delivery” while creating a new Runtime, clicking deploy first creates the Runtime and then runs the “Attach GitHub continuous delivery” phase: it initializes the target branch and writes the GitHub Actions workflow, and the deployment flow completes only after initialization succeeds. This phase appears as a separate step in the deployment progress and shows a live GitHub delivery log with sync states (syncing, synced, or read failed) that you can expand and copy; logs are redacted server-side before being sent. The workflow file is written to .github/workflows/publish-agentkit.yml in the repository and is triggered when:

you push to the target branch (commits whose message contains [skip runtime] skip the publish); or
you trigger it manually.

The workflow uses a concurrency group bound to the Runtime, installs the project dependencies and the AgentKit Python SDK, and publishes an incremented Runtime version. In BytePlus mode the workflow additionally injects BytePlus credentials and the memory-region environment variables.

Version management and rollback

After selecting a Runtime that is bound to GitHub continuous delivery in the workspace, the detail page provides a “Versions” tab. It lists the commit history and workflow runs of the target branch; each version shows its commit, branch, source, publish status, and creation time:

Publish status	Meaning
Published	The version has been published to the Runtime successfully.
Publishing	The workflow is building or publishing.
Pending	The source has been pushed and is waiting for the workflow to trigger.
Failed	The workflow run failed.

Selecting a historical version creates a rollback. When continuous delivery is attached, Studio automatically merges the rollback Pull Request, restoring the target branch to the selected version and triggering the workflow to publish that version; with code sync only, Studio creates a rollback Pull Request for manual merging. Rollback events are also recorded in the version list.

Sync source from the command line

Besides the Studio UI, you can use the veadk github-cicd-pipeline command to push an AgentProject JSON exported by Studio to the target branch, corresponding to the “GitHub code sync” mode:

veadk github-cicd-pipeline \
  --github-url https://github.com/org/repo \
  --github-branch main \
  --github-token "$GITHUB_TOKEN" \
  --project-json ./agent-project.json \
  --region cn-beijing

Option	Required	Default	Description
`--github-url`	Yes	—	GitHub repository URL.
`--github-branch`	No	`main`	Target branch to push the source to.
`--github-token`	Yes	—	GitHub token with contents write permission on the target repository.
`--project-json`	Yes	—	Path to an AgentProject JSON file exported by Studio.
`--region`	No	`cn-beijing`	AgentKit Runtime region.

This command only syncs the source to the target branch; it does not write a GitHub Actions workflow or Secrets and does not publish a Runtime.

Unlike the AgentKit Runtime continuous delivery capability under Automation integrations, this feature is embedded in the custom-creation deployment flow, targets source generated by Studio, and can initialize GitHub delivery while creating a Runtime. Use either as needed.

View integration methods

After selecting a deployed agent in “Manage agents”, the detail page offers an “Integration methods” tab. The tab probes the protocols and endpoints that the current Runtime actually exposes and provides ready-to-use request examples, so you can call the agent from outside Studio without consulting the console.

Integration methods are confirmed at runtime by read-only probes issued when the tab opens; only confirmed protocols and addresses are shown. Protocols the Runtime does not expose appear as unavailable, and Studio never invents unconfirmed endpoints.

Supported protocols

Protocol	Discovery	Call endpoint
API Server	Probes the Runtime `/list-apps` endpoint	`<Runtime public endpoint>/run_sse`
A2A	Reads the Runtime `/.well-known/agent-card.json`	The call address declared in the Agent Card

While probing, Studio shows a loading state. If a probe fails due to network or authentication issues, the tab shows an error with a “Retry” button. When the Runtime does not expose a protocol, that protocol appears as unavailable without affecting the other one.

Authentication and API Key

The tab shows the Runtime’s current authentication type:

Authentication	Description
API Key	The Runtime authenticates with an API Key.
OAuth / JWT	The Runtime authenticates with a custom JWT.
No authentication	The Runtime has no authentication enabled.

When the authentication type is API Key, the tab shows an API Key field. For security, the key is masked as **** by default and is only fetched from the Runtime after you click the reveal button; switching tabs or leaving the agent clears the revealed value. Examples always use placeholders and never embed a real API Key.

A revealed API Key is present in the browser. Only grant Studio access to authorized users, close the reveal view after use, and obtain credentials from a secrets manager or environment variable for programmatic calls rather than copying the plaintext key from Studio.

Request examples

The tab generates a Python request example for each detected protocol, based on the probe results. Endpoints and app names come from the probe; credentials use placeholders. For the API Server protocol, the example uses requests to create a session and call the /run_sse streaming endpoint:

import uuid

import requests

BASE_URL = "<Runtime public endpoint>"
APP_NAME = "<app name>"
USER_ID = "demo-user"
SESSION_ID = str(uuid.uuid4())
API_KEY = "<API_KEY>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

session_response = requests.post(
    f"{BASE_URL}/apps/{APP_NAME}/users/{USER_ID}/sessions/{SESSION_ID}",
    headers=HEADERS,
    json={},
    timeout=30,
)
session_response.raise_for_status()

with requests.post(
    f"{BASE_URL}/run_sse",
    headers=HEADERS,
    json={
        "app_name": APP_NAME,
        "user_id": USER_ID,
        "session_id": SESSION_ID,
        "new_message": {
            "role": "user",
            "parts": [{"text": "Hello, please introduce yourself"}],
        },
        "streaming": True,
    },
    stream=True,
    timeout=120,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

For the A2A protocol, the example calls the agent via the JSON-RPC message/send method:

import uuid

import requests

AGENT_URL = "<A2A call address>"
API_KEY = "<API_KEY>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    AGENT_URL,
    headers=HEADERS,
    json={
        "jsonrpc": "2.0",
        "id": str(uuid.uuid4()),
        "method": "message/send",
        "params": {
            "message": {
                "messageId": str(uuid.uuid4()),
                "role": "user",
                "parts": [{"kind": "text", "text": "Hello, please introduce yourself"}],
            }
        },
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())

The examples illustrate the calling convention only. Actual endpoints, app names, and authentication depend on the probe results; when no authentication is enabled, the Authorization header is not required.

Browse agents

The Agents entry in the sidebar opens the agent directory, where you browse, connect to, and inspect the AgentKit Runtimes under your account. The agent selector in the conversation top bar also provides an entry point into this directory. The directory switches between agent types using the filter at the top, defaulting to General agents:

Type	Description
General agents	Lists the AgentKit Runtimes visible to the current user. Visibility depends on role permissions.
Codex	Opens the Codex temporary session creation entry.
DeepSeek	Opens the DeepSeek workspace session creation entry.
OpenClaw	Not yet available.
Hermes	Not yet available.

The General agents list provides owner, region, and name filters. The owner filter toggles between “All” and “Created by me”: “All” is available only to the admin role; developer and regular users can only view their own Runtimes. The region filter defaults to the Studio’s current region and can be switched to other regions supported by the current cloud provider. The list paginates by the selected region and automatically loads the next page as you scroll to the bottom, showing “All agents loaded” when complete. Use the search box to filter the loaded agents by name. Each agent card shows the Runtime name, description, creator, and creation time. The creation time is displayed as a relative label (e.g., “3 minutes ago”). Click a card to open that Runtime’s detail view; the Connect button on the card makes the Runtime the agent for the current conversation and switches to the conversation page. The connected agent is pinned to the top of the list. When you have creation permission, the first card in the list is a “Create agent” entry. When loading fails, the directory shows an error message with a Reload button; an empty list shows the corresponding empty-state message. Connection failures are diagnosed the same way as when selecting a cloud Runtime.

Each Runtime card in the agent directory automatically checks whether the Runtime supports Studio conversation. While the check is in progress, the card shows a “Checking” status and the Connect button is disabled. After the check completes, Runtimes that support conversation show no additional indicator; Runtimes that do not support conversation show an “Unsupported” label; check errors show a “Check failed” label. When the check fails or the Runtime is unsupported, the card provides a Retry button to re-run the check. Results are cached per Runtime version and automatically re-checked when the version changes.

Select a cloud Runtime

In cloud mode, the agent selector at the top of the chat page lists the AgentKit Runtimes visible to the current user. The visible scope matches the Manage Agents view and is determined by the signed-in account role. Runtimes are paginated by region. Each Runtime exposes two independent actions:

Connect: makes the Runtime the agent for the current conversation and closes the selector after switching.
Info: opens a tabbed preview panel that shows the Runtime’s capabilities without connecting to it or persisting the selection.

The info panel has two tabs:

Agent info: reads live metadata from the Runtime’s deployed Agent Server, including name, model, description, sub-agents, tools, skills, available search sources, and mounted components with their backend types. This information contains only display-oriented summaries and never returns system prompts, credentials, environment-variable values, or arbitrary serialized objects.
Runtime details: shows the Runtime model, description, status, region, resources, version, and environment variables available to Studio.

The Runtime details tab can display runtime environment-variable values. Restrict Studio to authorized users and prefer the platform’s secret-management features.

When connecting to a Runtime, Studio first probes read-only endpoints (agent list, agent info, session list) for readiness: if the Runtime was just deployed and is not yet ready, Studio automatically retries up to 3 times with increasing delays (up to 5 seconds). Private-network Runtimes are not retried. After retries are exhausted or another error occurs, Studio distinguishes the failure cause and shows a corresponding message so you can locate the problem directly:

Access denied: the current account is not allowed to use the Runtime. Refresh the list or sign in again and retry.
Agent Server unreachable: the Runtime’s Agent Server does not expose a connection interface, usually because the Runtime is not ready or its version is incompatible. Confirm the Runtime status and version.
Private Runtime unreachable: the Runtime is deployed inside a VPC without a public address, and the current Studio environment cannot reach that VPC. Use a Studio bound to the same VPC, or switch to a Public or Public + VPC deployment.
Authentication failure: the Runtime service rejected the connection request. Check the Runtime’s authentication configuration.

This lets you decide whether to refresh, sign in again, inspect the Runtime’s readiness, or adjust the network deployment mode without reading logs.

When loading agent info or Runtime details, if the current Runtime does not support the Studio detail interface, the detail panel shows a “Partially unavailable” notice and advises upgrading the Runtime to view the full information. If an error occurs during loading, the detail panel shows a “Detail loading failed” notice with a Retry button to reload the corresponding content.

New-conversation workspace

When starting a new conversation, Studio offers three workspace modes at the top of the conversation page. The mode selector is visible to all signed-in users:

Agent: chat with the selected agent or start a temporary session with a built-in agent.
Skill customization: generate a new skill from a natural-language description or optimize an existing skill. This mode appears only when an administrator has configured a usable Dev Sandbox.
Video creation: generate a video from a text prompt and optional reference assets.

Agent chat and built-in agents

The Agent workspace supports two modes:

Agent chat: starts a normal multi-turn conversation with the selected agent. When the input is empty, starter prompts appear for quick access to common questions.
Built-in agent: uses a platform-provided agent for conversation. You can select Codex or DeepSeek Harness. Codex starts a multi-turn conversation in an independent AgentKit CodeEnv Session with a dedicated editor; DeepSeek Harness opens the DeepSeek Harness workspace in an independent AgentKit CodeEnv Session. Exiting either deletes the cloud Session and does not add it to ordinary session history.

Follow-up messages in an ordinary conversation continue to use the existing message history for that session; only a new session starts with empty context. When a Runtime cannot be connected, Studio distinguishes insufficient permission, an unreachable Agent Server, a private unreachable Runtime, and authentication failure, and displays the corresponding troubleshooting direction. In an agent chat, you can mount built AIO Sandbox or Codex Sandbox runtime environments to the current session via the environment picker at the top of the session. Once mounted, the agent gains the ability to execute shell commands or delegate tasks in the environments. See Session sandbox environments.

When an error occurs during a conversation with the built-in Codex agent — whether the Codex app-server returns an error or the connection is interrupted — Studio displays the complete error detail in the conversation, including the JSON-RPC error code, message, and data, as well as the underlying cause. All error information is credential-redacted before display.

Built-in Codex sessions recover automatically after an idle timeout or transport disconnection. On the next message or request, Studio rebuilds the connection and resumes the current Thread, preserving the existing conversation history, workspace lock state, and context usage — no manual new session is required. Transport recovery does not reset the inactivity timeout; new progress during an active turn resets the recovery allowance, while reconnecting and reading unchanged state do not extend the inactivity deadline. When a Codex turn is interrupted — including interruptions discovered after reconnecting — Studio reports the interrupted status explicitly; it does not publish a new version or wait for the inactivity timeout. Explicit stop requests, inactivity timeouts, task cancellation, and transport failures have distinct reason identifiers; cancellation alone does not imply a user-initiated stop. Recovery is transparent to the user; if recovery fails, the credential-redacted error detail is still shown in the conversation.

In cloud mode, Studio does not auto-select the first available agent. Before starting a new conversation, connect a Runtime from the agent selector at the top of the chat page. Starting a new chat without a selected agent prompts you to choose one first and opens the agent management page.

View Runtime instance logs

In cloud mode, after you connect a Runtime and send a message, the hint bar below the composer shows a “View logs” entry. Clicking it opens the “Instance logs” panel, which streams the live logs of the VeFaaS instance handling the current conversation request, so you can locate runtime errors and unexpected output during a conversation. The entry appears only when a cloud Runtime is connected; it is not shown in local mode or for built-in agent sessions. The panel header shows the following information:

Area	Description
Connection status	Indicates the current log stream state: idle, connecting, live, or retrying. The stream reconnects automatically when interrupted.
Instance ID	The name of the VeFaaS instance handling the current conversation request. Before an instance is captured it shows “waiting for instance”; after you send a message it shows the actual instance.
Console link	Clicking the instance ID opens the cloud console Runtime instance page in a new tab (Volcengine at `console.volcengine.com`, BytePlus at `console.byteplus.com`), filtered to the current instance.
Request ID	When the runtime returns a request identifier, the panel shows it so you can correlate a single request in the cloud console.

The log area renders log lines, auto-refreshes, and keeps only the most recent 1,000 lines. When new logs arrive, the panel auto-scrolls to the bottom to follow the latest output; manual upward scrolling pauses following, and returning to the bottom resumes it. Log lines are colored by level: lines containing ERROR/FATAL/CRITICAL, WARNING, INFO, or DEBUG keywords are marked with the corresponding color so you can distinguish them at a glance.

Studio reads instance logs through a server-side proxy and verifies the logged-in identity’s access to the Runtime before reading. Logs are credential-redacted and length-truncated on the server before being sent to the browser, and runtime credentials are never exposed to the browser. Reading instance logs uses the Volcengine or BytePlus credentials configured for Studio.

Before you send a message, or before an instance has been captured from the runtime response, the panel shows “instance not yet captured” and suggests sending a message first. Studio locates the instance from the identifier returned in the runtime response; when no direct instance identifier is available, it matches the instance that contains the session among the current Runtime’s instances using the session identifier.

Instance logs may contain application output printed by the runtime. Make sure Studio is only exposed to authorized users, and avoid printing sensitive information to logs.

Local configuration

Before using built-in agents locally, prepare one AgentKit CodeEnv Tool in the Ready state and configure its ID:

export SANDBOX_CHAT_CODEX="your-chat-code-env-tool-id"

veadk studio --agents-dir ./agents --open

Environment variable	Default	Description
`SANDBOX_CHAT_CODEX`	—	AgentKit CodeEnv Tool ID for built-in agents; required when using this mode locally.
`AGENTKIT_SANDBOX_REGION`	`cn-beijing`	Preferred region for creating Sessions and looking up Tools for built-in agents; supports `cn-beijing` and `cn-shanghai`.

When creating a Session or looking up the Tool for built-in agents, Studio first tries the region set by AGENTKIT_SANDBOX_REGION; in Volcengine mode, when it is not set it falls back to the REGION environment variable and then the default cn-beijing. If that region reports the resource as not found, it automatically falls back to the other supported region (Beijing ↔ Shanghai) and continues. Other errors do not trigger fallback. When deployed to VeFaaS, this region matches --region.

Codex and DeepSeek Harness share the same AgentKit CodeEnv Tool (SANDBOX_CHAT_CODEX); no separate Tool is needed for DeepSeek Harness. Sessions for the two built-in agent types are distinguished by an agent-kind identifier and do not interfere with each other.

Codex session controls

After selecting the Codex agent, conversations use a dedicated Codex session composer. The composer exposes permissions and workspace entries on the left of the input, terminal, browser, and file-upload entries in the Add menu, and supports slash commands, model switching, and Skill invocation. These controls apply only to the current Sandbox Session and do not modify the deployed agent.

Slash commands

Typing / in the input opens a slash-command menu that can be filtered by name or keyword. Selecting a command fills the input; press Enter to submit it to the current Codex Session for execution.

Command	Description
`/model [model]`	Show or switch the model for the current conversation. Without an argument, lists available models to choose from.
`/models`	Lists the models currently available.
`/skill`	Browse and invoke a Skill available in the current workspace.
`/skills`	Browse and invoke Skills available in the current workspace.
`/new`	Starts a new conversation.
`/resume [thread]`	Opens the conversation history list, or resumes a specified thread.
`/fork`	Forks a new conversation from the current context.
`/compact`	Compresses the current conversation context.
`/archive`	Archives the current conversation and starts a new one.
`/status`	Shows the current connection, thread, model, and token status.
`/clear`	Clears the current view and starts a new conversation.
`/help`	Shows the supported slash commands.

Models and Skills

Typing /model triggers the model list; choose one or type a model ID directly to switch the model used by the current conversation. Typing $ browses Skills available in the current workspace; selecting one inserts it as a chip in the input and it is submitted with the message. When the input is empty, pressing Backspace removes the last selected Skill.

Workspace

The workspace button on the left of the input selects the directory where the current Codex Thread runs commands and modifies files. In the dialog you can enter an absolute path directly or browse the directory tree. Once a conversation starts, the workspace is locked; start a new Sandbox Session to choose again.

When an administrator enables the STUDIO_EXPOSE_SANDBOX_ENDPOINT environment variable (any value other than 0/false), the Codex session editor shows a “Copy Sandbox Endpoint” button next to the composer that copies the current Sandbox public endpoint to the clipboard. The button is hidden when the variable is not enabled. It is configured via an environment variable for both local and deployed Studio, and is disabled by default.

Permissions

The permissions button on the left of the input opens the Codex Permissions dialog. Settings are saved to the current Sandbox Session and synced to all Threads within it.

Setting	Options	Description
Sandbox mode	Read-only / Workspace write / Full access	Controls the file-system isolation scope. Full access disables file-system and network isolation and forces network access on.
Approval policy	Untrusted commands only / On request / Never	Determines when Codex pauses to request human confirmation for commands or file modifications.
Approval reviewer	By me / Auto review	Whether approval requests are handled by you in Studio or by the Codex automatic review process.
Network access	On / Off	Controls external network access in Workspace write and Read-only modes. Forced on for Full access and cannot be turned off.

Full access disables file-system and network isolation. Use it only for trusted tasks that require full host permissions.

Action approvals

When the approval policy requires human confirmation and Codex requests a command execution or file modification, Studio opens an approval dialog showing the pending command, file changes, and execution directory. You can Decline, Allow once, or Allow for this session. The decision is recorded as an activity entry in the conversation.

Terminal and browser

From the Add menu, choose Enter terminal or View browser to open an interactive terminal or browser view attached to the current AgentKit Session. A loading state is shown while connecting, and you can retry on failure. The same menu also lets you upload images, documents or PDFs, and videos to the current conversation; uploaded images display a preview inline and open in a shared photo viewer when clicked.

Status and history

/status shows the current Thread, workspace, model, run state, total tokens, and context window as an activity record. After each assistant reply, the token usage for that turn is displayed. Typing /resume opens the Resume Codex conversation dialog to select and restore a recently updated Thread.

The “Created by” field in the sandbox session list shows the signed-in user’s display name (OAuth email or local username), making it easier to distinguish session ownership in multi-user deployments. When no display name is available, the internal user identifier is used instead. When a display name’s UTF-8 encoding exceeds the session metadata byte limit, Studio truncates it at a character boundary and appends an ellipsis so that session creation is not affected.

When a built-in agent’s session ends, its latest saved record appears in the agent list with a “sleeping” status, sharing the same “Ready” label and styling as live sessions and marked “Never expires”. Opening a sleeping agent wakes it on demand: Studio first restores the saved session and then opens the normal entry point; a wait indicator is shown during the wake and you can retry on failure. Wake requests for the same agent are serialized within a single service instance, and retries check for an existing live session and reuse it directly — this is not a distributed lock. Users can list, wake, and delete their own sleeping records; administrators can additionally manage legacy records that lack owner metadata; records of a different agent kind are filtered out when a Tool is shared. Deleting a sleeping agent requires confirmation and removes only the selected saved record; if older records exist for that logical agent, the next latest one may appear after refresh. Records that failed to resume remain available for deletion but cannot be opened. This capability requires the corresponding sandbox snapshot Tool to be configured. The UI always uses agent terminology and does not expose the underlying control-plane resource types.

Skill customization

The Skill customization workspace provides a quick entry point for generating and optimizing skills from the new-conversation page, reusing the Skill Center’s Dev Sandbox skill generation. This mode is available only to developer and admin roles, and appears in the workspace selector only when an administrator has configured a usable Dev Sandbox and its model credentials; when not configured, the mode is hidden rather than exposing an action that must fail.

Skill generation

Describe the target skill in natural language in the input box, for example “generate a skill that analyzes CSV files and outputs summary statistics”. After submitting, Studio navigates to the Skill Center Dev Sandbox skill generation workspace and pre-fills the description as the initial intent.

Skill optimization

Switch to “Optimize”, select the skill space and skill to optimize from AgentKit SkillSpace, then describe the optimization goal in the input box, for example “improve compatibility with Chinese column names”. After submitting, Studio navigates to the Skill Center workspace to optimize the selected skill and optionally overwrite-publish it to the original skill space.

Skill customization shares the same generation and optimization flow, Dev Sandbox session management, candidate comparison, and publishing flow as the Skill Center. The workspace acts only as a quick entry point. Browsing AgentKit SkillSpace is performed by the Studio server using its own configured Volcengine credentials; the browser never sees credentials.

Video creation

The Video creation workspace generates videos from text prompts and optional reference assets, suitable for content creation, asset preview, and similar scenarios. This mode is available to all signed-in users. Uploading reference assets requires an administrator-configured persistent storage; when not configured, reference asset upload is disabled, but text-to-video remains available.

How to use

Select the “Video creation” workspace on the new-conversation page.
Choose a video task mode and, as needed, upload reference assets and set the aspect ratio, resolution, and duration.
Enter a video description in the input box. After submitting, Studio first enhances the prompt, then creates a video generation task.
Track progress in the video task dialog: during generation it shows whether the task is queued or the model is generating, along with the elapsed time. You can close the dialog while a task is generating and it continues running in the background without affecting the result; when generation completes, preview and download the resulting video.

Video task modes

Mode	Description	Reference assets
Auto	Automatically determines which of the following modes to use based on the prompt and uploaded assets.	Per selected mode
Text to video	Generates a video from a text prompt only, without reference assets.	None
Reference to video	Generates a new video from a reference image or reference video.	Reference image or reference video
Video editing	Edits an existing video according to the prompt.	Video to edit
Video extension	Appends new content at the end of an existing video.	Base video
First/last frame	Generates a video from a first frame and an optional last frame image.	First frame image (required), last frame image (optional)

Generation parameters

Parameter	Options	Default	Description
Aspect ratio	`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`	`16:9`	Width-to-height ratio of the generated video.
Resolution	`480p`, `720p`	`720p`	Clarity of the generated video.
Duration	4–30 seconds	8 seconds	Length of the generated video. Video editing uses the original video length.

Generation flow

Video generation has two stages, both performed on the Studio server:

Prompt enhancement: the enhancer model expands and normalizes the input prompt and resolves the final task mode.
Video generation: the generation model creates a video task using the enhanced prompt and parameters. When the task completes, a preview URL and download link are returned.

The models used differ by cloud provider:

Cloud provider	Generation model	Enhancer model
Volcengine	`doubao-seedance-2-5-260628`	`doubao-seed-2-1-pro-260628`
BytePlus	`dreamina-seedance-2-5-260628`	`dola-seed-2-1-turbo-260628`

Video generation runs asynchronously. The dialog shows the real-time status of both the enhancement and generation stages: during generation it distinguishes whether the task is queued or the model is generating and shows the elapsed time. You can close the dialog while a task is generating and it continues running in the background without affecting the result. When a stage fails, the dialog displays the error details returned by the server (with keys and signatures automatically redacted); you can retry from the failed stage without re-entering the prompt.

Reference assets and persistent storage

Reference asset upload and result storage depend on Studio persistent storage. When persistent storage is not configured, the reference asset upload controls are disabled and the corresponding UI shows “管理员未配置持久化存储”; text-only features such as text-to-video remain available. For storage configuration, see Studio persistent storage.

Reference assets and generated results are stored in the TOS bucket configured for Studio, isolated by signed-in user. Do not upload assets that contain sensitive information.

Manage session capabilities

Starting with VeADK 1.0.9, Studio can manage tools and skills for the current session when the connected Runtime exposes the session-scoped capability-overlay endpoints. When the connected Runtime exposes the session-scoped capability-overlay endpoints, the agent info panel on the conversation page shows “Add a tool to this conversation” and “Add a skill to this conversation” entries in the tool and skill lists. Added capabilities apply only to the current session: they do not modify the deployed root agent and are not written to other sessions.

Built-in tools: chosen from the VeADK built-in tool catalog; searchable by Chinese name or tool identifier.
Remote skills: searched from the public Skill Hub, or browsed from AgentKit Skill Spaces by region and project.

Mounted session capabilities can be removed from the same panel; once removed, the capability is no longer available in the current session. Conversations in the session run through a session-aware runner so that the overlaid tools and skills actually participate in calls. Listing and mounting remote skills requires Volcengine credentials; provide them locally with VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY, and on VeFaaS use the bound IAM Role. For the complete overlay endpoints and parameters, see Deploy to AgentKit.

Automatic evaluation and optimization feedback

Agents deployed to AgentKit support automatic evaluation and optimization feedback in the workspace. When “Auto-create evaluation sets” is enabled during deployment, Studio creates Good Case and Bad Case evaluation sets for the agent. After a conversation session ends, Studio automatically evaluates each turn and saves the result to the corresponding evaluation set, then generates optimization suggestions based on the accumulated cases.

Evaluation set creation

The deployment configuration area provides an “Auto-create evaluation sets” toggle, disabled by default. After deployment succeeds, Studio idempotently creates Good Case and Bad Case default evaluation sets in persistent storage for the Runtime. Creation runs in the “Create evaluation sets” stage, after which the deployment flow enters its final stage.

Evaluation-set creation failures do not affect the deployed Runtime. On failure, a warning is shown in the deployment result; the successfully deployed agent remains usable.

Automatic evaluation

When a user converses with a deployed agent in Studio, each completed turn is automatically evaluated after a quiet period (300 seconds by default). The evaluation proceeds as follows:

Studio reads the latest assistant reply for that turn from the Runtime.
The doubao-seed-2-0-lite-260428 model scores the reply on task completion, factual and logical reliability, tool-use soundness, clarity, and safety.
Scores range from 0 to 1; scores of 0.6 or above are saved to the Good Case evaluation set, and scores below 0.6 are saved to the Bad Case evaluation set.
Auto-evaluated cases are written to the corresponding TOS evaluation set, marked as “auto” source in the case list, and display their score and evaluation reason.

If the user sends a new message in the same session, the quiet timer is reset so that evaluation only runs after the conversation pauses.

Optimization suggestions

Once enough cases have been accumulated through automatic evaluation, Studio generates optimization suggestions based on the agent’s existing evaluation cases. Suggestions are grouped by priority and module and displayed in the workspace’s “Optimization” tab:

Field	Description
Fix priority	Labels each group as high, medium, or low priority.
Suggested module	Identifies the module to improve, such as agent structure, prompt, tool, knowledge base, memory, or workflow.
Suggestion and reason	Each suggestion includes a specific improvement description and the corresponding evaluation basis.

Optimization suggestions are generated by the doubao-seed-2-0-lite-260428 model based on accumulated evaluation cases and the agent configuration, and are for reference only. The evaluation model can be overridden with the VEADK_STUDIO_EVALUATION_MODEL environment variable.

When Studio persistent storage is configured, optimization snapshots are stored in TOS, survive process restarts, and are shared across instances. When persistent storage is not configured, snapshots are kept in process memory only and are lost on restart. For storage configuration, see Studio persistent storage.

Annotate a reply as a Bad Case

When conversing with a deployed agent, you can select a text fragment directly within an assistant reply and add an inline annotation to save that turn as a Bad Case evaluation sample in the corresponding Bad Case evaluation set. The annotation preserves the selected fragment and your note, making it easier to trace the issue back to a specific passage. This capability is available only when all of the following conditions are met:

Connected to a deployed Runtime with Studio persistent storage configured (local debug sessions are not supported);
The reply has finished generating (not available while streaming is in progress or while authorization is pending).

Usage:

Select a text fragment inside the assistant reply bubble. After releasing the mouse, an annotation popover appears near the selection and shows the selected excerpt.
In the “Note” field, describe the problem or the expected correction.
Click “Add to Bad Case”. Studio combines the selected fragment and the note into the evaluation case’s comment and writes the turn to the Bad Case evaluation set. On success the popover shows a confirmation message.

The selected text is capped at 700 characters, the note at 1,200 characters, and the combined comment at 2,000 characters; excess content is truncated. If the save fails, the annotation popover stays open with an error message so you can retry after correcting the issue.

Bad Case samples saved through annotation are marked as “manual” source in the case list, with a score of 0 and the annotation as the evaluation reason. Manual cases created through thumbs-up/thumbs-down without an annotation still show ”—” as the score.

View evaluation cases

The workspace’s “Evaluation sets” tab shows all evaluation cases for the Runtime, filterable by Good Case / Bad Case and auto / manual source. Auto-evaluated cases display a score (on a 0–100 scale) and an evaluation reason; manual cases created through thumbs-up/thumbs-down without an annotation show ”—” in the score column, while manual cases created through annotation display a score and the annotation reason. Cases from both sources can be deleted.

Automation integrations

The “Automation” page in the Studio sidebar provides automation integrations for development tools and message channels. Automations are organized into “Development” and “Channels” categories. The Coding Agents integration detects and configures locally installed coding-agent clients; GitHub automations create branches, files, and Pull Requests directly through the browser using the GitHub API; the Feishu automation generates a basic agent and deploys it directly to an AgentKit Runtime from Studio; the website integration embeds a deployed Runtime as a floating chat window on external websites.

Configure Coding Agents

Globally installs the bundled VeADK and AgentKit Skills to locally installed coding-agent clients so they can build, debug, deploy, and operate the platform while developing VeADK applications. This integration is badged “Local”: detection and installation run only on the machine hosting Studio and do not access cloud resources.

The “Configure Coding Agents” card is enabled only when Studio is accessed at http://127.0.0.1. When accessed through any other hostname (including localhost or a deployed VeFaaS public URL), the card appears disabled with a “仅本地部署可用” tooltip.

Open the “Configure Coding Agents” card on the Automation page to detect installed coding-agent clients on the current operating system (macOS, Linux, Windows) and list the bundled Skills available for global installation. Supported coding-agent clients:

Client	Detection	Global skills path
Trae	`trae` or `trae-cn` on the PATH, a `.trae` or `.trae-cn` marker in the home directory, or an installed Trae app (macOS `/Applications` or the Windows program directory)	`~/.trae/skills`
Claude Code	`claude` on the PATH or a `.claude` marker in the home directory	`~/.claude/skills`
Codex	`codex` on the PATH, a `.codex` or `.agents` marker in the home directory, or an installed ChatGPT/Codex app	`~/.agents/skills`

When a CLI executable is found, Studio also reports its version; clients that are not detected are marked unavailable. The bundled Skills are a fixed set and cannot be customized:

Skill	Description
`veadk-agent-development`	VeADK development skill for building, debugging, and delivering VeADK-based agent applications.
`agentkit-cli`	AgentKit platform-operation skill for managing deployments, runtimes, and platform resources with the AgentKit CLI.

After selecting one or more detected clients and one or more bundled Skills, Studio writes the selected Skills to each client’s global skills directory (for example ~/.claude/skills/<skill_id>). Each Skill is written to its own subdirectory containing SKILL.md and any bundled scripts, references, and assets.

The browser can only choose from fixed client and Skill identifiers; arbitrary shell commands, filesystem paths, and Skill content are never accepted. Skills come from Studio’s bundled resources, not from browser uploads. You can preview the files in each Skill before installing.

Installation is atomic: Studio stages the Skill files in a temporary directory, validates them, and then swaps them into the target directory. When a Skill with the same name already exists, it is backed up before replacement; a failed install rolls back to the original content automatically.

Installation writes to the global skills path under the home directory of the user that runs Studio. Make sure the user running Studio is the same user that owns the coding-agent client, so Skills are installed in the correct user directory.

When role-based access control is enabled, configuring Coding Agents requires the developer or admin role. Template project import and AgentKit Runtime continuous delivery adapt their region options, default region, default model API URL, and required GitHub Secret names to Studio’s current cloud provider. In Volcengine mode the region options are cn-beijing and cn-shanghai (default cn-beijing) and the Secrets are VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, and the optional VOLCENGINE_SESSION_TOKEN; in BytePlus mode the region is ap-southeast-1 and the Secrets are BYTEPLUS_ACCESS_KEY, BYTEPLUS_SECRET_KEY, and the optional BYTEPLUS_SESSION_TOKEN. The cloud provider is determined by --provider or the AGENTKIT_CLOUD_PROVIDER/CLOUD_PROVIDER environment variables, falling back to Volcengine when unset. PR automated review is triggered through a GitHub App and does not rely on GitHub Actions workflows or GitHub Secrets; see Pull Request automated review.

Template project import

Creates a minimal VeADK agent project with a full Studio App Server in the target repository, along with a continuous delivery workflow. After submission, Studio creates a release branch in the target repository and opens a PR containing the template files and a GitHub Actions workflow. The template project includes an app.py service entry point, an agent with an example tool, requirements.txt, Dockerfile, .env.example, .gitignore, .dockerignore, and a continuous delivery workflow file. After merging the PR, pushing to the target branch triggers an AgentKit Runtime release.

Parameter	Required	Default	Description
GitHub Repo	Yes	—	Supports `owner/repository` or a full GitHub URL.
Target branch	No	`main`	The base branch for the PR.
Agent project directory	Yes	`agentkit-basic-agent`	The directory where template files are created.
Runtime name	Yes	—	The Runtime name used in the release configuration; must start with a letter and contain only letters, digits, underscores, and hyphens.
Runtime ID	Yes	—	The target AgentKit Runtime ID to continuously update.
Region	Yes	`cn-beijing` (Volcengine) / `ap-southeast-1` (BytePlus)	Must match the region of the target Runtime; the available options follow the current cloud provider.
GitHub Token	Yes	—	Requires write access to the target repository; used only for the current request and never persisted.

AgentKit Runtime continuous delivery

Adds a GitHub Actions workflow to an existing repository for continuous publishing to an AgentKit Runtime. Pushing code to the target branch automatically builds and releases a new Runtime version.

Parameter	Required	Default	Description
GitHub Repo	Yes	—	Supports `owner/repository` or a full GitHub URL.
Target branch	No	`main`	The branch the workflow listens on and the base branch for the PR.
Agent project directory	No	`.`	The project directory containing `app.py`; uses the repository root when left blank.
Runtime name	Yes	—	The Runtime name used in the release configuration.
Runtime ID	Yes	—	The target AgentKit Runtime ID to continuously update.
Region	Yes	`cn-beijing` (Volcengine) / `ap-southeast-1` (BytePlus)	Must match the region of the target Runtime; the available options follow the current cloud provider.
GitHub Token	Yes	—	Requires write access to the target repository; used only for the current request and never persisted.

The continuous delivery and template import workflows require the GitHub Secrets that match the current cloud provider to be configured in the repository: VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, and the optional VOLCENGINE_SESSION_TOKEN in Volcengine mode; BYTEPLUS_ACCESS_KEY, BYTEPLUS_SECRET_KEY, and the optional BYTEPLUS_SESSION_TOKEN in BytePlus mode. These Secrets are managed in GitHub and do not pass through Studio.

GitHub Pull Request automated review

Uses a GitHub App to automatically review pull requests in an isolated Sandbox and publishes the results as GitHub Reviews. After an administrator configures the GitHub App, users install the App to their repositories and enable review per repository in Studio. GitHub sends Pull Request webhooks to Studio, which creates Sandbox review tasks and publishes the results to the corresponding PR.

Automated PR review only reviews non-draft PRs from the same repository (opened, synchronize, reopened, ready_for_review events), not fork PRs.

Administrator configuration

Create a GitHub App in GitHub and record the App ID, App slug, private key, and webhook secret. In the GitHub App settings, set the webhook URL to the Studio path /web/github/app/webhook (for example https://<Studio address>/web/github/app/webhook) and set the webhook secret to match the environment variable below. Then configure Studio with the following environment variables:

Environment variable	Default	Description
`VEADK_GITHUB_APP_ID`	—	The GitHub App ID.
`VEADK_GITHUB_APP_SLUG`	—	The GitHub App slug, used to generate the install URL.
`VEADK_GITHUB_APP_WEBHOOK_SECRET`	—	The GitHub App webhook secret; must match the value in the GitHub App settings.
`VEADK_GITHUB_APP_PRIVATE_KEY`	—	The GitHub App private key content, with newlines represented as `\n`.
`VEADK_GITHUB_APP_PRIVATE_KEY_B64`	—	Base64-encoded GitHub App private key. Mutually exclusive with `VEADK_GITHUB_APP_PRIVATE_KEY` and `VEADK_GITHUB_APP_PRIVATE_KEY_PATH`; Base64 encoding takes priority.
`VEADK_GITHUB_APP_PRIVATE_KEY_PATH`	—	Path to the GitHub App private key file. Used when neither of the above is set.
`VEADK_GITHUB_APP_REVIEW_OWNER_ID`	`github-app`	The owner identifier for review tasks.
`VEADK_GITHUB_APP_REVIEW_CREATOR`	`GitHub App`	The display name for review tasks.

For local startup, provide the above configuration through environment variables. When deploying to VeFaaS, veadk studio deploy and veadk studio update forward the GitHub App configuration environment variables to the function environment; the private key is preferentially passed as Base64-encoded data.

Automated PR review requires Studio persistent storage to be configured (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION) to persist per-repository review toggles and review records. Without persistent storage, users cannot enable review or view records in Studio.

Usage flow

After the administrator completes the configuration, the “Pull Request automated review” page displays an install link for the GitHub App.
Click “Install GitHub App” to install the App to the target GitHub repositories. After installation, Studio automatically loads the list of installed repositories.
Toggle review on for each repository that should receive automated reviews. Only repositories with review enabled will respond to GitHub webhooks.
Subsequent non-draft PRs in the target repository automatically trigger Sandbox review tasks; review results are published as GitHub Reviews on the corresponding PR.
You can also enter a PR URL from an enabled repository in the “Review now” section to manually start a review.

The repository list supports search by owner or repository name and paginated loading. Manual review requires the PR URL’s repository to have the GitHub App installed and review enabled.

Review records

Studio records recent automatically triggered and manually started review tasks and displays them in the “Review records” section. Each record includes the PR link, status (started, completed, ignored, failed), trigger type (webhook or manual), event type, and time. Records with an in-progress review offer an “Open Session” button to jump to the corresponding Sandbox session.

Merge Request automated review

Uses GitLab OAuth to automatically review merge requests in an isolated Sandbox and publishes the results as GitLab Discussions and comments. After an administrator configures a GitLab OAuth application, users connect their own GitLab account in Studio, select target projects, and enable review. GitLab sends Merge Request webhooks to Studio, which creates Sandbox review tasks and publishes the results to the corresponding MR.

Automated MR review only reviews non-draft MRs from the same project (open, reopen, update events), not fork MRs. Draft MRs (marked as Work in Progress or with titles starting with Draft: or WIP:) are not reviewed.

Administrator configuration

Create an OAuth application in your GitLab instance, record the Client ID and Client Secret, and set the redirect URI to the Studio path /web/gitlab/oauth/callback (for example https://<Studio address>/web/gitlab/oauth/callback). The OAuth application scope must include api. Then configure Studio with the following environment variables:

Environment variable	Default	Description
`VEADK_GITLAB_BASE_URL`	`https://gitlab.com`	GitLab instance URL; must be an HTTPS URL without path parameters. Specify the actual URL for self-hosted GitLab instances.
`VEADK_GITLAB_WEBHOOK_SECRET`	—	GitLab webhook verification token; must match the value configured in the project webhook.
`VEADK_GITLAB_OAUTH_CLIENT_ID`	—	GitLab OAuth application Client ID.
`VEADK_GITLAB_OAUTH_CLIENT_SECRET`	—	GitLab OAuth application Client Secret.
`VEADK_GITLAB_OAUTH_REDIRECT_URI`	—	OAuth redirect URI, pointing to the Studio `/web/gitlab/oauth/callback` path.
`VEADK_GITLAB_GROUP_ID_OR_PATH`	—	GitLab Group ID or path to restrict the project list scope. When unset, all projects where the current user is a member are listed; when set, only projects within that group (including subgroups) are listed.
`VEADK_STUDIO_PUBLIC_BASE_URL`	—	Public base URL of Studio, used to generate the GitLab webhook callback URL. When unset, project webhooks cannot be created automatically.

For local startup, provide the above configuration through environment variables. When deploying to VeFaaS, veadk studio deploy and veadk studio update forward the GitLab configuration environment variables to the function environment.

Automated MR review requires Studio persistent storage to be configured (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION) to persist per-user GitLab OAuth credentials, per-project review toggles, and review records. Without persistent storage, users cannot connect GitLab, enable review, or view records.

Usage flow

After the administrator completes the configuration, the “Merge Request automated review” page displays a “Connect GitLab” button.
Click “Connect GitLab” to redirect to the GitLab authorization page. After authorization, Studio redirects back automatically. Studio saves the GitLab OAuth credential under the current signed-in user’s identity; each user maintains their own authorization independently.
After authorization, Studio loads the list of GitLab projects accessible to the current user. Toggle review on for each project that should receive automated reviews. When review is enabled, Studio automatically creates a webhook in the target project pointing to Studio (path /web/gitlab/app/webhook) and uses the Webhook Secret to verify requests.
Subsequent non-draft MRs in the target project automatically trigger Sandbox review tasks; review results are published as GitLab Discussions (supporting line-level positioning) and comments on the corresponding MR.
You can also enter an MR URL from an enabled project in the “Review now” section to manually start a review.

The project list supports search by project path or name and paginated loading. Enabling review requires the current user to have Maintainer or higher permissions (access level ≥ 40) in the target project, so that Studio can automatically create and manage the project webhook. Manual review requires the MR URL’s project to have GitLab connected and review enabled.

When the GitLab OAuth access token expires, Studio automatically refreshes it using the refresh token. If refresh fails, Studio marks the project as authorization invalid and the user must reconnect GitLab.

Review records

Studio records recent automatically triggered and manually started review tasks and displays them in the “Review records” section. Each record includes the MR link, status (started, completed, ignored, failed), trigger type (webhook or manual), event type, and time. Records with an in-progress review offer an “Open Session” button to jump to the corresponding Sandbox session.

Feishu bot

The Feishu bot automation is currently marked as Beta.

Creates a Feishu agent powered by an AgentKit Runtime directly from Studio. After providing credentials for a published Feishu app, Studio generates a basic agent, creates an independent Runtime, and enables the Feishu message long-connection. Deployment progress is shown across four stages: generating agent, building image, creating Runtime, and publishing service. After deployment succeeds, the Runtime console can be opened from the page.

Parameter	Required	Default	Description
Agent name	Yes	`feishu_assistant`	Used as the root agent name in the new Runtime.
Deployment region	Yes	`cn-beijing`	The region where the Runtime and build artifacts are created. Supports `cn-beijing` or `cn-shanghai`.
Feishu App ID	Yes	—	Application credentials from the Feishu open platform.
Feishu App Secret	Yes	—	Used only for the current deployment and never written to generated source or browser storage.

The Feishu bot’s App Secret is used only for the current deployment and is not written to generated source, workflows, or logs. Deployment can be cancelled during the process; cancellation stops the task and cleans up the created Runtime.

Website integration

Embeds a deployed AgentKit Runtime as a floating chat window on external websites, allowing visitors to chat with an agent without logging in. Open the “Website integration” card on the Automation page, select a target Runtime, and enter the website domain. Studio generates a dedicated Token and an embed snippet.

The website integration is currently marked as Beta.

Prerequisites

At least one AgentKit Runtime is deployed and has a conversational agent.
The target Runtime uses API Key authentication. Runtimes using custom JWT authentication are not supported.
When Studio persistent storage is configured (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION), website integration records are persisted in TOS. Without persistent storage, in-memory storage is used and integration records are lost when Studio restarts.

Creating a website integration

In the “Add website” area, select the target AgentKit Runtime and enter the domain of the website where the chat window will be embedded.
Click “Generate Token”. Studio validates the conversational agents on the selected Runtime and creates an integration record with a domain-bound Token.
Review the created integration in the “Added websites” list. Each record shows the domain, Runtime name, agent name, and creation time.

The domain must be a valid http or https address. It can include a port (for example, localhost:5173 or example.com:8080) but must not contain a path, query parameters, or credentials.

Parameter	Description
AgentKit Runtime	Select the target Runtime from the list of runtimes visible to the current account.
Website domain	The domain of the website where the chat window will be embedded, such as `example.com` or `localhost:5173`.

Embedding the chat window

Copy the generated <script> tag from the “Embed method” area and paste it before the </body> tag on the target page. The script loads the chat component from the Studio server and renders an expandable floating chat window in the bottom-right corner of the page.

<script async src="https://your-studio-url/website-integration.js" data-token="wsi_xxx"></script>

The src URL in the embed snippet must point to a publicly accessible Studio service address. The Studio service must allow cross-origin requests from the target website. The integration domain is bound to the Token, and Studio validates the browser request Origin against the configured domain at runtime; requests with a mismatched Origin are rejected.

How it works

When a visitor opens a page with the embedded chat window, the chat component sends a session-creation request to the Studio embed endpoint and obtains a session token valid for one hour. Subsequent messages are forwarded through Studio to the bound Runtime using the session token, and replies are streamed back. A new session must be created after the session token expires. Studio accesses the Runtime using the configured Volcengine or BytePlus credentials. Website visitors never receive any credentials or direct Runtime addresses.

Deleting a website integration

Click the “Delete” button on the corresponding record in the “Added websites” list and confirm to remove the integration. After deletion, embed code using that Token can no longer create new sessions. Existing sessions expire when their session token expires.

Resource library

The “Resource library” page in the sidebar consolidates skill, knowledge base, and artifact management into three tabs:

Tab	Description
Skills	Manage skill spaces and skills, including upload, browse, Dev Sandbox generation, and optimization.
Knowledge	Create and manage user-owned AgentKit knowledge bases, upload files or import web pages as knowledge data.
Artifacts	Browse and manage documents, images, and videos generated in conversations; images and videos can be persisted, edited, and deleted.

Skills

The Skills tab provides skill space management and Dev Sandbox skill generation. Here you can create and manage skill spaces, upload and browse skills, and generate new skills or optimize existing ones from natural-language descriptions using the Dev Sandbox. Skill generation uses a dedicated AgentKit DevEnv Tool and is independent of the CodeEnv-based built-in agent mode.

Prerequisites

Skill space management and generation operations are performed by the Studio server using its own Volcengine credentials; the browser never touches them. For local startup, provide access through VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY; for VeFaaS deployments, use the IAM Role bound to the function. Dev Sandbox skill generation requires an administrator to configure an AgentKit DevEnv Tool in the Ready state. For local startup, specify the Tool ID via the SANDBOX_DEV environment variable; for VeFaaS deployments, it is auto-created or reused via --sandbox-dev-tool-id. When not configured, skill space management and upload remain available, but the “Create skill” and “Optimize” actions show “Dev Sandbox not configured” and are disabled.

Dev Sandbox skill generation is available only to developer and admin roles. Skill space browsing is available to all signed-in users, but non-admins can only see skill spaces they created.

Skill publish storage

When publishing a skill to a skill space, Studio uploads the skill package to a TOS bucket. The bucket is selected by the following priority:

Priority	Source	Description
1	`VEADK_SKILL_CREATOR_TOS_BUCKET`	A TOS bucket explicitly designated for skill publishing.
2	Studio persistent storage bucket	Configured via `VEADK_STUDIO_TOS_BUCKET` and `VEADK_STUDIO_TOS_REGION`. When used, the bucket region is validated against the skill publish region; publishing fails if they do not match.
3	Bucket from the AgentKit global configuration	The bucket set through the AgentKit CLI global configuration.
4	Auto-generated	The system generates a bucket name and creates it automatically.

The object prefix within the bucket is specified by the VEADK_SKILL_CREATOR_TOS_PREFIX environment variable, defaulting to agentkit/skills.

When Studio persistent storage is configured, skill publishing automatically reuses that bucket with no additional configuration. To use a separate bucket for skill publishing, set the VEADK_SKILL_CREATOR_TOS_BUCKET environment variable.

Manage skill spaces

Skill spaces are loaded by region and support filtering by name. Administrators can see all skill spaces visible to the current account across all regions; non-admins see only spaces they created.

Action	Description
Create space	Provide a name (up to 128 characters) and an optional description (up to 1024 characters), select a region, and create. The creator is recorded in the space’s tags.
Edit space	Modify the space name and description.
Delete space	All skills in the space must be deleted before the space can be deleted; if skills remain, a prompt appears asking to remove them first.

When creating a skill space you must select a region: for Volcengine the options are cn-beijing and cn-shanghai, defaulting to cn-beijing; for BytePlus the option is ap-southeast-1. Skill space cards display their region; spaces without an explicit region show the current cloud provider’s default region.

Studio maintains two system skill spaces: studio_share_space is the enterprise shared skill space, always shown first in the Skills library, where administrators can maintain shared skills; studio_review_space stores submitted skill versions for review and is excluded from the Skills library and skill selectors. Each space is created once per cloud provider region and VEADK_STUDIO_PROJECT (or default). System spaces cannot be renamed or deleted; content in the review space can only be modified through the skill review workflow. When creating or renaming a skill space, user-entered names that conflict with reserved system space names are rejected.

When creating a personal skill space, Studio generates a unique cloud name containing only lowercase letters, numbers, and underscores, and stores the user-entered name in the skill space’s display_name tag. The Skills library cards, details, and selectors prefer the display name and fall back to the cloud name when the tag is missing or blank. Skill lookups and exports continue to use the original cloud name.

Manage skills

After entering a skill space, you can browse all skills within it and filter by name. Each skill supports the following actions:

Action	Description
View files	Displays the complete file list as a file tree; `SKILL.md` content is previewed directly in the page.
Download ZIP	Downloads the skill’s complete file package as a ZIP archive.
Optimize	Uses the Dev Sandbox to optimize an existing skill, producing an improved version that can overwrite the original. Requires the Dev Sandbox to be configured.
Delete	Requires confirmation before deletion. Deleting a skill affects all spaces that reference it.
Local upload	Upload a ZIP file to the current skill space. The ZIP file must not exceed 20 MiB; file format, count, and path safety are validated before upload.
Submit for review	Submit a selected version of a personal skill for review. Studio copies the version snapshot into an independent skill in the review space, preserving the original name and recording the submitter. Duplicate submissions of the same source version are rejected while pending or approved.

When uploading a ZIP, Studio checks that the archive contains SKILL.md and validates file count and path safety, automatically ignoring macOS metadata files inside __MACOSX directories. Full frontmatter and skill format validation is performed by ADK at load time. A validation function is available to pre-check ZIP contents before upload.The skill name must be unique within the target skill space. If a skill with the same name already exists in the target space, the upload is rejected; rename the skill and re-upload, or use the optimize function to overwrite the existing skill.

When viewing files or downloading a ZIP, Studio downloads the skill package from the skill space’s region and ignores macOS metadata files such as __MACOSX directories, .DS_Store, and ._-prefixed files while extracting. For skills using the legacy SkillSpace interface type, Studio falls back to resolving the skill by name so their file list and SKILL.md still load. A download or parsing failure returns a structured retryable error; retry after verifying the region, credentials, and network.

Skills support native version history. Uploading a ZIP with the same skill name as an existing skill creates a new version under the original skill ID and updates only its personal space association. Both ZIP uploads and optimized source updates wait for a new ready version instead of reusing an old running version. You can inspect files and submit reviews for a selected historical version from the version dialog.

Generate skills with the Dev Sandbox

Selecting “Create skill” on a skill space page opens the Dev Sandbox skill generation workbench. The workbench creates an independent development sandbox session via the DevEnv Tool and generates a SKILL.md and associated files in ADK skill format from a natural-language description.

Generation plan

Setting	Description
Goal	Required. Describe what you want the skill to accomplish in natural language, up to 20,000 characters.
Skill name	Optional. Must contain only lowercase letters, digits, and hyphens, up to 64 characters; auto-generated when left blank.
Generation plan	Each group starts an independent Dev Sandbox session. Up to 3 groups can be added; each selects a model and style to generate candidate skills in parallel.

Available style presets for each group:

Style	Description
Concise	Generates short, directly actionable instructions.
Strict	Prioritizes robust constraints, explicit validation, safe failure modes, and edge cases.
Tutorial	Clear sequencing with small concrete examples.
Automation	Optimized for repeatable automation, deterministic steps, and minimal manual intervention.
Custom	Describe your own expression style, rigor level, or output preferences.

The model list is read from the DevEnv Tool configuration; a model ID can also be entered manually.

Generation workflow

Enter goal and configuration

In the generation workbench, enter the goal description, an optional Skill name, and select a model and style for each candidate group.

Generate candidates

Click “Generate” to start an independent Dev Sandbox session for each group in parallel. Activity records are shown in real time during generation, including status, reasoning content, and tool calls.

Validation and auto-repair

After generation completes, Studio validates the skill format. If validation fails due to format issues (such as missing SKILL.md, non-compliant frontmatter, or mismatched directory name), auto-repair runs up to 2 times; manual re-repair is available after auto-repair is exhausted.

Preview and refine

Validated candidates display the complete file tree. You can enter follow-up adjustment instructions in the input box to iteratively refine the current candidate.

Download or publish

After generation completes, download the skill as a ZIP or publish it directly to the current skill space. The skill name must be unique within the target skill space; if a skill with the same name already exists, publishing is rejected — rename and publish again, or use the optimize function to overwrite. When optimizing an existing skill, you can choose to overwrite the original.

Dev Sandbox sessions have a 1-hour time-to-live. Leaving the workbench stops running sessions and releases resources. Refreshing or closing the page during generation does not affect already-started sessions, but keeping the page open is recommended to track progress.

Dev Sandbox sessions run in an AgentKit development environment. Generated skill content comes from model output; review the files before publishing to ensure they do not contain sensitive information or inappropriate content.

Optimize an existing skill

When browsing skills in a skill space, you can select “Optimize” for an existing skill. The optimization workflow is similar to creation but uses the existing skill as the source: enter an optimization goal, start a Dev Sandbox session, and generate an improved version. After optimization, you can choose to overwrite the original skill or publish it as a new skill.

Skill review workflow

The skill review workflow lets you submit personal skill versions to the review space for administrator approval before publishing them to the enterprise shared skill space.

Submit for review

Submit a selected version from a personal skill’s action row. Studio copies the version snapshot into an independent skill in the review space, preserving the original name and writing the submitter’s display name to the author tag. The source space, skill name, version, and submission time are also recorded in tags. Duplicate submissions of the same source version are rejected while pending or approved; a returned version can be resubmitted as a new request.

Administrator review

Administrators review submitted skill versions and files in the Review Center. They can approve (with an optional comment) or return (with a required reason and optional comment). On approval, Studio copies the version snapshot into studio_share_space. After a return, the submitter can resubmit after fixing the issues; earlier decisions remain in history.

Shared skill management

Administrators can maintain approved shared skills in studio_share_space. Shared skills are read-only snapshots, independent of personal skill versions.

Review actions are performed by administrators in the Review Center. Submitters can view the review status, reviewer, decision time, comments, and return reasons from the personal skill list, details, and version dialog.

Automatic skill assessment

Submitted skill versions are automatically assessed using AI. Assessment uses the same model as automatic agent creation and scores through the Ark structured-output API.

Dimension	Weight	Description
Safety	40%	Evaluates whether the skill poses security risks.
Usability	25%	Evaluates whether the skill is easy to understand and use.
Completeness	15%	Evaluates whether the skill’s functionality is fully covered.
Reliability	10%	Evaluates the skill’s stability across different scenarios.
Maintainability	10%	Evaluates the maintainability of the skill’s code and documentation.

Studio calculates the weighted total and includes per-dimension scoring rationale, risks, and suggestions. Assessment reads only the fixed submitted snapshot without running its code or tools. Each dimension receives a score and rationale; when file coverage is incomplete, the safety, completeness, and total scores may be omitted.

Assessment reads at most 100 text files, with up to 40,000 characters per file and 120,000 characters total. Omitted, binary, and truncated files are disclosed in the report.

Assessment reports are stored under the review-scores/ directory in the Studio persistent storage bucket. Review status, total score, assessment time, model, and report location are recorded in skill tags. Administrators and the submitting user can view the full JSON report; administrators can retry failed assessments. Completed reports are immutable. Manual review decisions and published shared skills remain independent of AI scores.

Review Center

The Review Center is located in the sidebar’s Administration group, alongside User Management. It is visible only to administrators; the group is hidden entirely when no entries are visible. Administrators can switch between skill and agent review requests in the Review Center, with region, status filters, and search. Skill review requests are loaded from the regional review space. Each request shows the AI assessment status and total score; the details view exposes per-dimension scoring rationale, risks, file coverage, model metadata, and JSON report download. Review requests support approval (with an optional comment) or return (with a required reason and optional comment), and display reviewer details and history. Agent review requests are loaded from the Runtime list for the selected region, showing agents with a submitted review application. Each request shows the agent name, applicant, submission time, current version, and model; the details view shows the agent description, application notes, and configuration fingerprint verification result. Administrators can approve (with an optional comment), return (with a required reason and optional comment), or publish directly. After a review action, the applicant can see the review status, reviewer, decision time, and comments on the agent card. See Agent publication review.

Agent publication review

Agent publication review allows developers to request that a deployed agent be shared with everyone in the organization, subject to administrator approval. Review records are stored in Runtime tags, independently of skill reviews.

Submit a request

On the agent card in the “Manage agents” page, click “Request publication” and enter an application note (up to 20 characters). The agent must have been deployed through Studio (the Runtime tag veadk:managed must be true) and be in a running or ready state. After submission, the agent enters a pending review state. The application record is written to Runtime tags, including the application ID, status, submission time, application note, and configuration fingerprint.

Administrator review

Administrators view applications in the Agent tab of the Review Center and can approve (with an optional comment, up to 256 characters), return (with a required reason, up to 256 characters, and an optional comment), or publish directly. On approval, Studio verifies that the configuration fingerprint matches the one captured at submission; if the agent configuration has changed since submission, approval is rejected and the administrator is prompted to return the application first. Direct publish skips the application flow and lets the administrator set the agent to enterprise-visible immediately. Reviewer information, decision time, and comments are written to Runtime tags.

Enterprise visibility and unpublish

After approval or direct publish, the agent is marked as visible to everyone in the organization. All users can see and use the agent from the agent list. The agent owner or an administrator can unpublish the agent; after unpublishing, other users can no longer access the agent.

The review status can be one of the following:

Status	Description
Pending	An application has been submitted and is awaiting administrator review.
Approved	The administrator has approved the application; the agent is visible to everyone.
Returned	The administrator returned the application; the submitter can resubmit after adjustments.
Withdrawn	The submitter withdrew the application before a decision was made.

An agent with a pending application must be withdrawn before it can be modified or deleted; a published agent must be unpublished first. After unpublishing, other users can no longer access the agent through the Studio proxy, but an already-running conversation stream is not terminated.

Enterprise-visible agents expose conversation capabilities to other users through the Studio proxy. Other users can view agent information and start conversations, but only access their own sessions; agent management, logs, credentials, and other users’ sessions remain restricted.

Review records are stored in Runtime tags, including the application ID, status, submission time, application note, configuration fingerprint, reviewer information, and review comments. Each submission replaces the previous application record. The configuration fingerprint verifies whether the agent configuration has changed since submission, preventing an approved agent from differing from the actual deployed content. Reviewer avatars and names are resolved through the Identity user pool.

Knowledge

The Knowledge tab lets you create and manage user-owned AgentKit knowledge bases, and upload files or import web pages as knowledge data. Knowledge bases are created on the AgentKit platform; creation and write operations require Studio to use Volcengine or BytePlus credentials to call the AgentKit knowledge service.

Create a knowledge base

Click “Create knowledge base” to open the dialog and provide the following:

Field	Required	Description
Name	Yes	1–48 characters, starting with a letter, containing only letters, digits, and underscores.
Description	No	Up to 80 characters.

The description is limited to 80 characters because Studio appends a signed marker to identify knowledge base ownership; the combined description and marker must not exceed the AgentKit knowledge base’s 200-character description limit.

Knowledge bases are loaded by region and support name search. Volcengine deployments list knowledge bases in cn-beijing and cn-shanghai; BytePlus deployments list knowledge bases in ap-southeast-1. When creating a new knowledge base, the region options are cn-beijing for Volcengine and ap-southeast-1 for BytePlus.

Manage knowledge bases

Each knowledge base card shows the name, description, creator, and status. Users with management permission can edit the description, add data, or delete the knowledge base; users without permission can only browse.

Action	Description
Edit description	Modify the description, up to 80 characters. The name cannot be changed after creation.
Add data	Upload a file or import a web page as a knowledge document.
Delete knowledge base	Requires confirmation. Deletion is irreversible; the knowledge base and all its data are removed.

Add knowledge data

After entering a knowledge base, users with management permission can add knowledge data. Three source types are supported:

Source	Supported formats	Description
Image	PNG, JPG, JPEG	Single file up to 200 MB.
Document	PDF, PPTX, DOCX, XLSX, TXT	Single file up to 200 MB.
Web page	Public web page URL	Studio fetches the page server-side, extracts the main content as Markdown, and stores it in the knowledge base after preview confirmation.

Web page imports are performed by the Studio server with SSRF protection: the target URL and resolved IP addresses are validated against internal or reserved ranges; redirects are limited to 3, HTML size to 5 MB, and extracted Markdown to 2 MB; only text/html and application/xhtml+xml content types are accepted.

When importing a web page, Studio first fetches the page and extracts the main content as Markdown, then shows a rendered preview before saving. Only an explicit confirmation stores the previewed Markdown; cancelling or a preview failure leaves the knowledge base unchanged. Web documents are named automatically from the page title, falling back to the hostname when no title is available. When the primary extractor yields no content, Studio attempts a fallback parser to extract visible body text; if the page requires JavaScript rendering and has no visible content, Studio reports that the page cannot be imported. Imported web documents show their original Markdown source when previewed in the knowledge base, rather than chunked retrieval results.

Each knowledge data item supports an optional name, type, and metadata (JSON format). After adding, you can preview the parsed content in the knowledge base, including text, tables, images, and PDFs. Data parsing takes time; newly added data may not be previewable immediately—refresh later to check.

File uploads are relayed through Studio’s private TOS storage before being imported into the AgentKit knowledge base. When Studio persistent storage is configured, the corresponding bucket is reused automatically.

Artifacts

The Artifacts tab consolidates documents, images, and videos generated during conversations. Image and video artifacts are persisted to Studio persistent storage and remain available after refreshing the page or switching sessions; document artifacts are shown only while the corresponding session events are available. Artifacts are grouped by session source, showing the associated app, session, and creation time, with type filtering and search support. Click an artifact to preview images or videos; document artifacts support inline preview. When you open the Artifacts tab, Studio automatically collects image and video artifacts from the currently visible session events and syncs them to persistent storage. Artifacts that have already been saved are not written again; only image and video artifacts are synced.

Manage artifacts

Each persisted artifact supports the following actions:

Action	Description
Preview	Preview image or video content inline.
Download	Download the artifact file to your computer.
Edit info	Update the artifact name, description, and tags.
Delete	Requires confirmation before deletion. Once deleted, the artifact and its content cannot be recovered.

When editing artifact info, the name is up to 180 characters, the description is up to 500 characters, and you can add up to 10 tags with each tag up to 32 characters.

Prerequisites

Artifact persistence depends on Studio persistent storage. When persistent storage is not configured, the Artifacts tab cannot sync or display persisted artifacts and shows “管理员未配置持久化存储”. For configuration details, see Studio persistent storage. Artifact syncing validates the source URL: only HTTPS addresses from trusted generation services are accepted, and sources that resolve to private or reserved IP ranges are blocked, preventing content from untrusted addresses. The default trusted source host suffixes are volces.com, volccdn.com, byteplus.com, and bytepluses.com. The maximum size for a single artifact defaults to 512 MB.

Artifact content is stored in the TOS bucket configured for Studio, isolated by the signed-in user. Do not generate or upload content containing sensitive information in conversations.

The following environment variables adjust artifact sync behavior:

Environment variable	Default	Description
`VEADK_ARTIFACT_MAX_FILE_BYTES`	`536870912` (512 MB)	Maximum number of bytes allowed for a single artifact.
`VEADK_ARTIFACT_SOURCE_HOSTS`	`volces.com,volccdn.com,byteplus.com,bytepluses.com`	Comma-separated trusted source host suffixes; uses the default when empty.

Scheduled tasks

The Scheduled tasks workspace is accessible from the sidebar via the “Scheduled tasks” entry. It runs a fixed text prompt against a deployed Runtime Agent on a recurring schedule. Each trigger creates an independent session for that Runtime, and the task always follows the Runtime’s currently active version. Scheduled tasks are a Beta capability.

Scheduled tasks rely on Studio persistent storage to persist task definitions, locks, execution history, and results. When persistent storage is not configured, the Scheduled tasks workspace is unavailable and shows “管理员未配置持久化存储”. For configuration details, see Studio persistent storage.

Create and edit tasks

Click “Create task” on the Scheduled tasks page to open the task form. Editing an existing task uses the same form. The form contains the following fields:

Field	Description
Task name	Display name of the task, up to 80 characters.
Runtime Agent	Select a deployed Runtime Agent. The task always uses its currently active version. Cannot create a task when no Runtime is available.
Execution text	The fixed text prompt sent to the Runtime Agent on each trigger, up to 20,000 characters.
Schedule	Schedule type and corresponding time settings, see the table below.
Timezone	The IANA timezone used for schedule times. Defaults to the browser timezone.
Enable after creation	When enabled, execution starts from the next scheduled time. When disabled, the task is created but does not trigger automatically.

The following schedule types are supported:

Type	Configuration	Description
One-time	Execution time	Triggers once at the specified time.
Daily	Daily execution time	Triggers every day at the specified time.
Weekly	Day of week, execution time	Triggers at the specified time on the specified day of week.
Cron	Cron expression	Triggers on a five-field Cron expression (minute, hour, day of month, month, day of week in order).

Manage tasks

The task list shows the name, associated Runtime, schedule, enabled status, next execution time, and latest result. Each task supports the following actions:

Action	Description
Run now	Trigger an immediate execution without waiting for the schedule. Unavailable when the task is running or paused.
Pause / Enable	When paused, the task no longer triggers on schedule. Re-enabling resumes execution from the next scheduled time.
Edit	Modify the task name, Runtime, execution text, schedule, or timezone.
Delete	Requires confirmation before deletion. Cannot delete a task with a running execution.

Click a task name to open its detail page, which shows the task configuration and execution history.

Execution history

Execution history records the status, duration, Runtime version used, and session identifier for each run, and retains the final answer and error details. Run statuses include queued, preparing, running, auto-retrying, succeeded, failed, cancelled, and skipped. Each run uses an independent session, and results and errors are retained permanently. Runs in queued or running state can be cancelled: queued runs can be dequeued, and running runs can be terminated. Failed runs can be re-executed. Execution history supports manual refresh.

Manually triggered runs are persisted with a “queued” status and placed in the next minute’s processing queue, so they normally start within 60 seconds. This avoids losing a run when the current minute has already been scanned.

Execution mechanism

Task definitions, run locks, execution history, and results are stored in the Studio private TOS bucket. In cloud deployments, veadk studio deploy creates or updates two additional stateless VeFaaS functions and corresponding minute timers: a scanner copies due tasks into a durable execution queue and advances each task’s schedule once per minute, while an asynchronous worker drains the queue, invokes the Runtime, and writes terminal results. The scanner, worker, and Studio can restart independently without losing tasks. Duplicate timer deliveries are deduplicated with immutable run IDs and TOS conditional writes; an ETag lock prevents concurrent executions of the same task across instances. The worker uses the function IAM role to read the Runtime’s current endpoint and version, and does not store user tokens or AK/SK credentials. When running Studio locally with veadk studio --vite, the Studio backend starts independent local scan and execution loops; no separate scheduler process is required.

`veadk studio` options

Option	Type	Default	Description
`--agents-dir`	`str`	`.`	Parent directory of agent applications. Each child directory with `agent.py` exposing `root_agent` is an app.
`--frontend-dir`	`str \| None`	Bundled UI, then `./frontend/dist`	Override the built Studio UI directory.
`--site-title`	`str \| None`	`VEADK_SITE_TITLE`, otherwise `AgentKit Studio`	Custom system name, up to 16 characters.
`--site-logo`	`str \| None`	`VEADK_SITE_LOGO`	Custom logo as a local image path or HTTP(S) URL.
`--host`	`str`	`127.0.0.1`	Bind address.
`--port`	`int`	`8000`	Bind port.
`--provider`	`volcengine` \| `byteplus`	`AGENTKIT_CLOUD_PROVIDER`/`CLOUD_PROVIDER`, then `volcengine`	Cloud provider for AgentKit services. Defaults to `AGENTKIT_CLOUD_PROVIDER` then `CLOUD_PROVIDER`, falling back to `volcengine` when neither is set; selecting `byteplus` reads credentials from `BYTEPLUS_ACCESS_KEY`, `BYTEPLUS_SECRET_KEY`, and the optional `BYTEPLUS_SESSION_TOKEN`.
`--dev`	Boolean flag	`false`	Load local agents in the picker instead of cloud AgentKit Runtimes.
`--vite`	Boolean flag	`false`	Serve only the API and allow CORS from the Vite development server at `http://localhost:5173` (and the fallback port `http://localhost:5174`).
`--oauth2-user-pool`	`str \| None`	`None`	VeIdentity user-pool name. Combine with a client name or UID to enable SSO.
`--oauth2-user-pool-client`	`str \| None`	`None`	VeIdentity user-pool client name.
`--oauth2-user-pool-uid`	`str \| None`	`OAUTH2_USER_POOL_ID`	Select the VeIdentity user pool by UID.
`--oauth2-user-pool-client-uid`	`str \| None`	`OAUTH2_USER_POOL_CLIENT_ID`	Select the user-pool client by UID.
`--oauth2-redirect-uri`	`str \| None`	`OAUTH2_REDIRECT_URI`, otherwise `http://{host}:{port}/oauth2/callback`	OAuth2 callback. Public deployments require an externally reachable URL.
`--oauth2-provider`	`str \| None`	`OAUTH2_PROVIDER`; defaults to `veidentity` with a pool	SSO provider identifier.
`--oauth2-provider-label`	`str \| None`	`OAUTH2_PROVIDER_LABEL`	Login-button label. When unset, the default label for VeIdentity login follows the cloud provider: “火山引擎 Identity” for volcengine and “BytePlus Identity” for byteplus.
`--auth-mode`	`frontend \| gateway`	`frontend`	`frontend` handles login in Studio; `gateway` trusts JWT identity forwarded by an upstream gateway. It also reads `VEADK_FRONTEND_AUTH_MODE`.
`--super-admin`	`str \| None`	`None`	Initial super administrator email or UID when an Identity user pool is configured. Enables Identity role management; other users default to regular users. Also reads `VEADK_STUDIO_SUPER_ADMIN`.
`--admin`	`str \| None`	`None`	Comma-separated admin list (usernames or OAuth emails). Only effective locally without an Identity pool. Also reads `VEADK_STUDIO_ADMINS`.
`--developer`	`str \| None`	`None`	Comma-separated developer list (usernames or OAuth emails). Only effective locally without an Identity pool. Also reads `VEADK_STUDIO_DEVELOPERS`.
`--generated-agent-test-run-ttl`	`int`	`1800`	Lifetime in seconds for temporary generated-agent test processes.
`--open` / `--no-open`	`bool`	`--no-open`	Open the default browser when ready. Ignored with `--vite`.
`--sandbox-chat-codex-tool-id`	`str`	`SANDBOX_CHAT_CODEX`	CodeEnv Tool ID for temporary chats
`--sandbox-chat-openclaw-tool-id`	`str`	`SANDBOX_CHAT_OPENCLAW`	ArkClawEnv Tool ID for OpenClaw chats
`--sandbox-chat-hermes-tool-id`	`str`	`SANDBOX_CHAT_HERMES`	HermesEnv Tool ID for Hermes chats
`--sandbox-chat-codex-snapshot-tool-id`	`str`	`SANDBOX_CHAT_CODEX_SNAPSHOT`	Snapshot-enabled CodeEnv Tool ID for persistent chats
`--sandbox-chat-openclaw-snapshot-tool-id`	`str`	`SANDBOX_CHAT_OPENCLAW_SNAPSHOT`	Snapshot-enabled Tool ID for persistent OpenClaw chats
`--sandbox-chat-hermes-snapshot-tool-id`	`str`	`SANDBOX_CHAT_HERMES_SNAPSHOT`	Snapshot-enabled Tool ID for persistent Hermes chats
`--help`	`bool`	—	Show help for the installed version

Deploy to VeFaaS

The current Preview deploys Studio itself with 8 vCPU, 16 GB memory, and one instance on both Volcengine and BytePlus. These are workbench-service defaults, not defaults for agent Runtimes created inside Studio; those use project deployment settings

veadk studio deploy deploys Studio as a VeFaaS application protected by VeIdentity login. It creates or reuses a Serverless API Gateway. Unless you pass an IAM role, it also creates or reuses VeADKFrontendServiceRole and VeADKFrontendPolicy. When --user-pool-id and --allowed-client-id are omitted, the command creates or reuses a named VeIdentity user pool and web client in the deployment region. After deployment, the command registers the public callback with the user-pool client and updates the application configuration. Before deployment, the command checks the VeFaaS service role ServerlessApplicationRole: if it is missing, the role is created automatically with the vefaas_full_access custom policy and the required system policies; if the role already exists, the command reconciles any missing custom and system policies for both Volcengine and BytePlus. This check is independent of --iam-role and runs even when a custom role is specified.

This operation creates or changes VeFaaS, API Gateway, IAM, and VeIdentity resources. It can incur charges and affect production access. The default role has broad permissions to create and manage AgentKit runtimes and related cloud resources. Have an administrator review the scope before production deployment; pass --iam-role to use a preconfigured, narrower role.

Prepare suitable Volcengine credentials, then run: Run from the installed and built Preview source root described above. --from-source builds and deploys that checkout. Prepare authorized Volcengine credentials first

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --project "default" \
  --from-source

When --user-pool-id and --allowed-client-id are omitted, the deploy command creates or reuses a user pool named veadk-studio-{vefaas-app-name} and a web client named veadk-studio-{vefaas-app-name}-web in the region selected by --region, and prints their IDs on completion. You can also pass both options to use existing resources; passing only --user-pool-id creates or reuses a web client within that pool. Passing --allowed-client-id without --user-pool-id raises an error. To deploy the unreleased Studio capabilities documented in Preview, run this command from the VeADK source directory and use --from-source so the current source is built into VeFaaS. Without this option, deployment uses the latest PyPI release, which does not contain unreleased capabilities.

veadk studio deploy treats VeFaaS deployments as idempotent by application name: deploying again with the same --vefaas-app-name updates the existing application’s function code bundle instead of creating a duplicate function, preserving the original URL, IAM, gateway, and Identity configuration. This is suitable for upgrading Studio or redeploying under the same application name.

After deployment, Studio sets the VeFaaS function’s minimum instance count to 1, keeping one warm instance so that the first request after deployment does not incur a cold start.

When deploying with --provider byteplus, the staged requirements file includes --extra-index-url https://pypi.org/simple at the top, allowing pip to fall back to the public PyPI index when packages are unavailable from the BytePlus default package index, preventing deployment failures caused by missing packages.

Deployment credentials are resolved in the following order: explicit --volcengine-access-key / --volcengine-secret-key options take precedence; otherwise the VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY environment variables of the current process are read; when neither is present, the [default] profile in ~/.volc/credentials is used. Any source that yields a complete access key and secret key is sufficient to proceed. For STS temporary credentials, the session token is supplied via --volcengine-session-token, or resolved from the VOLCENGINE_SESSION_TOKEN / VOLC_SESSIONTOKEN environment variables and the session_token field of the [default] profile in ~/.volc/credentials; when not provided it is left empty and only long-lived AK/SK are used. On success, the terminal prints the public URL, VeFaaS application ID, Identity region, user pool ID, user pool domain, and client ID. Opening the URL redirects the user through VeIdentity login. When the deployment automatically provisions an Identity user pool, a TOS bucket, or sandbox Tools (i.e., existing resources were not specified via --user-pool-id with --allowed-client-id, VEADK_STUDIO_TOS_BUCKET, or sandbox Tool ID options), the terminal additionally prints a summary of the configured cloud resources. The summary lists each sandbox Tool type and its ID, the private TOS storage address, the user pool ID, and the client ID, along with a link to the Identity console for the corresponding cloud provider. When Studio manages the user pool (i.e., no existing pool is passed via --user-pool-id), deployment configures the pool for SSO-only sign-in by default: password sign-in, passwordless sign-in, sign-up, recovery, and unconfirmed-user login are disabled, and an SSO identity provider must be configured in the Identity console before inviting users. Pass --allow-dangerous-login to explicitly enable those local login flows on a Studio-managed user pool; the flag only applies to Studio-managed pools. When an existing user pool is provided via --user-pool-id, deployment preserves that pool’s existing login settings and ignores this flag.

--allow-dangerous-login enables local account login flows on the user pool and weakens sign-in security. Use it only in controlled or testing environments; production deployments should keep the default SSO-only configuration.

The deployment also creates or updates two stateless VeFaaS functions and corresponding minute timers for scheduled-task scheduling: a scanner copies due tasks into a durable execution queue and advances schedules once per minute, while an asynchronous worker drains the queue, invokes the Runtime, and writes results. After deployment, the terminal prints the scanner and worker function IDs and timer IDs.

During deployment and update, the terminal streams real-time VeFaaS release progress: the code upload phase shows a progress bar (percentage, speed, and ETA), and the release phase shows release status, revision, build stages (installing dependencies, building image, deploying service, starting service), and elapsed time. Build logs are printed as they become available with repeated lines suppressed; during quiet periods a progress message reports the current stage and elapsed time every 15 seconds. Optional log retrieval uses short timeouts and does not interrupt deployment. Logs are redacted of credentials before output, including access keys, bearer tokens, and signed URL query parameters. The scheduled-task scanner and worker Functions each show independent deployment progress, build logs, and final status. Volcengine uses Chinese progress messages and BytePlus uses English messages.

--region selects the Studio deployment region, defaults to cn-beijing, and also supports cn-shanghai; the VeFaaS Application, Function, API Gateway, and AgentKit resources use the selected deployment region. When both --user-pool-id and --allowed-client-id are provided, the command locates the existing VeIdentity user pool and client across the deployment region and the Beijing and Shanghai regions: it queries the deployment region first, then searches the other region on a miss, emitting a warning and continuing when matched cross-region. When these options are omitted, the user pool and client are created or reused in the deployment region without cross-region lookup. --project selects the VeFaaS function project and defaults to default. The deployer’s long-lived access and secret keys are not written to the VeFaaS application environment. Deployed Studio uses temporary credentials from its bound IAM role. During deployment, a knowledge signing key is generated or reused and written to the VEADK_STUDIO_KNOWLEDGE_SIGNING_KEY environment variable to identify knowledge base ownership. If the variable already exists, the existing value is preserved; otherwise, a deterministic key is derived from the deployment secret and deployment identity, so the same deployment can verify previously created knowledge bases after updates. When --sandbox-chat-codex-tool-id is omitted, deployment creates the AgentKit CodeEnv Tool for built-in agents in the region selected by --region; the deploy command also creates an additional DevEnv Tool for the Dev Sandbox. Sessions created by these Tools use the same region as the VeFaaS Function and API Gateway. Model credentials are configured only on the respective Tools; the VeFaaS Function receives only the Tool IDs. You can pass existing Tool IDs when suitable Tools are already available in the same region. Deployment also provisions a snapshot-enabled Studio Sandbox Tool concurrently alongside the other sandbox Tools, for code projects. Model credentials (MODEL_AGENT_NAME, MODEL_AGENT_BASE_URL, and MODEL_AGENT_API_KEY) are obtained automatically and injected into the Tool. The Tool type depends on the cloud provider: BytePlus creates a StudioEnv-type Tool and Volcengine creates a Private-type Tool. Deployment, CLI updates, and cloud OTA updates share the same provisioning flow; existing workspace bindings are preserved. The Tool defaults to 8 CPU cores and 16 GB of memory, using the studio-sandbox image corresponding to the deployment region:

Cloud	Region	Image
Volcengine	cn-beijing	`enterprise-public-cn-beijing.cr.volces.com/vefaas-public/agentkit-sandbox:studio-sandbox-1.0.1`
Volcengine	cn-shanghai	`enterprise-cn-shanghai-cn-shanghai.cr.volces.com/vefaas-public/agentkit-sandbox:studio-sandbox-1.0.1`
BytePlus	ap-southeast-1	`enterprise-public-ap-southeast-1.cr.volces.com/vefaas-public/agentkit-sandbox:studio-sandbox-1.0.1`

You can override the image with the STUDIO_WORKSPACE_IMAGE environment variable to specify an image accessible in the selected region. The launch command uses the image’s built-in /opt/gem/run.sh and no longer injects editor patches. Volcengine defaults to Chinese and BytePlus defaults to English; model configuration follows the Studio configuration for the respective cloud environment. You can specify an existing persistent Tool via --studio-sandbox-tool-id (or the STUDIO_WORKSPACE_TOOL_ID environment variable); in that case the Tool is reused without creating or modifying its configuration. After deployment, the workspace is bound via the STUDIO_WORKSPACE_TOOL_ID environment variable, and the System info page displays the corresponding Tool ID. The model, endpoint, and candidate regions for sandbox Tools differ by cloud provider: Volcengine uses the doubao-seed-2-1-pro-260915 model with https://ark.cn-beijing.volces.com/api/v3, and candidate regions cn-beijing and cn-shanghai; BytePlus uses the dola-seed-2-1-turbo-260628 model with https://ark.ap-southeast.bytepluses.com/api/v3, and candidate region ap-southeast-1.

When creating sandbox Tools during deployment and updates, the CLI automatically retries transient errors such as rate limits, network failures, and temporary server errors. Concurrent Tool creations are staggered to avoid triggering rate limits. Each creation request carries an idempotency token so that retries do not create duplicate Tools. When Tool provisioning fails, error messages include the Tool ID and cloud service error details (error code, status code, and request ID) to help with troubleshooting.

IAM permission pre-check

veadk studio deploy automatically runs a read-only IAM permission pre-check before creating any cloud resources. The pre-check reads the caller’s attached IAM policies and evaluates each required IAM Action for the deployment. The required permission scope depends on the deployment configuration: when existing identity resources are not specified via --user-pool-id and --allowed-client-id, permissions for creating user pools are required; when --iam-role is not provided, role management permissions are required; when no existing bucket is specified via VEADK_STUDIO_TOS_BUCKET, bucket creation permissions are required; when sandbox Tool IDs are not specified, Tool creation permissions are required; when --gateway-name is not provided, gateway management permissions are required (including apig:UpdateRoute to enable the HTTP methods required by Studio APIs); the deployment also requires VeFaaS permissions to create and update the scheduled-task scheduler functions and minute timers (vefaas:ListFunctions, vefaas:GetFunction, vefaas:ListTriggers, vefaas:CreateTimer, vefaas:UpdateTimer); the deployment also sets the Studio function’s minimum instance count to 1 to keep one warm instance, so vefaas:UpdateFunctionResource is required; when --keep-failed-deploy is not enabled, permissions for cleaning up failed resources are also required. After the pre-check completes, the terminal prints a permission table listing each IAM Action, its purpose, and whether it is satisfied. If any permission is missing, the terminal also prints the IAM configuration URL for the corresponding cloud provider to help you add the missing permissions. The Volcengine URL is https://console.volcengine.com/iam/policymanage and the BytePlus URL is https://console.byteplus.com/iam/policymanage. In a formal deployment (without --precheck-only), if any permission is missing, the command prompts for confirmation before continuing; the default is to decline, which stops the deployment, and confirming allows the deployment to proceed despite the missing permissions. When --precheck-only is specified, a missing permission causes the command to exit immediately without a confirmation prompt. Use --precheck-only to run only the permission pre-check without creating any cloud resources, which is useful for verifying credential permissions before a formal deployment:

veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --precheck-only

The pre-check uses the deployment credentials to query IAM policies in a read-only manner and does not modify any resources.

In-app updates

Studio reads new releases from the centrally maintained TOS source in cn-beijing, regardless of the deployment region, so administrators can update the frontend and Python backend together from the navbar without extra options. The default release bucket depends on the cloud provider: veadk-studio for Volcengine and veadk-studio-byteplus for BytePlus. Use --studio-update-bucket and --studio-update-prefix (or the matching VEADK_STUDIO_UPDATE_BUCKET and VEADK_STUDIO_UPDATE_PREFIX environment variables) to override the default release source; the release source region is always cn-beijing. During the update, the cloud-provider entry point is selected automatically based on the CLOUD_PROVIDER (or AGENTKIT_CLOUD_PROVIDER) environment variable in the deployment; BytePlus deployments also have BYTEPLUS_REGION written during the update. Studio checks for updates every three minutes and lists available versions with their change notes. After an administrator confirms an update, Studio prefers downloading a thin release bundle, which does not embed runtime dependencies and instead pulls verified Python wheels and the AgentKit CLI from the current cloud provider’s public artifact source at deploy time. If the thin bundle or the public artifacts are unavailable, Studio automatically falls back to the full release bundle that includes all dependencies. Whichever bundle is used, Studio verifies its integrity before replacing the Python backend and frontend assets together and re-releasing the existing Application. The Application and Function IDs, public URL, SSO client, and server-side secrets are preserved.

Thin release bundles are published only for Volcengine; BytePlus deployments always receive the full release bundle with all dependencies.

Before starting the update, Studio pre-checks whether the current VeFaaS Function role has all the IAM permissions required to complete the OTA update (including reading the release bundle, creating and updating scheduler functions, releasing the application and functions, installing dependencies, managing scheduled-task triggers, and setting the function’s minimum instance count). The pre-check queries the attached IAM policies in read-only mode and does not modify any resources. If any permission is missing, the update is blocked before any mutation begins; the update dialog lists the missing permissions and provides a link to the corresponding provider’s IAM console for authorization. After completing authorization, the administrator can retry the update. The update progress panel shows a “Pre-checking Studio update permissions” stage. During the update, Studio checks the current VeFaaS Function for missing cloud resources and provisions them automatically: if persistent storage (VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION) is not configured, a TOS bucket is created or reused in the deployment region; if sandbox snapshot Tools (SANDBOX_CHAT_CODEX_SNAPSHOT, SANDBOX_CHAT_OPENCLAW_SNAPSHOT, SANDBOX_CHAT_HERMES_SNAPSHOT) are missing, they are created for the current cloud provider. The provisioned resources are written as environment variables into the Function configuration so that older Studio versions gain the new persistent-storage and sandbox capabilities after upgrading. The update progress panel shows a “Checking and provisioning Studio cloud resources” stage. The in-app update also creates or updates the scheduled-task scheduler functions and minute timers; the update progress panel shows a corresponding stage.

If the scheduled-task scheduler update fails, Studio records a warning and continues updating the main function without aborting the entire update. The scheduler can be repaired later by running the update again.

The VeFaaS Function console link in the update status is provider-specific: Volcengine deployments point to console.volcengine.com, and BytePlus deployments point to console.byteplus.com.

In-app updates do not modify the Function’s IAM role policy. To update IAM permissions, use the veadk studio update command.

After the update, Studio sets the VeFaaS function’s minimum instance count to 1, keeping one warm instance so that the first request after the update does not incur a cold start.

During the update, the deployment progress panel streams the VeFaaS deployment log in real time. Logs are filtered on the server to remove curl progress bars, config JSON dumps, ANSI escape sequences, and duplicate lines, retaining only deployment-relevant content. When the Function role lacks the vefaas:GetApplicationRevisionLog permission, the log panel is replaced with a permission notice that links to the corresponding provider’s IAM console (console.volcengine.com/iam for Volcengine, console.byteplus.com/iam for BytePlus) so an administrator can grant access; the update continues without interruption. After the update completes, Studio automatically reloads the page to load the new version; if an update dialog was open before the reload, it is automatically restored when the page reopens.

veadk studio deploy \
  --vefaas-app-name "veadk-studio" \
  --studio-update-bucket "custom-studio-releases" \
  --studio-update-prefix "veadk/studio/main"

In-app updates are available only to signed-in users with the admin or super admin role. They update Studio’s own VeFaaS Function and do not affect deployed AgentKit Runtimes. Cloud-resource provisioning during the update uses the deployer’s configured Volcengine or BytePlus credentials.

Deployment options

Option	Type	Default	Description
`--user-pool-id`	`str \| None`	`None`	Existing VeIdentity user-pool UID. When omitted, a named user pool is created or reused in the deployment region.
`--allowed-client-id`	`str \| None`	`None`	Existing user-pool client UID. When omitted, a named web client is created or reused in the user pool; requires `--user-pool-id` when provided.
`--client-secret`	`str`	`""`	Supply only if the secret cannot be read from the client UID. Direct arguments can enter shell history, so omit it when lookup is available.
`--allow-dangerous-login`	Boolean flag	`false`	Enable local password, passwordless, sign-up, recovery, and unconfirmed-user login flows on a Studio-managed Identity user pool. Only takes effect when no existing pool is specified via `--user-pool-id`; when an existing pool is provided, deployment preserves its existing login settings.
`--vefaas-app-name`	`str`	Required	VeFaaS application name, 4–64 characters containing letters, digits, and hyphens, but no underscores.
`--provider`	`volcengine` \| `byteplus`	`AGENTKIT_CLOUD_PROVIDER`/`CLOUD_PROVIDER`, then `volcengine`	Cloud provider for the deployment. Defaults to `AGENTKIT_CLOUD_PROVIDER` then `CLOUD_PROVIDER`, falling back to `volcengine` when neither is set; when `byteplus` is selected, credentials are read from `BYTEPLUS_ACCESS_KEY`, `BYTEPLUS_SECRET_KEY`, and the optional `BYTEPLUS_SESSION_TOKEN`, with the default region `ap-southeast-1`.
`--region`	`cn-beijing` \| `cn-shanghai` \| `ap-southeast-1`	Derived from `--provider`	Studio deployment region; also determines the region for VeFaaS, API Gateway, and related resources. When `--user-pool-id` and `--allowed-client-id` are provided, the deploy command searches existing VeIdentity user pools across Beijing and Shanghai.
`--project`	`str`	`default`	VeFaaS function project.
`--iam-role`	`str \| None`	`None`	Existing IAM role TRN for the function. If omitted, the default role is created or reused.
`--environment-cp-workspace`	`str \| None`	`None`	Existing CodePipeline workspace ID or name for Studio environment image builds. When omitted, Studio creates or reuses a managed workspace. This option is not read from environment variables.
`--environment-cr-repository`	`str \| None`	`None`	Existing Container Registry repository as `registry/namespace/repository` for Studio environment images. When omitted, Studio creates or reuses managed CR resources. This option is not read from environment variables.
`--vefaas-application-template-id`	`str \| None`	Built-in template	Override the built-in VeFaaS Application Center template ID. Also read from `VEFAAS_APPLICATION_TEMPLATE_ID`.
`--super-admin`	`str \| None`	`None`	Initial super administrator email or Identity UID. The user must already exist in the pool. Omit on first deployment to make everyone an admin; supplying it makes other users regular users by default. Later deployments preserve Identity roles. Also reads `VEADK_STUDIO_SUPER_ADMIN`.
`--site-title`	`str \| None`	`None`	Custom Studio name, up to 16 characters.
`--site-logo`	`str \| None`	`None`	Custom Studio logo as a local image path or HTTP(S) URL; bundled into VeFaaS during deployment.
`--gateway-name`	`str`	`""`	Serverless API Gateway name. If omitted, an existing gateway is reused or a gateway is created when none exists.
`--gateway-service-name`	`str`	`""`	Gateway service name; leave empty for automatic configuration.
`--gateway-upstream-name`	`str`	`""`	Gateway upstream name; leave empty for automatic configuration.
`--volcengine-access-key`	`str \| None`	Auto-resolved	Deployment access key, resolved from the option, `VOLCENGINE_ACCESS_KEY`, then the `[default]` profile in `~/.volc/credentials`.
`--volcengine-secret-key`	`str \| None`	Auto-resolved	Deployment secret key, resolved from the option, `VOLCENGINE_SECRET_KEY`, then the `[default]` profile in `~/.volc/credentials`.
`--volcengine-session-token`	`str \| None`	Auto-resolved	STS temporary-credential session token, resolved from the option, `VOLCENGINE_SESSION_TOKEN` / `VOLC_SESSIONTOKEN`, then the `session_token` field of the `[default]` profile in `~/.volc/credentials`.
`--byteplus-access-key`	`str \| None`	`BYTEPLUS_ACCESS_KEY`	BytePlus deployment access key, used only with `--provider byteplus`.
`--byteplus-secret-key`	`str \| None`	`BYTEPLUS_SECRET_KEY`	BytePlus deployment secret key, used only with `--provider byteplus`.
`--byteplus-session-token`	`str \| None`	`BYTEPLUS_SESSION_TOKEN`	BytePlus STS temporary-credential session token, used only with `--provider byteplus`.
`--veadk-version`	`str`	Latest release	`veadk-python` version installed in VeFaaS; set it only when pinning or reproducing a release.
`--from-source`	Boolean flag	`false`	Build and deploy a wheel from the current checkout, including uncommitted changes. Use it for unreleased validation, not together with a pinned release workflow.
`--keep-failed-deploy`	Boolean flag	`false`	Keep created VeFaaS Application and Function resources when deployment fails, so release logs can be inspected in the console.
`--precheck-only`	Boolean flag	`false`	Run the read-only IAM permission pre-check and exit without creating cloud resources.
`--sandbox-chat-codex-tool-id`	`str \| None`	Auto-create	AgentKit CodeEnv Tool ID for built-in agents; also read from `SANDBOX_CHAT_CODEX`.
`--sandbox-dev-tool-id`	`str \| None`	Auto-create	AgentKit DevEnv Tool ID for the Dev Sandbox; also read from `SANDBOX_DEV`.
`--studio-sandbox-tool-id`	`str \| None`	Auto-create	Tool ID for Studio Sandbox code projects; also read from `STUDIO_WORKSPACE_TOOL_ID`. When an existing persistent Tool is specified, it is reused without creating or modifying its configuration.
`STUDIO_WORKSPACE_IMAGE`	`str`	Region-dependent	Overrides the image reference used by the Studio Sandbox. Must be accessible in the selected region.
`--studio-update-bucket`	`str \| None`	`veadk-studio` (Volcengine) / `veadk-studio-byteplus` (BytePlus)	TOS bucket holding immutable Studio release bundles; written to the function env as `VEADK_STUDIO_UPDATE_BUCKET`. Also read from `VEADK_STUDIO_UPDATE_BUCKET`.
`--studio-update-prefix`	`str`	`veadk/studio/main`	TOS object prefix for the Studio main release channel. Also read from `VEADK_STUDIO_UPDATE_PREFIX`.

Deploy to VeStack

In Volcengine VeStack (hybrid-cloud) environments, the public-cloud VeFaaS Application API is unavailable. veadk studio deploy with --deploy-target vestack deploys Studio as a VeFaaS image function exposed through a shared APIG Gateway with a dedicated domain. Before deploying, build a linux/amd64 Studio image locally or in CI and push it to a VeStack image registry.

When to use

The deployment target is VeStack or a private cloud that does not support the public-cloud VeFaaS Application API.
Studio needs to use IAM-role-bound temporary credentials (STS) to access hybrid-cloud AgentKit OpenAPI, without storing long-lived AK/SK in the image or function environment.
Each sandbox session requires a dedicated AgentKit Tool for disk persistence and session isolation.

Build the image

Build a linux/amd64 image using the Dockerfile in the VeADK source directory:

bash

docker build --platform linux/amd64 \
  -f docker/Dockerfile.vestack \
  --build-arg PYTHON_IMAGE=<reachable-python-3.12-image> \
  -t <vestack-registry>/<namespace>/veadk-studio:<tag> .

If the selected VeStack base image already contains VeADK runtime dependencies, pass --build-arg VEADK_INSTALL_DEPENDENCIES=0 to skip full dependency resolution and install only the current repository and wheels staged under docker/vendor/. Before using this mode, stage wheels that are absent from the VeStack mirror:

bash

python -m pip download --no-deps \
  'openviking-sdk>=0.1.3' 'fastmcp==3.4.7' 'fastmcp-slim==3.4.7' \
  -d docker/vendor

Deploy command

This operation creates or changes VeFaaS functions, APIG Gateway, IAM Role, and VeIdentity resources. It can incur charges and affect production access. Verify that credentials have the required permissions and that the target VeStack environment is network-accessible before deploying.

Prepare suitable Volcengine credentials, then run:

bash

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio deploy \
  --deploy-target vestack \
  --provider volcengine \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --project "default" \
  --image "<vestack-registry>/<namespace>/veadk-studio:<tag>" \
  --public-domain "studio.example.com" \
  --vestack-openapi-url "https://openapi.example.com" \
  --vestack-agentkit-region "e70" \
  --vestack-apig-cluster-id "<cluster-id>" \
  --super-admin "admin@example.com"

The deployment performs the following steps:

Validates that --provider is volcengine when --deploy-target is vestack.
Parses --vestack-openapi-url and sets the OpenAPI Host and Scheme environment variables for VeFaaS, APIG, IAM, and Identity so SDK requests target the VeStack control plane.
Creates or reuses a VeIdentity user pool and web client (unless existing resources are specified via --user-pool-id and --allowed-client-id).
Creates or reuses a Studio-specific IAM Role and custom policy; when --iam-role is not provided, a role is created automatically. Some public-cloud system policies may be unavailable in VeStack; in that case, missing system policies are skipped and the validated custom policy is used.
Creates or updates a VeFaaS image function with the image, startup command, port, and role, passing only non-sensitive environment variables.
Releases the function and waits for the release to complete.
Creates or reuses an APIG Gateway, Service, Upstream, and Host Route to forward the dedicated domain to the function.
Registers the callback URL with the VeIdentity user-pool client.
Outputs the access endpoint, function ID, gateway ID, service ID, upstream ID, route ID, and IAM Role.

On success, the terminal prints output similar to:

✅ VeStack Studio Function deployed: http://studio.example.com:<port>
   function id: <function-id>
   gateway id: <gateway-id>
   service id: <service-id>
   upstream id: <upstream-id>
   route id: <route-id>
   IAM role: <role-trn>

The deployer’s long-lived AK/SK are used only to sign control-plane calls and are never written to the function environment. VeFaaS automatically mounts the IAM Role’s temporary STS credentials in the pod and refreshes them periodically; Studio uses these temporary credentials to access the VeStack AgentKit OpenAPI.

POC environments may use HTTP endpoints. Production environments should use trusted HTTPS certificates. Use --vestack-insecure-skip-tls-verify to bypass private certificate verification, but only in controlled environments.

Per-session independent Tools

In VeStack deployment mode, Studio creates a dedicated AgentKit Tool for each sandbox session instead of sharing a single Tool. Independent Tools support disk persistence and are automatically cleaned up when the session is deleted. When creating a session, you can specify the disk size (diskGb parameter), with a valid range of 5–100 GiB. The default value is determined by the deployment configuration.

Sandbox type	Independent Tool type	Description
Codex (built-in agents)	`CodeEnv`	Creates an independent CodeEnv Tool per session, bound to an IAM Role, with disk persistence.
Hermes	`Station-Hermes`	Enabled when Hermes model parameters are configured at deploy time; creates an independent Hermes Tool per session and automatically starts the Hermes Dashboard.

The Hermes independent Tool requires model parameters to be configured at deploy time (--vestack-hermes-model-agent-name, --vestack-hermes-model-api-base, --vestack-hermes-model-api-key, --vestack-hermes-model-id, and --vestack-hermes-model-agent-name). When not configured, the Hermes agent displays “Administrator has not configured the Hermes model or IAM Role.”

The Codex independent Tool is enabled by default (VEADK_STUDIO_CODEX_TOOL_PER_AGENT=true). The Hermes independent Tool is enabled only when complete Hermes model parameters are provided.

OpenAPI endpoint overrides

In VeStack environments, the OpenAPI endpoints for each cloud service typically point to internal addresses. At deploy time, --vestack-openapi-url uniformly sets the OpenAPI Host and Scheme for VeFaaS, APIG, IAM, and Identity. After deployment, Studio overrides each service’s OpenAPI endpoint through the following environment variables:

Environment variable	Description
`VEFAAS_OPENAPI_HOST`	VeFaaS OpenAPI host, overriding the default public-cloud address.
`VEFAAS_OPENAPI_SCHEME`	VeFaaS OpenAPI scheme (`http` or `https`).
`APIG_OPENAPI_HOST`	APIG OpenAPI host.
`APIG_OPENAPI_SCHEME`	APIG OpenAPI scheme.
`IAM_OPENAPI_HOST`	IAM OpenAPI host.
`IAM_OPENAPI_SCHEME`	IAM OpenAPI scheme.
`IDENTITY_OPENAPI_HOST`	Identity OpenAPI host.
`IDENTITY_OPENAPI_SCHEME`	Identity OpenAPI scheme.
`VOLCENGINE_OPENAPI_CA_BUNDLE`	Custom CA certificate path for private-certificate environments. When set, TLS verification is enabled.
`VOLCENGINE_OPENAPI_VERIFY_SSL`	Set to `false` to skip TLS certificate verification. Use only in controlled environments; prefer `VOLCENGINE_OPENAPI_CA_BUNDLE`.

VeStack deployment options

The following options take effect only when --deploy-target vestack is used; they supplement the deployment options.

Option	Type	Default	Description
`--deploy-target`	`application` \| `vestack`	`application`	Deployment target. `application` uses the public-cloud VeFaaS Application; `vestack` uses a VeFaaS image function + APIG. Also read from `VEADK_STUDIO_DEPLOY_TARGET`.
`--image`	`str`	—	Prebuilt `linux/amd64` Studio image required for VeStack deployment. Also read from `VEADK_STUDIO_IMAGE`.
`--public-domain`	`str`	—	Dedicated APIG host for the VeStack Studio deployment. Also read from `VEADK_STUDIO_PUBLIC_DOMAIN`.
`--vestack-openapi-url`	`str`	—	VeStack control-plane URL; must include scheme and host, e.g. `https://openapi.example.com`. Also read from `VESTACK_OPENAPI_URL`.
`--vestack-agentkit-host`	`str`	`ops-top.ops-top.svc:8000`	AgentKit TOP host reachable from the VeFaaS data plane. Also read from `VESTACK_AGENTKIT_HOST`.
`--vestack-agentkit-region`	`str`	—	Delivered environment region ID, e.g. `e70`. Also read from `VESTACK_AGENTKIT_REGION`.
`--vestack-codex-port`	`int` (1–65535)	`8642`	Service port used by independent VeStack Codex Tools. Also read from `VEADK_STUDIO_CODEX_PORT`.
`--vestack-hermes-port`	`int` (1–65535)	`4500`	Dashboard port used by independent VeStack Hermes Tools. Also read from `VEADK_STUDIO_HERMES_PORT`.
`--vestack-hermes-model-agent-name`	`str`	—	AgentKit model endpoint name for independent VeStack Hermes Tools. Also read from `VEADK_STUDIO_HERMES_MODEL_AGENT_NAME`.
`--vestack-hermes-model-api-base`	`str`	—	Model API base injected into independent VeStack Hermes Tools. Also read from `VEADK_STUDIO_HERMES_MODEL_API_BASE`.
`--vestack-hermes-model-api-key`	`str`	—	Model API key injected into independent VeStack Hermes Tools; prefer using environment variables. Also read from `VEADK_STUDIO_HERMES_MODEL_API_KEY`.
`--vestack-hermes-model-id`	`str`	—	Model endpoint ID injected into independent VeStack Hermes Tools. Also read from `VEADK_STUDIO_HERMES_MODEL_ID`.
`--vestack-apig-cluster-id`	`str`	—	VeStack cluster ID used by the APIG ClusterSpec. Also read from `VESTACK_APIG_CLUSTER_ID`.
`--vestack-apig-namespace`	`str`	`veadk-studio-apig`	Existing Kubernetes namespace where APIG installs the gateway. Also read from `VESTACK_APIG_NAMESPACE`.
`--vestack-apig-cluster-name`	`str`	`aio`	VeStack APIG cluster display name. Also read from `VESTACK_APIG_CLUSTER_NAME`.
`--vestack-insecure-skip-tls-verify`	Boolean flag	`false`	Allow a private or self-signed OpenAPI certificate. Also read from `VESTACK_INSECURE_SKIP_TLS_VERIFY`.

Studio BFF dynamic tools

When the connected AgentKit Runtime has enabled the Studio BFF dynamic tools host via enable_studio_tools=True, the Studio agent information rail shows Add Studio tools to this conversation below the agent’s static tools. New chats start with every Studio tool disabled; users can toggle individual tools, and the selection persists across turns within the current browser process. The browser sends the selected tool ID list on each Runtime run; an empty or omitted list uses the ordinary run path. Tool code and credentials remain in the Studio BFF and are never sent to the Runtime or browser.

This feature requires the Runtime to explicitly enable the enable_studio_tools parameter. See Deploy to AgentKit.

Session sandbox environments

On the conversation page, you can mount built AIO Sandbox or Codex Sandbox runtime environments to the current session. Once mounted, the agent gains the following tools for executing shell commands or delegating tasks inside the mounted environments:

Tool	Description
`list_envs`	Lists the environments mounted to the current session and their capabilities. The agent should call this tool first for every substantive task, semantically matching the task against each environment’s name, description, and capabilities to select the most appropriate environment.
`get_env_manifest`	Returns the read-only Manifest for a specified mounted environment, including the image, base environment, operating system, Python version, pre-installed packages, capabilities, and Sandbox Tool status.
`execute_in_sandbox`	Executes a non-interactive shell command inside a non-Codex mounted environment, including installed CLI tools. Codex Sandbox environments do not support this tool; use `delegate_to_codex_sandbox` instead. Supports setting the working directory, timeout, and waiting for a still-running command to return its result.
`delegate_to_codex_sandbox`	Delegates a complete coding, review, authoring, or engineering task to Codex inside a mounted Codex Sandbox environment. Applies to environments whose base environment is Codex Sandbox. Pass a self-contained task description (including the expected outcome, constraints, relevant context, and verification requirements); Codex inspects the environment and invokes its installed CLIs end to end. Call at most once per conversation turn; when it reports busy or timeout, do not retry automatically — surface that state to the user.

When mounting environments, you can select environments individually or by workspace in the session’s environment picker; the selection persists within the current browser session. On each run, Studio injects the mounted environment information into the conversation context and appends routing instructions to the current message, so the agent prioritizes using mounted environments to complete tasks. When the user does not explicitly request creating or delegating to a new agent, mounted environments take priority over dynamic sub-agent creation, knowledge bases, and Skill workflows. When the mounted environment’s base environment is Codex Sandbox, the agent should use delegate_to_codex_sandbox to delegate a complete task rather than splitting it into multiple execute_in_sandbox calls. The delegation result is returned directly to the user as the final tool call result; there is no need to use execute_in_sandbox to retrieve files from the Sandbox.

When an environment is mounted to a session, Studio assigns a new mount instance identifier for each mount. Sandbox Tool Sessions are reused only while the agent session, mount instance, environment version, Tool ID, image, cloud provider, and region all remain unchanged; unmounting and remounting creates a new mount instance and therefore a new Sandbox Session. Codex Sandbox progress and its Sandbox Session and Codex Thread identifiers are streamed into the tool-call card and preserved in conversation history.

execute_in_sandbox can execute arbitrary shell commands in the remote environment, install dependencies, read and write files, and access services reachable from the environment network. Confirm that command sources are trusted before running, and restrict the data, network, and permissions the environment can access. Do not write long-term credentials in commands; use the credential management supported by the environment when credentials are needed.

delegate_to_codex_sandbox delegates a task to Codex running in the remote environment, where Codex can invoke CLI tools, install dependencies, read and write files, and access the network. Confirm that the task content is trusted before running, and restrict the data, network, and permissions the environment can access. The maximum execution time for a Codex task is 30 minutes.

Branch comparison

The Studio BFF dynamic tools include a branch_compare tool. When the user asks to compare two styles, two approaches, or two creative directions, the agent can call this tool to generate two directly comparable branches in parallel and present the results as an inline card in the conversation. The tool accepts the following input parameters:

Parameter	Type	Description
`prompt`	`string`	The shared question or task both branches answer, 1–12,000 characters.
`branches`	`array`	Exactly two branch objects.
`branches[].label`	`string`	Branch name, 1–10 characters.
`branches[].instruction`	`string`	Branch-specific generation requirements, 1–4,000 characters.

The two branches are generated independently and in parallel. Each branch uses a dedicated agent in a dedicated session to produce Markdown text. Progress is streamed back incrementally during generation, and the final text is returned upon completion. The card displays both branches as tabs; users can switch between them and use the Continue this direction button to fill the selected branch into the input box for further conversation. If one branch fails, its error is shown without affecting the other branch. The model used for branch comparison defaults to doubao-seed-2-0-lite-260428 and can be overridden with the VEADK_STUDIO_BRANCH_MODEL environment variable. The tool timeout is 120 seconds.

Session artifacts

The Studio BFF dynamic tools include a studio_write_artifact (Save session artifact) tool. When enabled in a conversation that supports Studio tools, the agent can save generated reports, charts, documents, and other output as UTF-8 text files that become artifacts of the current session. The tool runs in the Studio BFF using Studio’s configured TOS bucket and server-side credentials; storage credentials are never sent to the Runtime or browser. The user and session identifiers are determined by the authenticated tool context — the agent cannot select the owner, session, bucket, or credentials through its parameters. Files are saved to artifacts/{user_id}/{session_id}/{relative_file_path}. Saving the same path replaces the existing file for the current session. The tool accepts the following input parameters:

Parameter	Type	Description
`path`	`string`	A relative file path within the session artifact directory, 1–1024 characters.
`content`	`string`	The complete UTF-8 text content of the file, up to 1 MiB.

On success, the tool returns the artifact path, file name, MIME type, size, and SHA-256 digest. Supported formats include HTML, SVG, Markdown, JSON, CSV, and code in UTF-8 text, with a maximum file size of 1 MiB per file.

Browsing and previewing artifacts

A “Session artifacts” button above the chat composer opens an artifact browser panel. The panel lists saved artifacts for the current session as a file tree, supporting refresh and pagination; the list auto-refreshes after a reply completes. Switching sessions closes the previous preview. Previewable formats include HTML, Markdown, images, JSON, and plain text. HTML previews render in a scriptless sandbox that allows only inline styles and up to 32 authenticated, same-session relative images; external resources and scripts are disabled. Other file formats can be downloaded directly.

Preview limits are 5 MB per file and 20 MB total for embedded images; larger files can be accessed via download. Small files are prefetched after replies to speed up display when the panel opens; a bounded per-session cache survives closing the panel.

Storage configuration

The session artifacts feature depends on Studio persistent storage, which requires the VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION environment variables. See Studio persistent storage. The Studio execution identity needs read, write, and list access to the bucket. Reads and writes use the Studio bucket’s region on both Volcengine and BytePlus. When Studio storage is configured, artifact previews always use that bucket, even if the Runtime has an unrelated TOS mount. When Studio storage is not configured, the reader retains support for an existing Runtime artifact mount, but the write tool is unavailable.

The tool only saves files to the current session’s artifact directory; it does not collect arbitrary files from /tmp or an independent Sandbox. The tool executes through the Studio BFF and requires no Runtime-side TOS mount or separate mount credentials.

AgentKit CLI terminal

The Studio sidebar footer provides a “Try AgentKit CLI” entry. Clicking it opens a terminal dialog over the current page. The terminal runs inside an AgentKit Dev Sandbox and automatically executes agentkit --help and agentkit --version on startup, providing a quick way to inspect the available AgentKit CLI commands and the installed version. The terminal creates a non-persistent session backed by the AgentKit Dev Sandbox (SANDBOX_DEV). When opening the terminal, Studio follows this sequence: search for an existing ready session for the current user, create a new non-persistent session if none exists, wait for the session to become ready, and then launch the terminal. During creation, the dialog shows a loading animation with status labels (searching for an existing environment, initializing environment, connecting to an existing environment). Once the terminal is ready, the toolbar displays the remaining time before the environment is recycled.

The AgentKit CLI terminal uses the same Dev Sandbox Tool as intelligent development and skill generation. For local startup, specify the Tool ID via the SANDBOX_DEV environment variable; for VeFaaS deployments, it is auto-created or reused via --sandbox-dev-tool-id. When not configured, the terminal shows “管理员未配置 AgentKit Dev Sandbox，请配置后再使用”. See Sandbox information for configuration details.

AgentKit CLI terminal sessions are isolated per user — administrators cannot access other users’ terminal sessions. This restriction is independent of Studio role permissions. Sessions are non-persistent; files and processes in the environment are not recoverable after expiry.

When a terminal request fails, the dialog displays the error details and provides a retry button. The terminal supports browser interactions such as clipboard read/write, file downloads, and pop-ups.

Studio Sandbox code projects

Studio provides persistent cloud code projects. Each user has one persistent cloud Sandbox, and projects are stored as directories under /home/gem/Projects. Users can create, name, and reopen projects from the workspace. The project list is stored on the Sandbox filesystem and survives Studio restarts.

Creating and opening projects

From the workspace page, select “Code projects” or create a new project from the workspace. When creating a project, enter a project name and Studio creates the corresponding directory in the user’s persistent Sandbox, initializing a Git repository, a Python virtual environment, and project template files. Creating a new project reuses the user’s existing Sandbox session; opening a project switches the VS Code working directory to the corresponding project path.

Project names must start with a letter and may contain letters, digits, hyphens, and underscores, up to 64 characters. The agent’s Python name converts hyphens to underscores. Existing project names are not overwritten; the UI prompts you to open them from the project list.

The editor opens directly at /code-server/; signed routing parameters remain private and are not cached. Returning to the management view keeps the editor mounted; switching directories opens the selected project directly.

Persistence and recovery

The Studio Sandbox Tool has persistent snapshots enabled. All of a user’s projects share the same persistent Sandbox session. When opening a project, if the remaining session time is less than one hour, Studio automatically extends the session to eight hours, and the title bar shows the remaining countdown. Studio reuses the user’s stable cloud session identity and automatically restores the latest ready snapshot after hibernation, rather than creating an empty replacement session. The project management panel supports fullscreen expansion, and the embedded browser uses the available page space.

Development environment

The Studio Sandbox image is built on the AgentKit Code Sandbox and includes the following development environment:

A dedicated VeADK Python environment, including veadk-python and the agentkit command
code-server (VS Code in the browser) and Jupyter
Python syntax highlighting, BasedPyright code completion, and Ruff formatting
Each project automatically creates Bash and Codex integrated terminals with the working directory set to the current project
Dark Modern theme, with Maple Mono font for code and terminals

Volcengine defaults to Chinese and BytePlus defaults to English. Model configuration follows the Studio configuration for the respective cloud environment. After configuring MODEL_AGENT_API_KEY, MODEL_AGENT_NAME, and MODEL_AGENT_BASE_URL, Codex automatically generates the model configuration without requiring interactive login.

Project templates

The default template is passed to the Sandbox by Studio when creating a project, including main.py, README.md, AGENTS.md, and .gitignore. The ${project_name} and ${agent_name} placeholders in the template are replaced with the project name and valid Python agent name at creation time. Modifying the template only requires updating Studio — no image rebuild is needed, and existing projects are not overwritten. New dependencies in templates are not automatically installed; runtime dependencies are still managed by the image.

Developer resources

The Studio sidebar footer provides a “Developer resources” entry. Clicking it opens a developer resources page over the current page, displaying the following content:

Related links: Quick links to the VeADK documentation, AgentKit CLI documentation, AgentKit platform documentation, and AgentKit console.
Best practices: Reference articles on developing and deploying agents with VeADK and AgentKit CLI.
Showcases: Application examples built with VeADK, covering a multi-agent research assistant, multimodal content analysis, a customer service workbench, a web search agent, and an A2UI interactive application.

Click the back button in the top-left corner to return to the page you were on before opening developer resources.

Frontend usage telemetry

Studio frontend product-behavior data is reported through TEA to track instance visits, sign-in usage, and the outcomes of agent deployment, sandbox creation, agent connection, message sending, debug test runs, and source code downloads. Telemetry is automatically enabled when running veadk studio (both local startup and veadk studio deploy instances) and requires no configuration; veadk frontend does not enable it. Reporting failures do not affect normal Studio usage. After the page loads, Studio records a single anonymous page entry before the user signs in; user identity is associated only after sign-in, distinguishing anonymous visits from authenticated visits. During deployment, Studio automatically provides the deploy ID, user-pool ID, application ID, function ID, deployment region, project, and cloud account ID context to the frontend through the /web/ui-config endpoint for event correlation; no manual setup is required. The cloud account ID is resolved automatically by veadk studio deploy and veadk studio update during deployment or update and written to the runtime environment; it does not represent an individual user identity. When account ID resolution fails, the deployment or update is not interrupted; the sanitized resolution error is recorded as account_id_resolution_error in the telemetry context.

Telemetry collects only usage dimensions, including deploy ID, cloud account ID, user ID, role, region, source, creation mode, whether AI-assisted generation was used, and the success or failure outcomes and failure phases of agent deployment, sandbox creation, agent connection, message sending, debug test runs, and source code downloads. Anonymous entry visits do not include a user ID, which is associated only after sign-in. Failure events retain a stable error kind and optional error code; agent deployment failure events additionally report a sanitized, length-limited error message, which during the build phase is taken from the build log text. Telemetry does not collect conversation content, prompts, generated code, environment variable values, or any secrets.

This change affects only Studio frontend product-behavior telemetry. VeADK runtime APMPlus OpenTelemetry tracing and the APMPlus query capability in issue feedback are unaffected and continue to work.

Update a deployed Studio

veadk studio update rebuilds Studio from a local VeADK source checkout, updates the existing VeFaaS Function code, and releases the original Application. The built package does not embed the full offline runtime or AgentKit CLI; instead, verified dependencies are pulled from the current cloud provider’s public artifact source at deploy time, reducing the upload size. Install Node.js and npm, then run the command from the VeADK source directory:

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio update --vefaas-app-name "veadk-studio"

When --region and --project are omitted, the command searches Beijing, Shanghai, and all visible projects. If multiple Applications have the same name, add a region or project to narrow the scope. The update preserves the Application and Function IDs, public URL, SSO, IAM, gateway, and existing environment variables. Branding and the CodeEnv and DevEnv Tool IDs change only when their options are explicitly supplied. The update also checks and provisions the Studio Sandbox Tool: if the function environment is missing STUDIO_WORKSPACE_TOOL_ID, the update automatically creates a snapshot-enabled Studio Sandbox Tool, configures model credentials (MODEL_AGENT_NAME, MODEL_AGENT_BASE_URL, MODEL_AGENT_API_KEY), and saves the binding; when a Tool ID already exists, the binding is preserved. If creation fails, the update reports an error and does not ignore the failure. When updating from an older version that does not support code projects, the new version provisions and saves the Tool ID in the background on first launch; code projects are temporarily unavailable during provisioning, and failures are logged so you can check permissions and retry the update. When the function uses the default Studio IAM role, the update also refreshes the role’s managed policies to the latest version; custom roles are not modified. The update also registers the /oauth2/callback callback of the current Studio public URL on the bound VeIdentity user-pool client and enables skip-consent, so SSO login remains usable after the update; if registration fails, the terminal prints a warning and instructs you to add the URL to the client’s allowed callback URLs manually. When querying existing deployments and submitting the code-bundle update, the command automatically retries transient server errors such as rate limiting and network jitter; if it still fails after retrying, the terminal notes that the cloud release may still be in progress and you can rerun the same update command shortly after. The update also creates or updates the scheduled-task scheduler functions and corresponding minute timers.

If the scheduled-task scheduler update fails, the command records a warning and continues updating the main function without aborting the entire update. The scheduler can be repaired later by running the update again.

After the update, the command sets the VeFaaS function’s minimum instance count to 1, keeping one warm instance to avoid a cold start on the first request.

When updating with --provider byteplus, the generated requirements file includes --extra-index-url https://pypi.org/simple at the top, allowing pip to fall back to the public PyPI index when packages are unavailable from the BytePlus default package index, preventing update failures caused by missing packages.

Option	Type	Default	Description
`--provider`	`volcengine` \| `byteplus`	`AGENTKIT_CLOUD_PROVIDER`/`CLOUD_PROVIDER`, then `volcengine`	Cloud provider of the existing Studio deployment. Defaults to `AGENTKIT_CLOUD_PROVIDER` then `CLOUD_PROVIDER`, falling back to `volcengine` when neither is set; when `byteplus` is selected, credentials are read from `BYTEPLUS_ACCESS_KEY`, `BYTEPLUS_SECRET_KEY`, and the optional `BYTEPLUS_SESSION_TOKEN`.
`--vefaas-app-name`	`str`	Required	Existing VeFaaS Application name.
`--region`	`cn-beijing` \| `cn-shanghai` \| `ap-southeast-1`	Search both regions	Limit lookup to one region. In BytePlus mode, the default search region is `ap-southeast-1`.
`--project`	`str \| None`	Search all visible projects	Limit lookup to one project.
`--path`	`str`	`.`	VeADK source checkout to build.
`--site-title`	`str \| None`	Preserve deployed value	Replace the Studio name only when supplied.
`--site-logo`	`str \| None`	Preserve deployed value	Replace the Studio logo only when supplied.
`--super-admin`	`str \| None`	`None`	Enable Identity user management and migrate the deployed admin/developer lists. Provide an existing user’s email or UID as the initial super administrator.
`--sandbox-chat-codex-tool-id`	`str \| None`	Preserve deployed value	Replace the built-in-agent Tool ID only when supplied.
`--sandbox-dev-tool-id`	`str \| None`	Preserve deployed value	Replace the Dev Sandbox Tool ID only when supplied.
`--volcengine-access-key`	`str \| None`	`VOLCENGINE_ACCESS_KEY`	Access key used for the update.
`--volcengine-secret-key`	`str \| None`	`VOLCENGINE_SECRET_KEY`	Secret key used for the update.
`--volcengine-session-token`	`str \| None`	`VOLCENGINE_SESSION_TOKEN`	STS temporary-credential session token, used in Volcengine mode.
`--byteplus-access-key`	`str \| None`	`BYTEPLUS_ACCESS_KEY`	BytePlus update access key, used only with `--provider byteplus`.
`--byteplus-secret-key`	`str \| None`	`BYTEPLUS_SECRET_KEY`	BytePlus update secret key, used only with `--provider byteplus`.
`--byteplus-session-token`	`str \| None`	`BYTEPLUS_SESSION_TOKEN`	BytePlus STS temporary-credential session token, used only with `--provider byteplus`.
`--skip-cronjob-scheduler`	`bool` (flag)	Off	Update only the main Studio Application and leave the existing scheduled-task scheduler unchanged. Useful when you only need to update Studio code without affecting the scheduler service.

Studio roles and Runtime access

When deploying Studio, role management is backed by Identity user groups. The only deployment role option is --super-admin, which accepts an existing Identity user’s email or UID:

veadk studio deploy \
  --user-pool-id <pool-id> \
  --allowed-client-id <client-id> \
  --vefaas-app-name <app-name> \
  --super-admin "owner@example.com"

On first deployment, omitting this option makes all signed-in users admins, including future users. Supplying it makes other users regular users by default. The default and individual roles are stored in Identity. Later deployments and updates preserve existing assignments. Only super admins can see and use User management to list pool users and change roles. They inherit every admin capability. Studio protects the initial super admin from demotion. To assign the first super admin to an existing installation without changing other roles, run veadk studio update --vefaas-app-name <app-name> --super-admin <email-or-uid>.

Capability	Super admin	Admin	Developer	Regular user
Manage users	Allowed	Denied	Denied	Denied
Add, debug, and deploy agents	Allowed	Allowed	Allowed	Denied
View and connect to Runtimes	All	All	Own and enterprise-visible	Own and enterprise-visible
Manage or delete Runtimes	All Studio-managed	All Studio-managed	Own only	Denied
Request agent publication	Allowed	Allowed	Allowed	Denied
Approve or publish agents directly	Allowed	Allowed	Denied	Denied
Unpublish agents	Allowed	Allowed	Own only	Denied

The backend reads current Identity group membership for each authenticated request. Refreshing the page reflects role changes in permissions and the account badge. In-app updates match the old VEADK_STUDIO_ADMINS and VEADK_STUDIO_DEVELOPERS entries to Identity users and preserve their roles. Only after migration succeeds are the old role environment values cleared. Unmatched or ambiguous entries and insufficient permissions stop migration and retain the old configuration. Empty legacy lists preserve the all-admin default; with explicit lists, unlisted users remain regular users. Existing admins are never automatically promoted to super admin.

If the old updater predates migration, the new runtime migrates on first startup and clears the Function configuration. Published revisions may retain their old environment snapshots, but these lists never overwrite initialized Identity roles. Older deployments need Identity user/group read and membership write permissions before upgrading; alternatively, the new CLI update refreshes the managed Studio IAM policy. These rules apply to both Volcengine and BytePlus.

Local sessions without an Identity pool still support veadk studio --admin ... --developer ...; deploy no longer accepts these options.

A local username is stored in the browser and can be changed or impersonated. Use it only for local development and feature testing. Production deployments must use OAuth or gateway authentication so identity and permissions are determined from verified sign-in information.

Local session ownership

When Studio is running with OAuth or gateway authentication, local ADK session reads, creates, updates, and deletes, as well as agent run requests, are bound to the signed-in identity. A user can only access sessions that belong to their own identity; matching is case-insensitive and considers the username, email, and other identifiers in the sign-in token. Requests that target local sessions without a trusted signed-in identity receive a 401. A non-admin user who attempts to access another user’s sessions receives a 403.

Even when every signed-in user has the admin role (the default when no super admin is specified on first deployment), cross-user session access still requires an explicit entry in the administrator list. This restriction is independent of role permissions and is not relaxed by the legacy “all users are admins” mode.

Admins and super admins may access other users’ local sessions for troubleshooting and support; such access is recorded in an audit log containing the actor, target user, request method, and path.

View system information

After signing in, the account menu at the bottom of the sidebar offers a “System info” entry. Selecting it opens the system information page over the current page, which displays the Studio version, storage, sandbox information, and user pools. The back button in the top-left corner of the page returns to the page you were on before opening System info; the previous page is preserved. The TOS bucket, sandbox Tools, and user pools each provide a link that opens the corresponding page in the cloud console in a new tab. This page is available only to users with the admin or super admin role, and all resource identifiers are read-only; administrators can update sandbox Tools that have available image updates (see Sandbox information).

General

Displays the Studio “Current version”. When Studio is started locally or built and deployed from source, the version is the installed VeADK version. When Studio is switched to a cloud Frontend release, the corresponding release version is shown. If no version is available, ”—” is displayed.

Storage

Displays the TOS address used by Studio persistent storage. When VEADK_STUDIO_TOS_BUCKET and VEADK_STUDIO_TOS_REGION are configured, the bucket access address is shown, for example veadk-studio-<account ID>.tos-cn-beijing.volces.com; clicking the address opens the bucket in the cloud console. When not configured, “Not configured” is displayed.

Sandbox information

Lists the sandbox Tools configured in Studio and their IDs, including Codex Sandbox (SANDBOX_CHAT_CODEX), DeepSeek Harness Sandbox (SANDBOX_CHAT_CODEX), OpenClaw Sandbox (SANDBOX_CHAT_OPENCLAW), Hermes Sandbox (SANDBOX_CHAT_HERMES), Dev Sandbox (SANDBOX_DEV), and Studio Sandbox (STUDIO_WORKSPACE_TOOL_ID), shown in a fixed order. The Studio Sandbox is used for code projects and is a Tool with persistent snapshots enabled (StudioEnv type on BytePlus, Private type on Volcengine). DeepSeek Harness Sandbox shares the same AgentKit CodeEnv Tool as Codex Sandbox (SANDBOX_CHAT_CODEX), so the two display the same Tool ID. Configured Tool IDs provide a link to the corresponding Tool detail page in the cloud console. Tools without a configured ID show “Not configured”.

Sandbox image update

The sandbox information area includes a “Check for updates” button at the top. When clicked, the Studio server uses the configured Volcengine or BytePlus credentials to query the Tool catalog for the current cloud provider and region, retrieving the latest published images for each prebuilt sandbox Tool type and comparing them against the images currently in use by each Tool. Each configured Tool displays the version tags of its current image and the latest image; when the current image differs from the latest, an update indicator is shown. The image catalog is cached on the server for 60 seconds and refreshed before an update is applied. Administrators can update prebuilt sandbox Tools whose status is “Ready” and that have an available update. An available update is either a mismatched image version or, for Codex-type Tools, a need to backfill model environment variables. Clicking the update button next to a Tool submits an update request to the cloud provider, setting the Tool’s image to the latest published version. For Codex-type Tools, if the Tool’s environment variables are missing MODEL_AGENT_API_KEY or MODEL_AGENT_BASE_URL while both CODEX_API_KEY and CODEX_BASE_URL are present, the missing MODEL_AGENT_* variables are backfilled from the corresponding CODEX_* variables during the update; existing values are not overwritten. After the update is submitted, Studio polls the Tool status until it returns to “Ready” with the updated image, then displays the result next to the Tool. Keys are never sent to the browser at any point.

When Codex Sandbox and DeepSeek Harness Sandbox share the same AgentKit Tool, they share update state and the update is applied only once. Snapshot and non-snapshot Tools are checked and updated independently. The Private (Volcengine) and StudioEnv (BytePlus) Tool types used by the Studio Sandbox do not have corresponding prebuilt published images and cannot be updated through this feature.

If a Tool’s status is not “Ready” (for example, it is currently creating or updating), the update button is unavailable. When a Tool is missing CODEX_API_KEY or CODEX_BASE_URL and cannot have its model environment variables backfilled, an error message appears next to the Tool. Add the missing variables to the Tool in the cloud console first, then refresh the System info page to re-check.

Sandbox image update only modifies the Tool’s image and environment variables; it does not verify or rebuild snapshots of existing sessions. Confirm before running that the update will not affect sessions in progress. The image update feature has automated test coverage under BytePlus, but has not been verified against a live BytePlus account.

User pools

Lists the VeIdentity user pools associated with the current Studio, showing name, ID, domain, and region. Each user pool name provides a link that opens the corresponding user pool page in the cloud console. When running locally without Volcengine credentials configured, no user pools are displayed.

Last modified on September 23, 2026

​Find a task

​Version and availability

​Start locally

​Studio persistent storage

​Cloud deployment

​Local startup

​Customize branding

​Interface language

​Create an agent

​Model selection

​Model fallback configuration

​Configure deployment settings

​Configure build resources

​Configure agent optimizations

​Configure the cloud environment

​Workspaces

​Manage runtime environments

​Create a runtime environment

​Custom configuration

​Base environment types

​Upload Dockerfile

​Build from Git repository

​Bind existing CR image

​Build environment images

​Environment build resources

​Environment share codes

​Exporting share codes

​Importing share codes

​Intelligent development

​Workflow

​Deploy validated source

​Session management

​Project version library

Version comparison

​Add and deploy from a code package

​Migrate an existing project

​Migration effect evaluation

​Enabling evaluation

​Configuring evaluation cases

​Evaluation dimensions

​Evaluation workflow

​Evaluation report

​Evaluation states

​Add skills

​Generate an agent draft from a requirement

​Structure of the generated draft

​Unresolved items

​Steps

​Permissions and failure handling

​Add a remote agent

​Troubleshoot remote agents

​Configure memory

​Configure a knowledge base

​Add the code-execution tool

​View sub-agent handoffs

​Conversation traces and issue feedback

​View the call trace

​Issue feedback

​Export a conversation

​Use smart search

​Deployment network modes

​Manage agents

​Manage drafts

​Hand off a local task to the cloud

​Handoff environment variables

​Update a deployed agent

​Update modes

​Legacy Runtime recovery

​Update safety checks

​Deliver agents through GitHub

​Delivery modes

​Configure GitHub delivery

​Attach continuous delivery during deployment

​Version management and rollback

​Sync source from the command line

​View integration methods

​Supported protocols

​Authentication and API Key

​Request examples

​Browse agents

Find a task

Version and availability

Start locally

Studio persistent storage

Cloud deployment

Local startup

Customize branding

Interface language

Create an agent

Model selection

Model fallback configuration

Configure deployment settings

Configure build resources

Configure agent optimizations

Configure the cloud environment

Workspaces

Manage runtime environments

Create a runtime environment

Custom configuration

Base environment types

Upload Dockerfile

Build from Git repository

Bind existing CR image

Build environment images

Environment build resources

Environment share codes

Exporting share codes

Importing share codes

Intelligent development

Workflow

Deploy validated source

Session management

Project version library

Add and deploy from a code package

Migrate an existing project

Migration effect evaluation

Enabling evaluation

Configuring evaluation cases

Evaluation dimensions

Evaluation workflow

Evaluation report

Evaluation states

Add skills

Generate an agent draft from a requirement

Structure of the generated draft

Unresolved items

Steps

Permissions and failure handling

Add a remote agent

Troubleshoot remote agents

Configure memory

Configure a knowledge base

Add the code-execution tool

View sub-agent handoffs

Conversation traces and issue feedback

View the call trace

Issue feedback

Export a conversation

Use smart search

Deployment network modes

Manage agents

Manage drafts

Hand off a local task to the cloud

Handoff environment variables

Update a deployed agent

Update modes

Legacy Runtime recovery

Update safety checks

Deliver agents through GitHub

Delivery modes

Configure GitHub delivery

Attach continuous delivery during deployment

Version management and rollback

Sync source from the command line

View integration methods

Supported protocols

Authentication and API Key

Request examples

Browse agents

Select a cloud Runtime