> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Studio agent workbench

VeADK Studio 1.0.7 uses the same service and complete UI as VeADK Frontend. It provides chat, search, session history, the skill center, and agent creation, testing, deployment, and management, and opens on the chat view by default.

In VeADK 1.0.7, custom configuration is the available project-creation flow; intelligent, template, and workflow entries are marked as coming soon and cannot be selected. You can preview and edit generated files, run them in a temporary test process, download a ZIP, or deploy to AgentKit. This release also supports cloud Runtime selection, multiple skill sources, multimodal conversations, and centralized deployment task status and retries.

## Start locally

Run the command from the parent directory of your agent applications:

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

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

`--open` opens `http://127.0.0.1:8000` after the service is ready. Without it, Studio starts the service without opening a browser.

Volcengine credentials are used for models, cloud-resource queries, and AgentKit deployment from the workbench. In production, provide them through environment variables or a secret manager rather than project files.

## Customize branding

Use `--site-title` to set a system name of up to six 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, while the system name becomes the browser title. Omitting `--site-title` uses the default `VeADK Studio` name.

```bash lines theme={null}
veadk studio \
  --site-title "TeamAI" \
  --site-logo "./logo.png"
```

The logo can be up to 5 MB in PNG, JPEG, GIF, WebP, AVIF, or ICO format. The equivalent environment variables are `VEADK_SITE_TITLE` and `VEADK_SITE_LOGO`. The deployment command accepts the same options and bundles remote images during deployment.

## Create an agent

1. On Add Agent, select Custom. Intelligent, template, and workflow entries are not available.
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.
3. Review the generated files and run them in a restricted temporary process; download a ZIP if you need to work offline.
4. Select AgentKit deployment and monitor the build-image, deploy, and publish stages.

The temporary test process is retained for 1,800 seconds by default and can be changed with `--generated-agent-test-run-ttl`. Generated code can call external services or access data available to Studio, so test only trusted projects and give Studio restricted credentials.

## Use smart search

Smart search provides Session, Web, Knowledge, and Memory sources. Session searches the current agent's message history; Web calls the agent's mounted `web_search` tool; Knowledge and Memory perform semantic retrieval through the mounted knowledge base and long-term memory backend. Studio enables only sources available to the agent and labels results with their index or source name and backend type.

## Deployment network modes

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

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

When you select VPC or Public + VPC, you must provide the VPC ID and subnet ID.

A private VPC runtime does not return a public data-plane address after deployment. Studio reaches it through the server-side runtime proxy, and the data-plane API key stays server-side and is never delivered to the browser. This is the same server-side runtime proxy described in "Select a cloud Runtime".

## Manage agents

Manage Agents lists AgentKit runtimes deployed through this workbench by the signed-in user. The list defaults to the Beijing region and can be switched to Shanghai. It is filtered by the user identity recorded during deployment and 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.

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

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.

## Select a cloud Runtime

In cloud mode, the agent selector in the chat sidebar lists AgentKit Runtimes that the signed-in user deployed through this workbench, 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 the Runtime's name, model, description, sub-agents, tools, skills, available search sources, and mounted components with their backend types. It does not return system prompts, credentials, or environment-variable values.
* **Runtime details**: shows the Runtime model, description, status, region, resources, version, and environment variables available to Studio.

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

## Use temporary sessions and Skill creation

The new-conversation view supports ordinary agent chat, temporary sessions, and Skill creation. A temporary session runs a multi-turn conversation in an independent AgentKit CodeEnv Session; exiting deletes the cloud Session without adding it to ordinary session history. Skill creation generates two candidates in parallel, which can be compared, previewed, downloaded as ZIP files, or added to AgentKit.

Skill creation is available only to `developer` and `admin` users. Each candidate uses a separate Session, and Studio checks its `SKILL.md`, file count, size, and paths before packaging. Candidate Sessions expire after 30 minutes and are deleted immediately when the user starts over or leaves the task.

### Local configuration

Prepare two AgentKit CodeEnv Tools in the `Ready` state before using these modes locally:

