VeADK Python

https://volcengine.github.io/veadk-python/
Admin
VeADK Python is Volcengine's Agent Development Kit providing a cloud-native solution for building,...
Tokens:174,051
Snippets:980
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Veadk Project Initialization Prompts

Source: https://volcengine.github.io/veadk-python/llms-full

This is an example of the interactive prompts shown when running `veadk init`. It guides the user through setting up project names, API Gateway details, and choosing a deployment mode.

```bash
$ veadk init
Welcome use VeADK to create your project. We will generate a `weather-reporter` application for you.
Local directory name [veadk-cloud-proj]: 
Volcengine FaaS application name [veadk-cloud-agent]: 
Volcengine API Gateway instance name []: 
Volcengine API Gateway service name []: 
Volcengine API Gateway upstream name []: 
Choose a deploy mode:
  1. A2A/MCP Server
  2. VeADK Web / Google ADK Web
Enter your choice (1, 2): 1
Template project has been generated at .../veadk-cloud-proj
Edit .../veadk-cloud-proj/src to define your agents
Edit .../veadk-cloud-proj/deploy.py to define your deployment attributes
Run python `deploy.py` for deployment on Volcengine FaaS platform.
```

--------------------------------

### Run VeADK Web Interface

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Starts the VeADK web interface for interacting with your agent. This command launches a web server that allows you to communicate with the agent through a browser.

```bash
veadk web
```

--------------------------------

### Installation and Setup

Source: https://volcengine.github.io/veadk-python/agent/responses-api

Instructions on how to install the required libraries and enable the Responses API in your veadk-python agent.

```APIDOC
## Installation and Setup

### Requirements
- `veadk-python` version
- `google-adk>=1.21.0`

### Installation
```bash
pip install "google-adk>=1.21.0"
```

### Enabling Responses API
To enable the Responses API, set `enable_responses=True` when initializing the `Agent`.

```python
from veadk import Agent

root_agent = Agent(
    enable_responses=True, # Enable Responses API
)
```
```

--------------------------------

### Install VeADK from Source

Source: https://volcengine.github.io/veadk-python/llms-full

Installs VeADK from the local source code using `uv pip install .`. It also shows how to install in editable mode.

```bash
uv pip install .
# Or install in local editable mode
# uv pip install -e .
```

--------------------------------

### Veadk Project Initialization Prompts

Source: https://volcengine.github.io/veadk-python/deploy/deploy-vefaas_q=

Example interactive prompts for the `veadk init` command. It guides the user through setting up project names, API Gateway configurations, and choosing a deployment mode (A2A/MCP Server or VeADK Web).

```bash
$ veadk init
Welcome use VeADK to create your project. We will generate a `weather-reporter` application for you.
Local directory name [veadk-cloud-proj]: 
Volcengine FaaS application name [veadk-cloud-agent]: 
Volcengine API Gateway instance name []: 
Volcengine API Gateway service name []: 
Volcengine API Gateway upstream name []: 
Choose a deploy mode:
  1. A2A/MCP Server
  2. VeADK Web / Google ADK Web
Enter your choice (1, 2): 1
Template project has been generated at .../veadk-cloud-proj
Edit .../veadk-cloud-proj/src to define your agents
Edit .../veadk-cloud-proj/deploy.py to define your deployment attributes
Run python `deploy.py` for deployment on Volcengine FaaS platform.

```

--------------------------------

### VeADK Pipeline Command Example

Source: https://volcengine.github.io/veadk-python/cli_q=

This example demonstrates how to run the VeADK pipeline command with necessary GitHub and Volcengine parameters. It requires a GitHub repository URL, branch, token, and Volcengine access keys.

```bash
veadk pipeline \
  --github-url https://github.com/your-user/your-repo \
  --github-branch main \
  --github-token YOUR_GITHUB_TOKEN \
  --volcengine-access-key YOUR_AK \
  --volcengine-secret-key YOUR_SK \
  --region cn-beijing

```

--------------------------------

### Start VeADK Agent Lightning Training Server

Source: https://volcengine.github.io/veadk-python/deploy/optimization_q=

Starts the training server for reinforcement learning optimization using VeADK and Agent Lightning. This command is executed in a separate terminal to manage the training process.

```bash
cd veadk_rl_lightning_project
bash train.sh

```

--------------------------------

