Deploy to AgentKit

VeADK can deploy a local agent as an AgentKit Runtime. Shared AgentKit application infrastructure provides conversation endpoints, health checks, agent topology, the built-in Web UI, short-term session defaults, and an optional Feishu lifecycle.

Prerequisites

Install veadk-python==1.0.8.
Sign in or configure Volcengine access credentials.
Export an importable root_agent from the project.
Do not commit .env, API keys, or access credentials to source control.

Create the application

Studio-generated projects call create_agentkit_app. Manually created projects can use the same entry point:

app.py

from agents.customer_support.agent import root_agent
from veadk.integrations.agentkit import create_agentkit_app

app = create_agentkit_app(
    root_agent,
    {root_agent.name: "Customer support"},
)

The application exposes AgentKit conversation APIs and these public endpoints:

Endpoint	Purpose
`/ping`	Health check.
`/web/agent-info/{app_name}`	Agent name, description, model, instruction, sub-agents, tools, skills, and mounted components.
`/web/agent-graph`	Agent topology; each node includes skills, components, path, and whether it can be selected in a conversation.
`/`	Built-in Web UI.

Runtime identity binding

create_agentkit_app accepts an optional identity parameter that passes an AgentKit Runtime identity boundary to the application. When supplied, AgentKit verifies and binds the inbound user identity before VeADK Agent or Tool code runs. Omitting identity preserves the previous behavior.

Using the identity parameter requires agentkit-sdk-python>=0.8.2. On older versions, passing identity raises an error; upgrade the AgentKit SDK first.

VeADK excludes the /ping health-check endpoint from identity binding; that endpoint always returns {"status": "ok"}. All other business and introspection endpoints are identity-bound.

app.py

from agentkit.identity import RuntimeIdentity
from agents.customer_support.agent import root_agent
from veadk.integrations.agentkit import create_agentkit_app

app = create_agentkit_app(
    root_agent,
    {root_agent.name: "Customer support"},
    identity=RuntimeIdentity(),
)

Dynamic A2A run endpoints

Applications built with create_agentkit_app override the standard AgentKit run endpoints (/run, /run_sse, /invoke) to support dynamic A2A agent discovery. When the agent is configured with an AgentKit agent center via environment variables such as REGISTRY_SPACE_ID, the run endpoints dynamically discover matching remote agents from the center and attach them as callable tools for the current turn. Without an agent center configured, the run endpoints behave identically to the standard AgentKit run endpoints.

The run endpoints create a session automatically when the specified session does not exist, instead of returning 404.

Session-scoped capability overlays

Starting with VeADK 1.0.9, applications built with create_agentkit_app mount session-scoped capability-overlay endpoints under the /harness prefix. A caller can temporarily mount a built-in tool or a remote skill for a session, then run the agent with the overlay applied through /harness/run_sse. Overlays apply only to the specified session: they do not modify the root agent definition and are not written to other sessions. Capabilities fall into two categories:

Built-in tools: from the VeADK built-in tool catalog, referenced by tool name.
Remote skills: from the public Skill Hub or an AgentKit Skill Space, referenced by skill name and skill-source identifier.

Tools and skills already mounted on the root agent are returned as base capabilities (custom is false) and cannot be removed; capabilities mounted through the overlay API are session capabilities (custom is true) and can be removed individually.

When to use

When you need to enable an additional tool or skill for a single session without redeploying the Runtime.
When you need to isolate different capability sets by session so they do not affect each other.

Dependencies

The agent must expose a tools attribute; mounting fails when the overlay is non-empty but the root agent has no tools.
Listing and mounting remote skills requires Volcengine credentials. Provide them locally with VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY; on VeFaaS, use the bound IAM Role.

Endpoints

Endpoint	Method	Purpose
`/harness/capabilities/tools`	`GET`	List mountable built-in tools.
`/harness/skills/spaces`	`GET`	List AgentKit Skill Spaces visible to the current account.
`/harness/skills/spaces/{space_id}/skills`	`GET`	List skills in the specified Skill Space.
`/harness/skills/findskill`	`GET`	Search the public Skill Hub for skills.
`/harness/apps/{app_name}/users/{user_id}/sessions/{session_id}/capabilities`	`GET`	Query the current capability list and revision for the session.
`/harness/apps/{app_name}/users/{user_id}/sessions/{session_id}/capabilities`	`POST`	Mount one built-in tool or remote skill for the session.
`/harness/apps/{app_name}/users/{user_id}/sessions/{session_id}/capabilities/{capability_id}`	`DELETE`	Remove a mounted capability from the session.
`/harness/run_sse`	`POST`	Run the agent with the session overlay applied as an SSE stream.

