<p align="center">
<img src="assets/images/logo.png" alt="Volcengine Agent Development Kit Logo" width="50%">
</p>
# Volcengine Agent Development Kit
[](LICENSE)
[](https://deepwiki.com/volcengine/veadk-python)
An open-source kit for agent development, integrated the powerful capabilities of Volcengine.
For more details, see our [documents](https://volcengine.github.io/veadk-python/).
A [tutorial](https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) is available by Jupyter Notebook, or open it in [Google Colab](https://colab.research.google.com/github/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) directly.
---
***AgentKit 调研有礼！***
***5分钟聊聊您的真实使用体验，告诉我们哪里好用、哪里卡壳，审核通过可得 <ins>火山引擎 AgentKit</ins> ¥100 代金券【[填写问卷](https://bytedance.larkoffice.com/share/base/shrcnqGlkYuvmisvrmhFRZi9Kx7?prefill_%E6%9D%A5%E6%BA%90=GitHub&hide_%E6%9D%A5%E6%BA%90=1&hide_env=1&hide_region=1)】***
---
## Installation
### From PyPI
```python
pip install veadk-python
# install extensions
pip install veadk-python[extensions]
```
### Build from source
We use `uv` to build this project ([how-to-install-uv](https://docs.astral.sh/uv/getting-started/installation/)).
```bash
git clone ... # clone repo first
cd veadk-python
# create a virtual environment with python 3.12
uv venv --python 3.12
# only install necessary requirements
uv sync
# or, install extra requirements
# uv sync --extra database
# uv sync --extra eval
# uv sync --extra cli
# or, directly install all requirements
# uv sync --all-extras
# install veadk-python with editable mode
uv pip install -e .
```
## Configuration
We recommand you to create a `config.yaml` file in the root directory of your own project, `VeADK` is able to read it automatically. For running a minimal agent, you just need to set the following configs in your `config.yaml` file:
```yaml
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
```
You can refer to the [config instructions](https://volcengine.github.io/veadk-python/configuration/) for more details.
## Have a try
Enjoy a minimal agent from VeADK:
```python
from veadk import Agent
import asyncio
agent = Agent()
res = asyncio.run(agent.run("hello!"))
print(res)
```
## AgentKit application
Use the shared AgentKit application factory when your project needs AgentKit
APIs, VeADK's bundled Web UI, health checks, and agent-topology endpoints. This
keeps platform routes and lifecycle code out of your agent module:
```python
from veadk import Agent
from veadk.integrations.agentkit import create_agentkit_app
root_agent = Agent(name="customer_support")
app = create_agentkit_app(
root_agent,
enable_studio_tools=True,
)
```
Studio-owned dynamic tools and HTTP routes are separate Runtime capabilities.
Enable them explicitly with `enable_studio_tools=True` and
`enable_studio_routes=True`; both default to disabled.
See [`examples/generated_agentkit_project`](examples/generated_agentkit_project)
for a complete generated project.
The Agent Server metadata endpoint reports the root Agent's name, description,
model, sub-Agents, tools, skills, and mounted component summaries. Each Runtime
row in Studio has explicit connect and info actions; the info panel's tabs switch
between this live metadata and control-plane information without exposing prompts
or credentials. The same metadata advertises mounted smart-search sources, so
Studio can disable unavailable sources up front and query the Agent's web-search
tool, KnowledgeBase, or long-term memory without exposing component credentials.
Studio also manages user-owned Codex, OpenClaw, and Hermes AgentKit Sessions.
Users can create, reopen, inspect, and explicitly delete each Agent; leaving a
Codex conversation only disconnects it, while OpenClaw and Hermes expose their
main interface and Terminal through Studio.
When configuring skills, Studio can also browse account-scoped AgentKit Skill
Spaces and their paginated skill lists by region and project. These requests are
signed on the server, so browser clients never receive Volcengine credentials.
The Studio deployment flow lists Feishu, knowledge-base, short-/long-term
memory, and observability settings in their feature sections. Values entered
there are mirrored in the deployment environment-variable summary and converted
to VeADK runtime environment variables only when deploying; secrets are not
written to generated source or exported YAML. For multi-instance runtimes, use
a database-backed short-term memory store so sessions remain available across
instances.
When a cloud image build fails from the bundled Web UI, the deployment error
includes a credential-safe excerpt from the build log so dependency and
Dockerfile failures can be diagnosed directly.
When Studio connects to an AgentKit Runtime, users can rate completed answers
with like/dislike controls. Feedback is written server-side to per-Agent
`{agent_name}_good_case` and `{agent_name}_bad_case` evaluation sets, with
stable item keys so repeated clicks and rating changes remain idempotent.
## Feishu bot channel
VeADK now provides `veadk.extensions.FeishuChannelExtension` for bridging a Feishu bot with a `Runner`. It maps `union_id` to `user_id`, and `thread_id` / `chat_id` to `session_id`, so VeADK memory and tracing can work directly in Feishu conversations.
```python
from veadk import Agent, Runner
from veadk.extensions import FeishuChannelExtension
agent = Agent()
runner = Runner(agent=agent, app_name="feishu_demo")
channel = FeishuChannelExtension(runner=runner)
```
Configure credentials with `TOOL_FEISHU_CHANNEL_APP_ID` and `TOOL_FEISHU_CHANNEL_APP_SECRET`, or in `config.yaml` under `tool.feishu_channel`.
## Contribution
Before making your contribution to our repository, please install and config the `pre-commit` linter first.
```bash
pip install pre-commit
pre-commit install
```
Before commit or push your changes, please make sure the unittests are passed ,otherwise your PR will be rejected by CI/CD workflow. Running the unittests by:
```bash
pytest -n 16
```
## Security and privacy
This project takes security seriously.
For vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md)
## Contact with us
Join our discussion group by scanning the QR code below:
<p align="center">
<img src="assets/images/veadk_group_qrcode.jpg" alt="Volcengine Agent Development Kit Logo" width="40%">
</p>
## License
This project is licensed under the [Apache 2.0 License](./LICENSE).