Skip to main content
AgentKit Studio uses the same service and complete UI as VeADK Frontend. It provides chat, search, session history, the 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.

​
Start locally

Run the command from the parent directory of your agent applications:
--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 local CLI always uses Volcengine.

​
Studio persistent storage

Studio capabilities such as video creation, automatic evaluation, 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: 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.
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.

​
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, Library, and Search show the form “System name - Page name”. Omitting --site-title uses the default AgentKit Studio name.
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.

​
Create an agent

  1. 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.
  2. 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.
  3. Review the generated files and run them in a restricted temporary process; download a ZIP if you need to work offline.
  4. In the Optimization step, optionally enable Harness Sidecar optimizations for the agent; this step is optional and no Sidecar starts when nothing is selected.
  5. In the Environment step, select command-line tools to bake into the cloud Runtime image, or customize the Dockerfile used to build the image; this step is optional.
  6. 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.
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; on a build failure the failure detail is appended to 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.
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.

​
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. Deactivated models are excluded. 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:
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 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. 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:

​
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. Instance counts must be positive integers, and 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. The deployment progress shows a corresponding stage: when the instance range differs from the default 1–5, an “Update instance configuration” stage is added after Runtime creation. 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: 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: 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.

​
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: Selecting the Operations scenario automatically loads SQL read-only protection. Optimization components are grouped into three categories: 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, provide the MCP unified gateway address (MCP_URLS) and API Key (MCP_API_KEY).
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 official command-line tools to bake into the cloud Runtime image, or customize the Dockerfile used to build the image. The step is optional: when no tools are selected and no custom Dockerfile is provided, deployment uses the default AgentKit image build and the generated project contains no Dockerfile.

​
Select command-line tools

The following official command-line tools can be selected in the Environment step; selected tools are installed into the deployment image: After selecting any tool, Studio generates a provider-specific Dockerfile and adds it to the generated project (path Dockerfile). The Dockerfile builds on the AgentKit-provided base image (Volcengine uses the Beijing-region image, BytePlus uses the Singapore-region image), installs the system dependencies required by the selected tools, and downloads the binaries from the official GitHub Release archives, verifying SHA-256 checksums for both amd64 and arm64 before installing them; Pandoc is installed from system packages. The image then installs Python dependencies, copies the application code, and uses python -m app as the entrypoint.
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.

​
Customize the Dockerfile

Use “Advanced configuration” at the bottom of the Environment step to open the Dockerfile editor and edit the build content directly. The Dockerfile is limited to 64 KiB and cannot be empty; an empty or oversized Dockerfile blocks the Publish step, and Studio keeps you on the Environment step with a message.
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.
Whenever tools are selected or a custom Dockerfile is provided, the generated project includes a Dockerfile, which the cloud build service uses during deployment. Providing only a custom Dockerfile without selecting any tools also generates a Dockerfile and uses it verbatim.

​
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 then determines the intent, 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). When not configured, the entry shows “Unavailable.” veadk studio deploy creates this Tool automatically by default; for local startup you can specify an existing Tool ID manually.

​
Workflow

1

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.” If any key information may affect the result, Codex confirms with you before starting.
2

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. Delivery summaries follow a structured Markdown format: a one-sentence outcome summary first, followed by sections for Completed, Validation, and Remaining issues. The development environment is retained for up to 8 hours and can be iterated on within the same session.
3

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; 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 appear in the sidebar history list, mixed with regular conversations and sorted by time. An in-progress session shows a “Building” status; you can switch to other pages and return to resume the session. When resuming or reopening a completed session, the conversation history shows only user messages and assistant responses; internal intent-gate and task-scheduling steps are not displayed. Completed sessions can be reopened to continue the conversation or deleted; deleting an in-progress session requires stopping the active build first.
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.

​
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.
1

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.
2

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.
3

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.
4

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.

​
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 following frameworks are supported:
1

Upload the project archive

On the Add Agent menu, choose “Migrate an existing project” and upload a .zip archive of up to 50 MB.
2

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).
3

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.
4

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.
5

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 are no longer available; you must re-upload and re-migrate. The app.py 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.
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; command execution, file updates, external tool calls, web searches, and sub-task coordination each display their input, output, and exit code or error details, with error details shown when execution fails. All activity content is redacted server-side before reaching the browser; keys, tokens, and other sensitive fields are removed.

