Overview

Relevant source files

• docs/docs/agent/agent-to-agent.md
• docs/docs/configuration.md
• docs/docs/index.md
• docs/docs/memory/long-term-memory.md
• docs/docs/memory/short-term-memory.md
• docs/docs/quickstart.md
• docs/docs/tools/builtin.md
• docs/docs/veadk.md
• pyproject.toml
• veadk/knowledgebase/backends/base_backend.py
• veadk/knowledgebase/backends/utils.py
• veadk/knowledgebase/backends/vikingdb_knowledge_backend.py
• veadk/tools/builtin_tools/vod.py
• veadk/version.py

VeADK (Volcengine Agent Development Kit) is a comprehensive Python framework for developing, deploying, and monitoring AI agents on the Volcengine platform. It provides an opinionated architecture built on top of Google ADK that integrates deeply with Volcengine's cloud services, offering developers a complete toolkit for building enterprise-grade agent applications with built-in observability, knowledge management, and deployment capabilities.

This page provides a high-level introduction to VeADK's architecture, core components, and design philosophy. For detailed implementation guides, see:

• Installation and first agent creation: Quick Start Guide
• Core framework components: Core Framework
• Cloud deployment: Cloud Deployment
• Development workflow and CLI tools: Development Workflow

---

What VeADK Provides

VeADK addresses the complete agent development lifecycle through five integrated subsystems:

Subsystem	Purpose	Key Components
Development Tools	Project scaffolding, local testing, deployment automation	veadk CLI, cookiecutter templates, FastAPI server
Core Agent Runtime	LLM orchestration, tool execution, conversation management	Agent, Runner, instruction management
Memory & Knowledge	Context persistence and retrieval	ShortTermMemory, LongTermMemory, KnowledgeBase
Tool Ecosystem	Extensible capabilities for agents	Built-in tools, Skills system, MCP integration
Cloud Infrastructure	Production deployment and scaling	CloudAgentEngine, VeFaaS, APIGateway
Observability	Monitoring and debugging	OpentelemetryTracer, multiple exporters

Sources: pyproject.toml1-101 docs/docs/index.md38-146 docs/docs/veadk.md1-111

---

Design Philosophy

Built on Google ADK

VeADK extends Google ADK rather than replacing it, maintaining full compatibility with the ADK ecosystem while adding Volcengine-specific integrations. The framework inherits ADK's session management, event streaming, and agent composition patterns.

Sources: pyproject.toml16-19 docs/docs/index.md111-114

Volcengine-First Integration

Unlike generic agent frameworks, VeADK treats Volcengine services as first-class citizens, providing:

• Automatic credential resolution from VeFaaS IAM roles (no hardcoded keys)
• Native TOS integration for file uploads in Runner media handling
• Pre-configured endpoints for Ark, VikingDB, APMPlus, and other services
• One-command deployment to VeFaaS with API Gateway provisioning

Sources: docs/docs/index.md148-180 docs/docs/configuration.md1-164

Modular Backend Architecture

VeADK abstracts storage and services through pluggable backends, allowing developers to start with local/in-memory implementations and swap to production backends without code changes:

Component	Development Backend	Production Backends
Short-term Memory	local (in-memory)	mysql, postgresql, sqlite
Long-term Memory	local (in-memory)	viking, mem0, opensearch, redis
Knowledge Base	local (in-memory)	viking, opensearch, redis, tosvector

Sources: docs/docs/memory/short-term-memory.md152-162 docs/docs/memory/long-term-memory.md18-30

---

Core Architecture

Component Mapping to Code

The following diagram maps VeADK's conceptual architecture to actual Python classes and modules:

Sources: pyproject.toml47-49 Diagram 1 from system architecture overview, Diagram 2 from data flow overview

Project Structure

A typical VeADK project generated by veadk create has the following structure:

your_project/
├── __init__.py              # Module exports
├── .env                     # Environment variables (MODEL_AGENT_API_KEY, etc.)
├── agent.py                 # Agent definition with root_agent instance
├── config.yaml              # Optional: structured configuration
└── deploy.py               # Generated deployment script (CloudAgentEngine)

The framework itself is organized as:

veadk/
├── agent/                   # Agent and Runner implementations
├── memory/                  # ShortTermMemory, LongTermMemory
├── knowledgebase/          # KnowledgeBase and backends
├── tools/                  
│   ├── builtin_tools/      # web_search, image_generate, etc.
│   └── skills/             # Skills system
├── integrations/
│   ├── ve_faas/            # VeFaaS deployment
│   ├── ve_api_gateway/     # API Gateway management
│   └── ve_tos/             # TOS object storage
├── tracing/                # OpenTelemetry instrumentation
├── cli/                    # CLI commands
├── auth/                   # Authentication and credentials
└── configs/                # Pydantic configuration models

Sources: docs/docs/quickstart.md99-107 pyproject.toml87-95

---

Key Components

Agent and Runner

The Agent class is the primary interface for defining agent behavior, while Runner orchestrates execution:

Key code references:

• Agent initialization: veadk/agent/ (extends google.adk.agent.llmagent.LLMAgent)
• Runner.run() method: veadk/agent/ (wraps google.adk.runner)
• Session creation: uses google.adk.session.SessionService
• Auto-save feature: Agent(auto_save_session=True, long_term_memory=...)

Sources: Diagram 2 from system architecture overview, docs/docs/memory/long-term-memory.md424-442

Memory System

VeADK implements a two-tier memory architecture:

Short-term Memory (Session Context):

• Managed by ShortTermMemory wrapper around google.adk.session.SessionService
• Stores conversation events within a single session
• Backends: local, mysql, postgresql, sqlite
• Supports event compaction via LlmEventSummarizer

