veadk-python: a Volcengine agent kit built on Google ADK

What veadk-python solves, and for whom

Building an agent usually means stitching together a model client, a session store, a tool-calling loop, a trace exporter and some HTTP surface to expose the result. veadk-python is Volcengine's attempt to ship that stack as one Python package. The README describes it as "An open-source kit for agent development, integrated the powerful capabilities of Volcengine", and the repository layout backs that up: a veadk/ package, a frontend/ directory for the bundled Web UI, a docker/ directory, and eighteen numbered example projects under examples/.

The audience is narrower than the description suggests. The configuration example in the README points at an ARK endpoint (https://ark.cn-beijing.volces.com/api/v3/) with a Volcengine API key and a model named doubao-seed-1-6-250615. The AgentKit integration, the Studio deployment flow, the skill-space browser and the Feishu channel are all Volcengine-shaped. If you are building on that cloud, this package saves you from wiring the pieces yourself. If you are not, you are adopting a large dependency tree to use a fraction of it.

The architecture: Google ADK underneath, Volcengine on top

The pyproject.toml is the most informative file in the repository. It depends on google-adk>=1.34.0 for what the comment calls "basic agent architecture", plus a2a-sdk for Google's Agent2Agent protocol. So the agent loop, the tool abstraction and the session model are Google ADK's, not Volcengine's. veadk-python is a layer above that, adding model configuration, memory backends, tracing, sandboxing and the AgentKit runtime surface.

The dependency comments also record a real portability problem. LiteLLM and SQLAlchemy are declared directly rather than inherited, because google-adk moved them behind extras in version 2.x. The SQLAlchemy entry is pinned as sqlalchemy[asyncio], and the comment explains why: the asyncio extra is what pulls in greenlet, which SQLAlchemy's async engine needs, and a bare sqlalchemy install left it to a platform marker that does not cover macOS arm64. The comment states that CI never caught this because ubuntu-latest is x86_64, where the marker matches. That is a useful signal about where the maintainers' test matrix has blind spots.

The AgentKit application layer is where veadk-python diverges most from plain ADK. The README gives create_agentkit_app as a factory that bundles AgentKit APIs, the Web UI, health checks and agent-topology endpoints, so platform routes stay out of your agent module. Studio-owned dynamic tools and HTTP routes are off by default and must be switched on with enable_studio_tools=True and enable_studio_routes=True. The metadata endpoint reports the root agent's name, description, model, sub-agents, tools and skills, and the README states that the info panel does not expose prompts or credentials.

Installing veadk-python and running a first agent

The README offers two paths. From PyPI, the base install is one command, with an extensions extra available separately:

pip install veadk-python
pip install veadk-python[extensions]

Building from source uses uv and pins the virtual environment to Python 3.12. The pyproject.toml declares requires-python as >=3.10,<3.14, so 3.12 is inside the range but 3.14 is not. The README lists database, eval and cli as separate extras, and uv sync --all-extras as the everything option:

uv venv --python 3.12
uv sync
uv pip install -e .

Configuration goes in a config.yaml at the root of your own project, which the README says VeADK reads automatically. For a minimal agent it names four keys, and the api_key value is left for you to fill in:

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: # <-- set your Volcengine ARK api key here

The README's minimal agent is four lines. Note that agent.run is awaited through asyncio.run rather than called directly, which tells you the interface is async even for the trivial case:

from veadk import Agent
import asyncio

agent = Agent()

res = asyncio.run(agent.run("hello!"))
print(res)

If you want the AgentKit surface instead of a bare agent, the README's second example passes a named root agent into create_agentkit_app with enable_studio_tools=True. It points at examples/generated_agentkit_project for a complete generated project, which is the better starting point than assembling the factory call by hand.

Where the design shows its edges

The most concrete limitation is in the pyproject.toml comment itself: the greenlet failure on macOS arm64 reached users before it reached CI. That is not a one-off bug report, it is a statement about the test matrix. If you develop on Apple silicon, treat the session layer as under-verified on your platform until you have written to a database yourself.

Multi-instance deployment has a documented constraint. The README states that for multi-instance runtimes you should use a database-backed short-term memory store so sessions remain available across instances. In other words, the default in-memory short-term memory is not sufficient once you scale past one process, and nothing in the README suggests the framework picks a database backend for you.

There is also a scope question. The README's AgentKit section describes Studio managing user-owned Codex, OpenClaw and Hermes AgentKit Sessions, browsing account-scoped Skill Spaces by region and project, and rating answers into per-agent evaluation sets named {agent_name}_good_case and {agent_name}_bad_case. That is a control plane, not a library. If you wanted a small agent runtime, you are reading documentation for a platform, and the surface area you would be depending on is much larger than the four-line quickstart implies.

The README does not document rollback for a failed deployment. It documents that a failed cloud image build returns a credential-safe excerpt from the build log, which helps you diagnose the failure, but the recovery path is not described.

veadk-python compared with using Google ADK directly

The honest alternative is google-adk on its own, because that is what veadk-python builds on. Choosing plain ADK means you keep the agent loop and session model but write your own model configuration, tracing, sandbox handling and HTTP surface. You also avoid the Volcengine coupling entirely, which matters if your models are not served from ARK.

Choosing veadk-python means you get the ARK model configuration path, the AgentKit runtime with its metadata and health endpoints, the bundled Web UI under frontend/, the Feishu channel extension, and the deployment flow that converts Studio settings into runtime environment variables. The README notes that secrets entered in the deployment form are not written to generated source or exported YAML, and that requests to Skill Spaces are signed server-side so browser clients never receive Volcengine credentials. Those are the parts you would otherwise have to build and secure yourself.

The trade is version coupling. veadk-python tracks google-adk with a floor of 1.34.0 and carries explicit workarounds for the 1.x to 2.x extras reshuffle. When google-adk changes again, someone has to update those pins. That is a maintenance commitment you inherit along with the integration.

Maintenance, licensing and upgrade cost

The repository is not archived. The last push was on 2026-09-10, the same day release 1.1.10 was published, and 1.1.9 and 1.1.8 landed on 2026-09-03 and 2026-08-31. That is a tight release cadence across the three most recent versions, and the versioning is plain semantic-style numbering rather than date-based tags.

Upgrade cost is concentrated in the dependency pins. The pyproject.toml holds litellm to a narrow window (>=1.83.7,<=1.83.14) and pydantic-settings to an exact version (2.10.1). Exact pins remove a class of surprise breakage but they also mean you cannot pick up a fix in pydantic-settings without a veadk-python release. The google-adk floor is open-ended at the top, which is the opposite policy: any 2.x release is allowed, and the explicit litellm and sqlalchemy declarations exist to keep that range working.

Licensing is Apache-2.0, declared both in the README badge and as a LICENSE file referenced by pyproject.toml. Apache-2.0 includes a patent grant and requires that you preserve notices and state changes. The repository also carries a .licenserc.yaml and a .gitleaks.toml, which suggests license headers and secret scanning are enforced in CI, but the README does not describe those workflows. This is a description of what the files declare, not legal advice; if you are redistributing a modified copy, read the LICENSE text yourself.

Editorial conclusion

Adopt veadk-python if your agents will run on Volcengine ARK and you want the AgentKit runtime, Studio UI and Feishu channel without assembling them yourself. Do not adopt it if your models live elsewhere and you have no ARK endpoint, because the default configuration path and the deployment tooling both assume Volcengine services. Before committing, verify that your Python version falls inside the declared range of 3.10 to below 3.14, and check whether the extras you need (database, eval, cli) are the ones you actually install, since the README treats them as separate sync targets rather than a single default.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. volcengine/veadk-python on GitHub