​
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.
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-2-1-pro-260628 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:
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

1

Enter the requirement

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

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.
3

Review unresolved items

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

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:

​
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 Volcengine credentials that can access AgentKit. 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.
1

Configure the root agent

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

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.
3

Select an agent center

Studio initially lists centers visible to the current account in the default project in Beijing. For another region, set the region under More options before selecting a center from the dropdown. Use the refresh button to reload the list.
4

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.
5

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. 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 Beijing. 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

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 normalize HTTP MCP tool endpoints configured on a generated agent: a URL not ending in /mcp is appended with /mcp, and tool discovery is validated over Streamable HTTP. If Studio cannot reach the MCP server to discover tools, the test returns an error prompting you to confirm the URL points to the actual MCP endpoint (typically ending in /mcp) and check the token; 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.

​
Configure memory

After enabling long-term memory for an agent, select one of these backends in Studio: 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:
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: 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 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.

​
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.
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. Opening the trace panel for a Runtime without tracing enabled prompts you to enable APMPlus tracing in the console first, and a failed trace query prompts you to retry later.

​
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: 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.

​
Share a conversation as an image

The “Share as image” button next to an assistant reply exports all inputs and outputs up to that turn as a single PNG image. The image is generated locally in the browser without any network request. The export 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 image can be previewed in the dialog. The following actions are available:
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.
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: 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.

​
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 only their own. 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.” 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.
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.
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.
1

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:
2

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.
3

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.
4

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:

​
Handoff environment variables

​
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.
1

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.
2

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.
3

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.
4

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.
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.

​
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:

​
Configure GitHub delivery

Both modes share the following form fields: 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: 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:
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

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: 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:
For the A2A protocol, the example calls the agent via the JSON-RPC message/send method:
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 tabs at the top, defaulting to General agents: The General agents list loads the signed-in user’s own Runtimes across all regions and automatically loads the next page as you scroll to the bottom of the list, showing “All agents loaded” when complete. Use the search box at the top to filter the loaded agents by name. Each agent card shows the Runtime name and creation time. 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 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.
The agent directory lists only the Runtimes created by the signed-in user and is not filtered by region. To browse other users’ or all Runtimes, use the agent selector in the top bar or the management page; the visible scope depends on role permissions.

​
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.

​
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.
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. 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.

​
Local configuration

Before using built-in agents locally, prepare one AgentKit CodeEnv Tool in the Ready state and configure its ID:
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.

​
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.
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 has ended but left a restorable snapshot, opening the sandbox session list as an administrator automatically resumes restorable snapshots for the listed agent kind. Studio resumes them concurrently in the background (up to 3 at a time), then refreshes the list to show the ready sessions directly — no manual wake is required. Snapshots that fail to resume are skipped and do not affect the rest of the list. This capability is available only to the admin role and requires the corresponding sandbox snapshot Tool to be configured.

​
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

  1. Select the “Video creation” workspace on the new-conversation page.
  2. Choose a video task mode and, as needed, upload reference assets and set the aspect ratio, resolution, and duration.
  3. Enter a video description in the input box. After submitting, Studio first enhances the prompt, then creates a video generation task.
  4. 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

​
Generation parameters

​
Generation flow

Video generation has two stages, both performed on the Studio server:
  1. Prompt enhancement: the enhancer model expands and normalizes the input prompt and resolves the final task mode.
  2. 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:
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, enabled by default. After deployment succeeds, Studio calls the AgentKit evaluation API to idempotently create two evaluation sets named {agent_name}_good_case and {agent_name}_bad_case for the agent. 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:
  1. Studio reads the latest assistant reply for that turn from the Runtime.
  2. The doubao-seed-2-0-lite-260428 model scores the reply on task completion, factual and logical reliability, tool-use soundness, clarity, and safety.
  3. 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.
  4. Auto-evaluated cases are written to the corresponding AgentKit 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:
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 Volcengine Runtime (BytePlus deployments and local debug sessions are not supported);
  • The reply has finished generating (not available while streaming is in progress or while authorization is pending).
Usage:
  1. 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.
  2. In the “Note” field, describe the problem or the expected correction.
  3. 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 agent, 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.

​
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: 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: 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

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.