### Run VeADK Agent Web Interface

Source: https://volcengine.github.io/veadk-python/quickstart

Starts the VeADK agent's web interface, allowing users to interact with the agent through a browser. This command can be customized with options for host, port, and log level.

```shell
veadk web

# Example with custom configuration:
# veadk web --host 0.0.0.0 --port 8000 --log_level DEBUG
```

--------------------------------

### Start Agent Lightning Training Server

Source: https://volcengine.github.io/veadk-python/deploy/optimization

Starts the training server for a VeADK project using Agent Lightning. This script configures and launches the training server.

```bash
cd veadk_rl_lightning_project
bash train.sh
```

--------------------------------

### Install VeADK Python with Pip

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Installs the VeADK Python package directly from PyPI using the standard 'pip' command. This is a straightforward method for installing the latest version.

```bash
pip install veadk-python
```

--------------------------------

### Verify VeADK Python Installation

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Checks if the VeADK Python package has been installed successfully by running the 'veadk --version' command. This command should output the installed version of the VeADK tool.

```bash
veadk --version
```

--------------------------------

### Configure and Create Veadk Agent (Go)

Source: https://volcengine.github.io/veadk-python/llms-full

Sets up the configuration for a Veadk Agent, including its LLM agent configuration (name, description, instructions, tools) and knowledge base integration. It then creates a new Veadk Agent instance.

```go
import (
    "fmt"
    "log"
    "os"
    "context"
    "github.com/veadk/veadk-go/pkg/agent"
    "github.com/veadk/veadk-go/pkg/agent/full"
    "github.com/veadk/veadk-go/pkg/agent/llmagent"
    "github.com/veadk/veadk-go/pkg/agent/veagent"
    "github.com/veadk/veadk-go/pkg/launcher"
    "github.com/veadk/veadk-go/pkg/session"
    "github.com/veadk/veadk-go/pkg/tool"
)

// Assuming knowledgeBase and calculateDateDifferenceTool are initialized and available
// var knowledgeBase *knowledgebase.KnowledgeBase
// func CalculateDateDifferenceTool() (tool.Tool, error) { ... }

// func main() {
//     ctx := context.Background()
//     var err error

//     calculateDateDifferenceTool, err := CalculateDateDifferenceTool()
//     if err != nil {
//         log.Fatal("CalculateDateDifferenceTool error: ", err)
//         return
//     }

//     cfg := veagent.Config{
//         Config: llmagent.Config{
//             Name:        "chat_agent",
//             Description: "你是一个优秀的助手，你可以和用户进行对话。",
//             Instruction: `你是一个优秀的助手。当被提问时，请遵循以下步骤：\n1. 首先，根据你的内部知识，生成一个初步的回答。\n2. 然后，查询你的知识库，寻找与问题相关的信息来验证或丰富你的答案。\n3. 最后，结合你的内部知识和知识库中的信息，给出一个全面、准确的最终答案。`,
//             Tools:       []tool.Tool{calculateDateDifferenceTool},
//         },
//         ModelName:     "doubao-seed-1-6-250615",
//         KnowledgeBase: knowledgeBase, // Assuming knowledgeBase is initialized
//     }

//     veAgent, err := veagent.New(&cfg)
//     if err != nil {
//         fmt.Printf("NewLLMAgent failed: %v", err)
//         return
//     }

//     config := &launcher.Config{
//         AgentLoader:    agent.NewSingleLoader(veAgent),
//         SessionService: session.InMemoryService(),
//     }

//     l := full.NewLauncher()
//     if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
//         log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
//     }
// }
```

--------------------------------

### Install VeADK Python with UV

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Installs the VeADK Python package using the 'uv' package manager. It first creates a virtual environment and then installs the package within that environment. This method is recommended for managing dependencies.

```bash
uv venv --python 3.10
source .venv/bin/activate
uv pip install veadk-python
```

--------------------------------

### Build VeADK Python from Source with UV

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Builds and installs VeADK Python from its source code using 'uv'. It involves setting up a Python 3.10+ virtual environment, activating it, and then installing the package in editable mode.

```bash
# Select Python 3.10 or later version
uv venv --python 3.10

# Activate uv virtual environment
# Linux/macOS:
source .venv/bin/activate

# Windows CMD:
.venv\Scripts\activate.bat

# Windows PowerShell:
.venv\Scripts\activate.ps1

# Install VeADK
uv pip install .
# Or install in local editable mode
# uv pip install -e .
```