Examples

Mount a built-in tool for a session:

curl -X POST "$RUNTIME_URL/harness/apps/customer_support/users/u-1/sessions/s-1/capabilities" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "tool",
    "name": "web_search",
    "expected_revision": 0
  }'

Example response:

{
  "schema_version": 1,
  "revision": 1,
  "tools": [
    {"id": "base:tool:get_weather", "kind": "tool", "name": "get_weather", "custom": false},
    {"id": "session:tool:web_search", "kind": "tool", "name": "web_search", "custom": true}
  ],
  "skills": []
}

Mount a remote skill from an AgentKit Skill Space:

curl -X POST "$RUNTIME_URL/harness/apps/customer_support/users/u-1/sessions/s-1/capabilities" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "skill",
    "name": "order-lookup",
    "skill_source_id": "ss-xxxxxxxx",
    "description": "Look up order status",
    "expected_revision": 1
  }'

Run the agent with the overlay applied:

curl -N -X POST "$RUNTIME_URL/harness/run_sse" \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "customer_support",
    "user_id": "u-1",
    "session_id": "s-1",
    "new_message": {"role": "user", "parts": [{"text": "Look up my order"}]},
    "streaming": true
  }'

/harness/run_sse returns the same event format as the standard /run_sse endpoint; each event is sent as a data: -prefixed JSON line.

Parameters

POST /capabilities request body:

Parameter	Type	Default	Description
`kind`	`"tool"` \| `"skill"`	—	Capability type to mount.
`name`	`str`	—	Tool or skill name; the tool must be a built-in tool, and the skill must exist in the selected source.
`skill_source_id`	`str \| None`	`None`	Skill-source identifier. Required when mounting a skill; a `findskill:` prefix denotes the public Skill Hub, otherwise it is an AgentKit Skill Space ID.
`description`	`str`	`""`	Skill description, used only when mounting a skill.
`version`	`str`	`""`	Skill version, used only when mounting a skill.
`expected_revision`	`int \| None`	`None`	Optimistic concurrency control; pass the current `revision`; a mismatch returns 409.

GET /harness/skills/spaces and GET /harness/skills/spaces/{space_id}/skills accept a region query parameter: spaces defaults to all (combining Beijing and Shanghai), and the skill list defaults to cn-beijing. GET /harness/skills/findskill accepts these query parameters:

Parameter	Type	Default	Description
`query`	`str`	`""`	Search keyword; empty returns popular skills.
`page_number`	`int`	`1`	Page number, starting at 1.
`page_size`	`int`	`20`	Page size, range 1–50.

Limitations

Base capabilities cannot be removed; a capability_id starting with base: returns 409.
A tool or skill with a duplicate name cannot be mounted; a name that collides with a root-agent capability returns 409.
An expected_revision that does not match the current revision returns 409; the caller should re-query and retry.
Session capabilities take effect only for runs of the session they were mounted to; they are not persisted to the root agent after the run.
The public Skill Hub search URL defaults to https://skills.volces.com/v1/skills and can be overridden with the FINDSKILL_SEARCH_URL environment variable.

Initialize and deploy

Run these commands in the project directory:

veadk agentkit init
veadk agentkit config
veadk agentkit launch

After deployment, inspect the Runtime and invoke it:

veadk agentkit status
veadk agentkit invoke -m "Describe your capabilities"

veadk agentkit uses the same project configuration and workflows as AgentKit CLI. See the AgentKit CLI documentation for complete commands, flags, and destructive-operation guidance.

Destroying a Runtime removes its cloud execution resources. Before running veadk agentkit destroy, verify the project, region, and Runtime identifier and retain any logs or data you need.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Prerequisites

Create the application

Runtime identity binding

Dynamic A2A run endpoints

Session-scoped capability overlays

When to use

Dependencies

Endpoints

Examples

Parameters

Limitations

Initialize and deploy

​Prerequisites

​Create the application

​Runtime identity binding

​Dynamic A2A run endpoints

​Session-scoped capability overlays

​When to use

​Dependencies

​Endpoints

​Examples

​Parameters

​Limitations

​Initialize and deploy

Prerequisites

Create the application

Runtime identity binding

Dynamic A2A run endpoints

Session-scoped capability overlays

When to use

Dependencies

Endpoints

Examples

Parameters

Limitations

Initialize and deploy