​
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.
The continuous delivery and template import workflows require VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY GitHub Secrets to be configured in the repository. When using temporary credentials, VOLCENGINE_SESSION_TOKEN is also required. These Secrets are managed in GitHub and do not pass through Studio.

​
Pull Request automated review

Adds a GitHub Actions workflow to the target repository that reviews non-draft PRs from the same repository in an isolated AgentKit Sandbox and publishes the review results as a GitHub Review.
The PR review workflow only reviews non-draft PRs from the same repository, not fork PRs, and does not read repository Secrets from fork PRs.
The PR review workflow requires the following GitHub Secrets to be configured in the repository:

​
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.
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.

​
Library

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

​
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: 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.
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.

​
Manage skills

After entering a skill space, you can browse all skills within it and filter by name. Each skill supports the following actions:
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.

​
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
Available style presets for each group: The model list is read from the DevEnv Tool configuration; a model ID can also be entered manually.
Generation workflow
1

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.
2

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.
3

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.
4

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.
5

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.

​
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:
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.

​
Add knowledge data

After entering a knowledge base, users with management permission can add knowledge data. Three source types are supported:
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: 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:

​
veadk studio options

​
Deploy to VeFaaS

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:
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. 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. It also notes that password sign-in is disabled by default for security and that an SSO identity provider must be configured before inviting users. --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. The model, endpoint, and candidate regions for sandbox Tools differ by cloud provider: Volcengine uses the doubao-seed-2-1-pro-260628 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); 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 deployment stops before creating cloud resources; 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. 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:
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 veadk-studio 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. 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. The release bundle is not tied to a cloud provider — Volcengine and BytePlus deployments share the same source. 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 verifies the complete release bundle, replaces the Python backend and frontend assets together, and re-releases the existing Application. The Application and Function IDs, public URL, SSO client, and server-side secrets are preserved. 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 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.
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.
In-app updates are available only to signed-in users with the 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

​
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.
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 only a stable error kind and optional error code; error stacks, error text, and free-form text are never collected. 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. Install Node.js and npm, then run the command from the VeADK source directory:
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. 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.

​
Studio roles and Runtime access

--admin and --developer each accept a comma-separated list of local usernames or OAuth email addresses. Whitespace is ignored and matching is case-insensitive. If the same identity appears in both lists, admin takes precedence. For a local Studio:
The equivalent environment variables are VEADK_STUDIO_ADMINS and VEADK_STUDIO_DEVELOPERS. Use the same options for a deployed Studio:
Omitting both options treats every signed-in user as an admin, granting full Studio capabilities and visibility into all Runtimes. Supplying either list enables role-based access control; an identity that does not match either list is a regular user. Studio restricts Runtime visibility according to the signed-in account. Existing Runtimes without a recorded creator are visible only to admin users.
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.

​
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 the admin role, and all resource identifiers are read-only; administrators can backfill missing model environment variables on a Codex Sandbox Tool that needs repair (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), and Dev Sandbox (SANDBOX_DEV), shown in a fixed order. 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”.

​
Codex Sandbox model environment repair

For Codex Sandbox (SANDBOX_CHAT_CODEX) and Codex Sandbox snapshot (SANDBOX_CHAT_CODEX_SNAPSHOT), the System info page also checks whether the Tool’s environment variables include MODEL_AGENT_API_KEY and MODEL_AGENT_BASE_URL. When either variable is missing and the Tool also has both CODEX_API_KEY and CODEX_BASE_URL, an update button appears next to the Tool ID. When an administrator clicks the update button, the Studio server uses its own Volcengine or BytePlus credentials to read CODEX_API_KEY and CODEX_BASE_URL from the Tool’s current environment variables, backfills the missing MODEL_AGENT_API_KEY and MODEL_AGENT_BASE_URL, and shows the result next to the Tool ID. Keys are never sent to the browser at any point.
If the Tool is missing CODEX_API_KEY or CODEX_BASE_URL, the update button does not appear and an error message next to the Tool ID indicates which variables are missing. Add the missing variables to the Tool in the cloud console first, then refresh the System info page to re-check.
This action only backfills missing MODEL_AGENT_API_KEY and MODEL_AGENT_BASE_URL; it does not overwrite existing values or modify any other Tool environment variables. Before running it, confirm that the Tool’s CODEX_API_KEY and CODEX_BASE_URL point to the intended model credentials.

​
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 19, 2026