--------------------------------

### Setup uv Environment for VeADK Build

Source: https://volcengine.github.io/veadk-python/llms-full

Sets up a `uv` virtual environment for building the VeADK project, selecting Python 3.10 or higher.

```bash
# Select version 3.10 and above
uv venv --python 3.10

# Activate uv virtual environment
source .venv/bin/activate
```

--------------------------------

### Install VeADK Go Package

Source: https://volcengine.github.io/veadk-python/index

Installs the Volcengine Agent Development Kit (VeADK) for Go using the go get command.

```go
go get github.com/volcengine/veadk-go

```

--------------------------------

### Initialize Viking Knowledge Backend (Go)

Source: https://volcengine.github.io/veadk-python/llms-full

Initializes a Viking Knowledge Backend with a specified index name, creation policy, and TOS configuration. It includes error handling for the initialization process.

```go
import (
    "log"
    "github.com/veadk/veadk-go/pkg/backend/ve_tos"
    "github.com/veadk/veadk-go/pkg/knowledgebase"
)

// Assuming NewVikingKnowledgeBackend and knowledgeBase are defined elsewhere
// For demonstration, we'll use placeholders

// Placeholder for ve_tos.Config
// type Config struct { Bucket string }

// Placeholder for NewVikingKnowledgeBackend
// func NewVikingKnowledgeBackend(options ...interface{}) (*knowledgebase.KnowledgeBase, error) {
//     // ... implementation ...
//     return &knowledgebase.KnowledgeBase{}, nil
// }

// Example usage:
// knowledgeBase, err := NewVikingKnowledgeBackend(
//     knowledgebase.WithIndex("veadk_go_test_kg"),
//     knowledgebase.WithCreateIfNotExist(true),
//     knowledgebase.WithTosConfig(&ve_tos.Config{
//         Bucket: "veadk-go-bucket",
//     }),
// )
// if err != nil {
//     log.Fatal("NewVikingKnowledgeBackend error: ", err)
// }
```

--------------------------------

### Start VeADK Web UI

Source: https://volcengine.github.io/veadk-python/deploy/evaluation

Starts the VeADK web server for interactive agent evaluation and dataset generation. Ensure VeADK is installed and your virtual environment is activated.

```bash
veadk web

```

--------------------------------

### Start Veadk Web UI

Source: https://volcengine.github.io/veadk-python/llms-full

This section describes how to launch the interactive web interface for veadk, which allows for agent evaluation, dataset generation, and detailed inspection of agent behavior.

```APIDOC
## Start Veadk Web UI

### Description
Launches the interactive web interface for veadk to evaluate agents, generate datasets, and inspect agent behavior.

### Method
CLI Command

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
veadk web
```

### Response
N/A

*Note: Ensure veadk is installed and your virtual environment is activated if the command is not found.*
```

--------------------------------

### Configure Video Generation Tool (Go)

Source: https://volcengine.github.io/veadk-python/llms-full

This Go code snippet shows how to set up and configure the video generation tool within the veadk-go framework. It involves creating a `VideoGenerateTool` instance with specific model configurations and API keys, and integrating it into an agent.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/a2aproject/a2a-go/a2asrv"
    "github.com/google/uuid"
    veagent "github.com/volcengine/veadk-go/agent/llmagent"
    "github.com/volcengine/veadk-go/common"
    "github.com/volcengine/veadk-go/tool/builtin_tools"
    "google.golang.org/adk/agent"
    "google.golang.org/adk/artifact"
    "google.golang.org/adk/cmd/launcher"
    "google.golang.org/adk/cmd/launcher/full"
    "google.golang.org/adk/model"
    "google.golang.org/adk/session"
    "google.golang.org/adk/tool"
)

func main() {
    ctx := context.Background()
    cfg := &veagent.Config{
        ModelName:    common.DEFAULT_MODEL_AGENT_NAME,
        ModelAPIBase: common.DEFAULT_MODEL_AGENT_API_BASE,
        ModelAPIKey:  os.Getenv(common.MODEL_AGENT_API_KEY),
    }
    videoGenerate, err := builtin_tools.NewVideoGenerateTool(&builtin_tools.VideoGenerateConfig{
        ModelName: common.DEFAULT_MODEL_VIDEO_NAME,
        BaseURL:   common.DEFAULT_MODEL_VIDEO_API_BASE,
        APIKey:    os.Getenv(common.MODEL_VIDEO_API_KEY),
    })
    if err != nil {
        fmt.Printf("NewLLMAgent failed: %v", err)
        return
    }

    cfg.Tools = []tool.Tool{videoGenerate}

    sessionService := session.InMemoryService()
    rootAgent, err := veagent.New(cfg)

    if err != nil {
        log.Fatalf("Failed to create agent: %v", err)
    }

    agentLoader, err := agent.NewMultiLoader(
        rootAgent,
    )
    if err != nil {
        log.Fatalf("Failed to create agent loader: %v", err)
    }

    artifactservice := artifact.InMemoryService()
    config := &launcher.Config{
        ArtifactService: artifactservice,
        SessionService:  sessionService,
        AgentLoader:     agentLoader,
    }

    l := full.NewLauncher()
    if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

```

