AgentKit Local Studio

agentengine studio is KsADK's local-first workspace. It brings Agent definitions, build history, conversations, resources, traces, and orchestration into one browser surface, while model calls and builds still run through the local KsADK runtime.

It does not replace agentengine web: use the Web UI to debug one existing project; use Studio to create and maintain several local Agents from an initial requirement.

Start a workspace

After installing KsADK, start Studio in a directory that will hold your local Agents:

pip install -U "ksadk[all]"
mkdir my-agent-workspace
agentengine studio ./my-agent-workspace

Studio binds to 127.0.0.1:8080 by default. The command prints a local session URL and opens it in the browser. That URL is for local use only: do not share its #session=... fragment.

# Do not open a browser, and use a different port
agentengine studio ./my-agent-workspace --port 8081 --no-open

# Provide model settings for this launch
agentengine studio ./my-agent-workspace --env-file ./model.env

Run ksadk studio and configure the control-plane URL, region, AK/SK and model credentials in Settings. Saved values apply to subsequent runs and survive restarts; a separate studio.env is unnecessary. Wait for active runs before saving, and provide both AK/SK when switching accounts.

Settings and credentials share .agentkit/config.yaml, written with owner-only permissions and excluded from Git. Legacy settings.yaml and secrets.env are imported once and left intact. Studio never rewrites your .env. Ordinary CLI commands also load the current workspace configuration.

Precedence: explicit --env-file > saved workspace configuration > startup environment > workspace .env. The default launch remains compatible with the current directory's .env. The explicit file is a process-only override accepting allowlisted model and cloud-control variables; Settings shows the active source. Explicit --codex-proxy also overrides saved values.

Create, build, and chat

In Studio's Create Agent flow, choose a runtime, template, and model profile, then provide the Agent name and task. The runtimes currently available for local creation and execution are:

• Codex: a declarative YAML Agent for debugging with the native local Codex Runtime.
• ADK: a Python Agent that exports root_agent.
• LangGraph: a Python Agent that exports a compiled graph.

The flow creates an editable Agent definition and can build it immediately. After a successful build, open the Agent's conversation view to send a message and inspect its response, run history, and traces in the same workspace. Model credentials stay in the local environment or explicit configuration file; they are not written into the Agent definition.

You can also keep using CLI templates and then debug the generated project in the local Web UI:

ksadk init --framework langgraph my-langgraph-agent
cd my-langgraph-agent
agentengine web .

For generated files, runtime entry-point conventions, and deployment paths, see Create a project, Codex Managed Runtime, and cloud deployment.

Cloud deployment and lifecycle

After a successful build, Studio can start deployment directly. It reuses AgentEngine's existing CreateAgent, UpdateAgent, status, and delete APIs instead of introducing a parallel deployment API:

1. Choose a successful build on the Builds page and deploy it, or start a deployment on the Deployments page.
2. Follow progress, then inspect the Endpoint, runtime status, current build, and version history on the detail page.
3. Chat opens the cloud Agent inside Studio by default. Hosted UI and third-party Runtime dashboards remain secondary actions.
4. Rebuild after editing the Agent and publish with UpdateAgent; select an older version and confirm to roll back.
5. Deleting an Agent calls the cloud lifecycle API and removes the corresponding local receipt.

Cloud targets combine Studio deployment receipts with Agents already present in the account, including high-code Agents deployed by the CLI. Identity always uses the complete agent_id, so changing the source does not create duplicate conversations. If Hermes or OpenClaw does not advertise the capabilities required by Studio chat, Studio says so and links to the official dashboard instead of pretending full compatibility.

Ordinary chat is a foreground streaming request and does not require Background mode. Background sessions are reserved for tasks that must continue after the foreground connection closes. Conversations support incremental text, reasoning, tools, approvals, attachments, model selection, three approval levels, and Goal / Plan controls. There is no separate “Loop” mode in the composer.

Messaging channels and local Agent connections

Studio ships the official Channel page in the KsADK wheel and activates it in the background after the Studio listener is ready. The first page does not wait for the DSH toolchain or the Channel service; a failed background activation only affects the Channels page. Set KSADK_STUDIO_CHANNEL_DEFAULT=0 to disable the default activation.

On the Channels page, configure the independently deployed Channel service's HTTPS URL, account, workspace, and API token, then enable the local Agents that should receive IM messages. Studio opens outbound WSS only for explicitly enabled Agents. You do not run agentengine-channel locally or expose a local listening port. The service owns deployment and credential issuance; ksadk provides the client protocol and UI.

ADK, LangGraph, and other high-code Agents can skip Studio and call ksadk.connector.create_channel_connector directly against the same Channel service. Channel routes IM to an Agent; A2A handles Agent-to-Agent interoperability. They can be used together, but they are different protocols.

See Channel Connector for configuration, failure boundaries, and a code example.

Plugins and local automation in 0.8.5

The Studio plugin page exposes two explicit host boundaries. A managed DSH toolchain owns DSH Bundle/Profile lifecycle operations, while official Codex plugins remain owned by Codex App Server. KsADK does not copy plugin implementations or present an arbitrary local directory as an installed capability.

The Automations page and the Agent detail automation tab use Scheduler Lite for once, interval, cron, IANA timezone, run-now, and occurrence-history flows. Scheduling belongs to the current Studio process: stopping Studio stops 24x7 wakeups, and no cross-Pod high availability is implied. See Plugins and automations for the complete boundary.

Studio and the local Web UI

Both Studio and agentengine web bind to loopback only; neither browser UI calls a model provider directly. Browser writes are checked with local session and CSRF tokens, then the local runtime invokes the configured framework runner.

Local state and reset

Workspace data and conversations are local development state, not source code to commit. To clear a local experiment, stop Studio and remove .agentengine/ inside that workspace before starting it again.

Do not remove Agent source files or agentengine.yaml to reset conversations. Those files define the project and should remain under version control.

UI package and source

Wheel users do not need to build the Studio frontend: the wheel includes the reviewed production static assets. The public repository, sdist, and wheel do not include editable Studio React / TypeScript source; the public release gate validates and packages only ksadk/studio/static.

See build and package and the Web UI source and release contract for details.

Editable installs and frontend diagnostics

An editable Python install does not compile Studio assets. Run make build-frontend in the SDK repository and restart Studio. Wheels already contain the frontend.

Settings → About shows the served JS/CSS entry filenames, including their build hashes. After stopping the old process, upgrade in the activated environment with uv pip install -U --no-cache --reinstall-package ksadk 'ksadk[all]', restart that environment's ksadk studio, then hard-refresh the browser (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux). If the old page remains, compare uv pip show ksadk, the CLI path and entry filenames.