```bash lines theme={null}
export SANDBOX_CHAT_CODEX="your-chat-code-env-tool-id"
export SANDBOX_SKILL_CREATOR="your-skill-code-env-tool-id"

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

| Environment variable | Default | Description |
| :- | :- | :- |
| `SANDBOX_CHAT_CODEX` | — | Tool ID for temporary sessions; required when using this mode locally. |
| `SANDBOX_SKILL_CREATOR` | — | Tool ID for Skill creation; required when using this mode locally. |
| `VEADK_SKILL_CREATOR_TOS_BUCKET` | AgentKit account default bucket | TOS bucket used for published Skill artifacts. |
| `VEADK_SKILL_CREATOR_TOS_PREFIX` | `agentkit/skills` | TOS object-key prefix for published artifacts. |
| `VEADK_SKILL_CREATOR_PROJECT_NAME` | — | Project name used when creating a Skill. |

## `veadk studio` options

| Option | Type | Default | Description |
| :- | :- | :- | :- |
| `--agents-dir` | `str` | `.` | Parent directory of agent applications. Each child directory with `agent.py` exposing `root_agent` is an app. |
| `--frontend-dir` | `str \| None` | Bundled UI, then `./frontend/dist` | Override the built Studio UI directory. |
| `--site-title` | `str \| None` | `VEADK_SITE_TITLE`, otherwise `VeADK Studio` | Custom system name, up to six characters. |
| `--site-logo` | `str \| None` | `VEADK_SITE_LOGO` | Custom logo as a local image path or HTTP(S) URL. |
| `--host` | `str` | `127.0.0.1` | Bind address. |
| `--port` | `int` | `8000` | Bind port. |
| `--dev` | Boolean flag | `false` | Load local agents in the picker instead of cloud AgentKit Runtimes. |
| `--vite` | Boolean flag | `false` | Serve only the API and allow CORS from the Vite development server at `http://localhost:5173`. |
| `--oauth2-user-pool` | `str \| None` | `None` | VeIdentity user-pool name. Combine with a client name or UID to enable SSO. |
| `--oauth2-user-pool-client` | `str \| None` | `None` | VeIdentity user-pool client name. |
| `--oauth2-user-pool-uid` | `str \| None` | `OAUTH2_USER_POOL_ID` | Select the VeIdentity user pool by UID. |
| `--oauth2-user-pool-client-uid` | `str \| None` | `OAUTH2_USER_POOL_CLIENT_ID` | Select the user-pool client by UID. |
| `--oauth2-redirect-uri` | `str \| None` | `OAUTH2_REDIRECT_URI`, otherwise `http://{host}:{port}/oauth2/callback` | OAuth2 callback. Public deployments require an externally reachable URL. |
| `--oauth2-provider` | `str \| None` | `OAUTH2_PROVIDER`; defaults to `veidentity` with a pool | SSO provider identifier. |
| `--oauth2-provider-label` | `str \| None` | `OAUTH2_PROVIDER_LABEL` | Login-button label. |
| `--auth-mode` | `frontend \| gateway` | `frontend` | `frontend` handles login in Studio; `gateway` trusts JWT identity forwarded by an upstream gateway. It also reads `VEADK_FRONTEND_AUTH_MODE`. |
| `--admin` | `str \| None` | `None` | Comma-separated admin list (usernames or OAuth emails). Omitting both `--admin` and `--developer` treats every signed-in user as an `admin`. Also reads `VEADK_STUDIO_ADMINS`. |
| `--developer` | `str \| None` | `None` | Comma-separated developer list (usernames or OAuth emails). Also reads `VEADK_STUDIO_DEVELOPERS`. |
| `--generated-agent-test-run-ttl` | `int` | `1800` | Lifetime in seconds for temporary generated-agent test processes. |
| `--open` / `--no-open` | `bool` | `--no-open` | Open the default browser when ready. Ignored with `--vite`. |

## 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`. After deployment, the command registers the public callback with the user-pool client and updates the application configuration.

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

Prepare the user-pool UID, user-pool client UID, and suitable Volcengine credentials, then run:

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk studio deploy \
  --user-pool-id "your-user-pool-id" \
  --allowed-client-id "your-user-pool-client-id" \
  --vefaas-app-name "veadk-studio" \
  --region "cn-beijing" \
  --project "default" \
  --veadk-version "1.0.7"
```

On success, the terminal prints the public URL and VeFaaS application ID. Opening the URL redirects the user through VeIdentity login.

`--region` selects the Studio deployment region, defaults to `cn-beijing`, and also supports `cn-shanghai`; VeFaaS, API Gateway, and other resources are created in that region. Deployment also locates the 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. `--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.

When `--sandbox-chat-codex-tool-id` and `--sandbox-skill-creator-tool-id` are omitted, deployment creates two independent AgentKit CodeEnv Tools for temporary sessions and Skill creation. Existing suitable Tools can be reused by passing their IDs.

### Deployment options