--------------------------------

### Responses API - Setup and Configuration

Source: https://volcengine.github.io/veadk-python/agent/responses-api_q=

This section details the requirements and setup for using the Responses API, specifically within the `veadk-python` environment. It includes installation instructions for necessary packages and how to enable the Responses API in your agent configuration.

```APIDOC
## Responses API Setup

### Requirements
- **`veadk-python` version**: The Responses API is currently only supported in the `veadk-python` version.
- **`google-adk` version**: Requires `google-adk>=1.21.0`.

### Installation
Ensure your environment meets the requirements by installing the necessary packages:

```bash
pip install "google-adk>=1.21.0"
```

Or using `uv`:

```bash
uv pip install "google-adk>=1.21.0"
```

### Enabling Responses API
To activate the Responses API, set the `enable_responses` parameter to `True` when initializing the `Agent`:

```python
from veadk import Agent

root_agent = Agent(
    enable_responses=True, # Enable Responses API
)
```
```

--------------------------------

### VeADK Agent Project Structure Example

Source: https://volcengine.github.io/veadk-python/cli_q=

Shows the directory structure created for a new VeADK agent project using the 'veadk create' command. It includes essential files like the .env configuration file, package initialization, and the main agent definition file.

```bash
location-agent/
├── .env          # 包含 API key 的环境配置
├── __init__.py   # Python 包初始化文件
└── agent.py      # 主要智能体定义文件

```

--------------------------------

### Example: Querying User API with API Key Authentication

Source: https://volcengine.github.io/veadk-python/auth/api-key-outbound

This example illustrates a complete Veadk agent setup for querying a user API using API Key authentication. It defines a tool to fetch user data and integrates it into an agent and runner. Requires 'asyncio', 'veadk', 'aiohttp', and 'veadk.integrations.ve_identity'.

```python
import asyncio
from veadk import Agent, Runner
from veadk.integrations.ve_identity import VeIdentityFunctionTool, api_key_auth
import aiohttp

async def query_api(api_key: str, user_id: str):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://api.example.com/users/{user_id}"
    async with aiohttp.ClientSession() as session:
        async with session.get(url, headers=headers) as resp:
            return await resp.json()

tool = VeIdentityFunctionTool(
    func=query_api,
    auth_config=api_key_auth(provider_name="user-api"),
    into="api_key",
)

agent = Agent(tools=[tool])
runner = Runner(agent=agent)
asyncio.run(runner.run(messages="查询用户 123"))
```

--------------------------------

### Clone VeADK Python Repository

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Clones the VeADK Python source code from GitHub to your local machine. This is the first step for building the project from source or contributing to its development.

```bash
git clone https://github.com/volcengine/veadk-python.git
cd veadk-python
```

--------------------------------

### Initialize and Add Data to OpenSearch Knowledge Base (Python)

Source: https://volcengine.github.io/veadk-python/llms-full

Initializes a KnowledgeBase instance using OpenSearch as the backend and adds data from a specified file. Ensure the 'tmp/demo.txt' file exists and contains the relevant text data.

```python
from veadk.knowledgebase import KnowledgeBase

APP_NAME = "opensearch_demo"

kb = KnowledgeBase(
    backend="opensearch",  # Set to opensearch
    app_name=APP_NAME,
)

# The file path has been corrected to tmp/demo.txt
kb.add_from_files(["tmp/demo.txt"])
```