Long-term Memory (Cross-session Persistence):

• Implemented in veadk.memory.LongTermMemory
• Stores user-specific knowledge across sessions
• Backends: viking (VikingDB), mem0, opensearch, redis
• Searchable via semantic vector search
• Auto-save: Agent.auto_save_session triggers add_session_to_memory()

Sources: docs/docs/memory/short-term-memory.md1-269 docs/docs/memory/long-term-memory.md1-442

Knowledge Base (RAG)

The KnowledgeBase class provides retrieval-augmented generation capabilities:

Backend implementations:

• VikingDBKnowledgeBackend: TOS upload + VikingDB vector storage (veadk/knowledgebase/backends/vikingdb_knowledge_backend.py67-657)
• OpensearchKnowledgeBackend: OpenSearch integration
• RedisKnowledgeBackend: Redis with Redisearch
• TOSVectorKnowledgeBackend: TOS-based vector storage
• InMemoryKnowledgeBackend: Local development

Sources: veadk/knowledgebase/backends/vikingdb_knowledge_backend.py1-657 veadk/knowledgebase/backends/base_backend.py1-73

Built-in Tools

VeADK provides production-ready tools integrated with Volcengine services:

Tool	Purpose	Integration	Code Path
web_search	Web search via Volcengine API	Ark Fusion Search	builtin_tools/web_search.py
vesearch	Agent-based search	VeSearch Agent	builtin_tools/vesearch.py
image_generate	Text-to-image generation	Ark Seedream models	builtin_tools/image_generate.py
video_generate	Text-to-video generation	Ark Seedance models	builtin_tools/video_generate.py
run_code	Code execution sandbox	AgentKit Tools	builtin_tools/run_code.py
lark	Feishu/Lark integration	Lark MCP Server	builtin_tools/lark.py
las	Data lake operations	LAS MCP Server	builtin_tools/las.py
vod_tools	Video editing	VOD MCP Server	builtin_tools/vod.py

Example tool usage pattern:

Sources: docs/docs/tools/builtin.md1-693 veadk/tools/builtin_tools/vod.py1-72

Skills System

VeADK supports three execution modes for skills:

1. Local execution: Skills run in the same process
2. Skills Sandbox: Remote execution via cloud sandbox
3. AIO Sandbox: Integrated browser/terminal/code environment

Skills are defined in SKILL.md format and loaded from:

• Local directories: agent.load_skills("./my_skills")
• Cloud skill spaces: Environment variable SKILL_SPACE_ID
• TOS storage: Environment variable TOS_SKILLS_DIR

Sources: Referenced in Diagram 1 system architecture overview, tool ecosystem section

---

Volcengine Service Integration

Credential Management

VeADK implements a three-tier credential resolution hierarchy:

The get_credential_from_vefaas_iam() function automatically retrieves temporary credentials when running in VeFaaS, eliminating the need for hardcoded secrets in deployed agents.

Sources: veadk/knowledgebase/backends/vikingdb_knowledge_backend.py601-619 authentication and security documentation references

Cloud Deployment Pipeline

The CloudAgentEngine orchestrates the complete deployment workflow:

Key deployment components:

• CloudAgentEngine.deploy(): Main orchestration (veadk/integrations/ve_faas/cloud_agent_engine.py)
• VeFaaS.deploy(): Function deployment with code upload (veadk/integrations/ve_faas/ve_faas.py)
• VeFaaS.deploy_image(): Container-based deployment
• APIGateway: Resource topology management (Gateway → Service → Upstream → Route)
• VeTOS: Document/file storage with signed URLs (veadk/integrations/ve_tos/ve_tos.py)

Sources: Diagram 3 from system architecture overview, cloud deployment section

Observability Stack

VeADK implements OpenTelemetry-based observability with multiple export targets:

Configuration via environment variables:

• APMPlus: OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT, OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY
• CozeLoop: OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT, OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY
• TLS: OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT, OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME

Sources: Diagram 5 from system architecture overview, docs/docs/configuration.md96-114

---

Multi-Agent Communication (A2A Protocol)

VeADK supports Agent-to-Agent communication via the A2A protocol:

Server Side (Exposing an Agent)

Client Side (Consuming a Remote Agent)

Authentication methods:

• Header: Authorization: Bearer {token}
• Querystring: ?token={token} (default for VeFaaS deployments)

Sources: docs/docs/agent/agent-to-agent.md1-272

---

Configuration System

VeADK uses a three-tier configuration hierarchy (highest to lowest precedence):

1. System environment variables: Pre-set in execution environment
2. .env file: Loaded from project root
3. config.yaml: Structured configuration file

Common configuration patterns:

Default constants (when not specified):

• DEFAULT_MODEL_AGENT_NAME: doubao-seed-1-6-251015
• DEFAULT_MODEL_AGENT_API_BASE: https://ark.cn-beijing.volces.com/api/v1/
• DEFAULT_TOS_BUCKET_NAME: veadk-default-bucket

Sources: docs/docs/configuration.md1-164 veadk/version.py1-16

---

Getting Started

The quickest path to a working agent:

For production deployment:

The generated deploy.py uses CloudAgentEngine to orchestrate:

1. Local validation with _try_launch_fastapi_server()
2. VeFaaS function creation (code or image deployment)
3. API Gateway resource provisioning
4. Authentication setup (OAuth2/API-Key)
5. Endpoint URL generation with credentials

For detailed guides:

• First agent tutorial: Quick Start Guide
• Configuration reference: Configuration System
• Agent API documentation: Agent System
• Deployment options: Cloud Deployment

Sources: docs/docs/quickstart.md1-145 pyproject.toml1-101