| Option | Type | Default | Description |
| :- | :- | :- | :- |
| `--user-pool-id` | `str` | Required | VeIdentity user-pool UID used for Studio login. |
| `--allowed-client-id` | `str` | Required | User-pool client UID used for login. |
| `--client-secret` | `str` | `""` | Supply only if the secret cannot be read from the client UID. Direct arguments can enter shell history, so omit it when lookup is available. |
| `--vefaas-app-name` | `str` | Required | VeFaaS application name, 4–64 characters containing letters, digits, and hyphens, but no underscores. |
| `--region` | `cn-beijing \| cn-shanghai` | `cn-beijing` | Studio deployment region; also determines the region for VeFaaS, API Gateway, and related resources. The deploy command searches VeIdentity user pools across Beijing and Shanghai. |
| `--project` | `str` | `default` | VeFaaS function project. |
| `--iam-role` | `str \| None` | `None` | Existing IAM role TRN for the function. If omitted, the default role is created or reused. |
| `--admin` | `str \| None` | `None` | Comma-separated admin list (usernames or OAuth emails). Omitting both `--admin` and `--developer` treats every signed-in user as an `admin`. Also reads `VEADK_STUDIO_ADMINS`. |
| `--developer` | `str \| None` | `None` | Comma-separated developer list (usernames or OAuth emails). Also reads `VEADK_STUDIO_DEVELOPERS`. |
| `--site-title` | `str \| None` | `None` | Custom Studio name, up to six characters. |
| `--site-logo` | `str \| None` | `None` | Custom Studio logo as a local image path or HTTP(S) URL. |
| `--gateway-name` | `str` | `""` | Serverless API Gateway name. If omitted, an existing gateway is reused or a gateway is created when none exists. |
| `--gateway-service-name` | `str` | `""` | Gateway service name; leave empty for automatic configuration. |
| `--gateway-upstream-name` | `str` | `""` | Gateway upstream name; leave empty for automatic configuration. |
| `--volcengine-access-key` | `str \| None` | `VOLCENGINE_ACCESS_KEY` | Access key used during deployment. Prefer the environment variable. |
| `--volcengine-secret-key` | `str \| None` | `VOLCENGINE_SECRET_KEY` | Secret key used during deployment. Prefer the environment variable. |
| `--veadk-version` | `str` | Latest release | `veadk-python` version installed in VeFaaS. Set it to `1.0.7` to reproduce this release. |
| `--from-source` | Boolean flag | `false` | Build and deploy a wheel from the current checkout, including uncommitted changes. Use it for unreleased validation, not together with a pinned release workflow. |
| `--sandbox-chat-codex-tool-id` | `str \| None` | Auto-create | AgentKit CodeEnv Tool ID for temporary sessions; also read from `SANDBOX_CHAT_CODEX`. |
| `--sandbox-skill-creator-tool-id`, `--skill-creator-tool-id` | `str \| None` | Auto-create | AgentKit CodeEnv Tool ID for Skill creation; also read from `SANDBOX_SKILL_CREATOR`. |

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

```bash lines theme={null}
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

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

When `--region` and `--project` are omitted, the command searches Beijing, Shanghai, and all visible projects. If multiple Applications have the same name, add a region or project to narrow the scope. The update preserves the Application and Function IDs, public URL, SSO, IAM, gateway, and existing environment variables. Branding and the two Tool IDs change only when their options are explicitly supplied.

| Option | Type | Default | Description |
| :- | :- | :- | :- |
| `--vefaas-app-name` | `str` | Required | Existing VeFaaS Application name. |
| `--region` | `cn-beijing \| cn-shanghai` | Search both regions | Limit lookup to one region. |
| `--project` | `str \| None` | Search all visible projects | Limit lookup to one project. |
| `--path` | `str` | `.` | VeADK source checkout to build. |
| `--site-title` | `str \| None` | Preserve deployed value | Replace the Studio name only when supplied. |
| `--site-logo` | `str \| None` | Preserve deployed value | Replace the Studio logo only when supplied. |
| `--sandbox-chat-codex-tool-id` | `str \| None` | Preserve deployed value | Replace the temporary-session Tool ID only when supplied. |
| `--sandbox-skill-creator-tool-id`, `--skill-creator-tool-id` | `str \| None` | Preserve deployed value | Replace the Skill-creation Tool ID only when supplied. |
| `--volcengine-access-key` | `str \| None` | `VOLCENGINE_ACCESS_KEY` | Access key used for the update. |
| `--volcengine-secret-key` | `str \| None` | `VOLCENGINE_SECRET_KEY` | Secret key used for the update. |

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

```bash lines theme={null}
veadk studio \
  --admin "admin,admin@example.com" \
  --developer "alice,alice@example.com,bob"
```

The equivalent environment variables are `VEADK_STUDIO_ADMINS` and `VEADK_STUDIO_DEVELOPERS`. Use the same options for a deployed Studio:

```bash lines theme={null}
veadk studio deploy \
  --user-pool-id "your-user-pool-id" \
  --allowed-client-id "your-user-pool-client-id" \
  --vefaas-app-name "veadk-studio" \
  --admin "admin@example.com" \
  --developer "alice@example.com,bob@example.com"
```

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.

| Capability | admin | developer | Regular user |
| :- | :- | :- | :- |
| Add, debug, and deploy agents | Allowed | Allowed | Denied; add/manage items are hidden from the sidebar |
| View and connect to Runtimes | All Runtimes | Own Runtimes only | Own Runtimes only |
| Manage or delete Runtimes | All Studio-managed Runtimes | Own Runtimes only | Denied |

Studio restricts Runtime visibility according to the signed-in account. Historical Runtimes without a recorded creator are visible only to `admin` users.

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