--------------------------------

### Configure Model API Key in .env

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Shows how to configure the model API key within the .env file for the VeADK agent project. The MODEL_AGENT_API_KEY variable needs to be set to your obtained API key.

```dotenv
MODEL_AGENT_API_KEY = ...
```

--------------------------------

### VeADK Project Structure Example

Source: https://volcengine.github.io/veadk-python/cli_q=

Illustrates the typical directory structure generated after initializing a VeADK project using the 'veadk init' command with the default 'template'. It shows the organization of source code, configuration files, and deployment scripts.

```bash
weather-reporter/
├────src                    # 智能体项目源代码目录
│   ├────weather_report     # 天气预报智能体项目目录
│   │    ├──────agent.py    # 主要智能体定义文件
│   │    └──────__init__.py # 智能体项目包初始化文件
│   ├── agent.py            # 主要智能体定义文件
│   ├── app.py              # 主要 Web 应用定义文件
│   ├── requirements.txt    # 项目依赖文件
│   ├── run.sh              # 项目运行脚本
│   └── __init__.py         # 智能体项目包初始化文件
├────clean.py               # 清理脚本，用于删除项目生成的临时文件
├────deploy.py              # 部署脚本，用于将项目部署到火山引擎 FaaS 平台
└────__init__.py            # 智能体项目包初始化文件

```

--------------------------------

### VeADK Agent Project Structure

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Illustrates the file structure of a newly created VeADK agent project. It includes essential files like __init__.py, .env for environment variables, and agent.py for agent definition.

```text
your_project
├── __init__.py # Module export file
├── .env        # Environment variables file, where you need to provide your model API Key
└── agent.py    # Agent definition file
```

--------------------------------

### Initialize and Run Agent

Source: https://volcengine.github.io/veadk-python/llms-full

This Python code initializes an Agent with a name, model, description, instructions, a knowledge base, and a list of tools. It then sets up a Runner with the agent and application name. Finally, it enters an interactive loop to take user input, run the agent with the input, and print the agent's completion, allowing the user to exit with 'exit' or 'quit'.

```python
import asyncio
import uuid
from veadk.agent import Agent
from veadk.runner import Runner

# Assuming kb, calculate_date_difference, and web_search are defined as above
# Assuming APP_NAME is defined as above

agent = Agent(
    name="chat_agent",
    model_name="doubao-seed-1-6-250615",
    description="你是一个优秀的助手，你可以和用户进行对话。",
    instruction="""
你是一个优秀的助手。当被提问时，请遵循以下步骤：
1. 首先，根据你的内部知识，生成一个初步的回答。
2. 然后，查询你的知识库，寻找与问题相关的信息来验证或丰富你的答案。
3. 如果知识库信息不足，或用户问题涉及实时、或知识库外的知识，请使用 `web_search` 工具进行网络搜索。
4. 最后，结合你的内部知识、知识库信息以及网络搜索结果，给出一个全面、准确的最终答案。""",
    knowledgebase=kb,
    tools=[calculate_date_difference, web_search],
)

runner = Runner(
    agent,
    app_name=APP_NAME,
)

if __name__ == "__main__":
    session_id = uuid.uuid4().hex
    print("欢迎使用交互式问答 Agent。输入 'exit' 或 'quit' 来结束对话。")
    while True:
        try:
            message = input("您: ")
            if message.lower() in ["exit", "quit"]:
                print("再见!")
                break

            completion = asyncio.run(
                runner.run(
                    messages=message,
                    session_id=session_id,
                )
            )
            print(f"Agent: {completion}")
        except KeyboardInterrupt:
            print("\n再见!")
            break
```

--------------------------------

### Define Root Agent in agent.py

Source: https://volcengine.github.io/veadk-python/quickstart_q=

Defines the main 'root_agent' in the agent.py file using the VeADK Agent class. It includes parameters for the agent's name, description, system instructions, and the model name to be used.

```python
from veadk import Agent # Import Agent module

root_agent = Agent(
    name="root_agent",  # Agent name
    description="A helpful assistant for user questions.",  # Agent description
    instruction="Answer user questions to the best of your knowledge",  # Agent system prompt
    model_name="doubao-seed-1-6-251015",    # Model name
)
```
Tokens:
Raw