### Install and Run Veadk-Python Example

Source: https://github.com/volcengine/veadk-python/blob/main/examples/02_custom_tools/README.md

Instructions to install the Veadk-Python library, set up environment variables, and run the example script.

```bash
pip install veadk-python
cp .env.example .env   # then set MODEL_AGENT_API_KEY
python main.py
```

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

### Run Best-Practice Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/optimization.en.mdx

This sequence demonstrates running an optimized VeADK arithmetic agent. It involves starting the client, restarting the Ray cluster, and then starting the training server in separate terminals.

```bash
python demo_calculate_agent.py
```

```bash
bash restart_ray.sh
```

```bash
bash train.sh
```

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

### Install Veadk Python and Configure Environment

Source: https://github.com/volcengine/veadk-python/blob/main/examples/11_tracing/README.md

Install the necessary package and copy the example environment file. Set API keys and observability flags in the .env file.

```bash
pip install veadk-python
cp .env.example .env   # set MODEL_AGENT_API_KEY (+ AK/SK and ENABLE_* to export)
python main.py
```

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

### Quick Start: Minimal Harness Setup with Compactor

Source: https://github.com/volcengine/veadk-python/blob/main/docs/extensions/harness/README.md

Start with only the compactor component for the smallest measurable change in your agent's behavior.

```python
plugins = build_harness_plugins(components=["compactor"])
```

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

### Run an Example

Source: https://github.com/volcengine/veadk-python/blob/main/examples/README.md

Execute a VeADK example script using Python.

```bash
python main.py
```

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

### Install and Configure pre-commit

Source: https://github.com/volcengine/veadk-python/blob/main/README.md

Install the pre-commit linter and configure it for the repository. This should be done before making contributions.

```bash
pip install pre-commit
pre-commit install
```

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

### Example: Calculate Agent Optimization

Source: https://github.com/volcengine/veadk-python/blob/main/veadk/cli/templates/rl/lightning/README.md

This section outlines a best practice case involving optimizing a VeADK arithmetic agent using reinforcement learning. It details the sequence of commands to run the client, restart the Ray cluster, and start the training server.

```bash
python demo_calculate_agent.py
```

```bash
bash restart_ray.sh
```

```bash
bash train.sh
```

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

### Launch Veadk Web UI

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/evaluation.en.mdx

Starts the veadk web server for interactive agent evaluation and evalset generation. Ensure dependencies are installed and the virtual environment is activated.

```bash
veadk web
```

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

### Configure Environment and Run Example

Source: https://github.com/volcengine/veadk-python/blob/main/examples/09_long_term_memory/README.md

Copy the example environment file and set the `MODEL_AGENT_API_KEY` and embedding model configuration. Then, run the main Python script to execute the long-term memory demo.

```bash
cp .env.example .env   # set MODEL_AGENT_API_KEY (+ embedding config)
python main.py
```

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

### Start Agent Client

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/optimization.en.mdx

Navigate to the project directory and execute this command to start the agent client. This script defines the agent's rollout logic and reward rules.

```bash
cd veadk_rl_lightning_project
python veadk_agent.py
```

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

### MySQL Configuration Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/memory/short-term/mysql.en.mdx

Example `config.yaml` snippet for setting up MySQL connection details. Never hard-code passwords; use environment variables instead.

```yaml
database:
  mysql:
    host:       # host or IP
    user:
    password:
    database:
    charset: utf8
```

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

### Install veadk-python with extensions

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/memory/long-term/opensearch.en.mdx

Install the veadk-python library with the necessary extensions to use the OpenSearch backend.

```bash
pip install "veadk-python[extensions]"
```

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

### Quick Start with VeADK Runner

Source: https://github.com/volcengine/veadk-python/blob/main/veadk/extensions/harness/README.md

Initialize an Agent and a Runner with the VeADK Harness plugins for context preparation, compaction, and response verification.

```python
from veadk.extensions.harness.plugins import build_harness_plugins
from veadk import Agent, Runner

agent = Agent(name="research_agent")
runner = Runner(
    agent=agent,
    app_name="research",
    plugins=build_harness_plugins(
        components=["invocation_context", "compactor", "response_verification"],
        profile="research",
    ),
)
```

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

### Install Cozeloop SDK

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/prompt.en.mdx

Install the Cozeloop Python SDK using pip. This is a prerequisite for using the CozeloopPromptManager.

```bash
pip install cozeloop
```

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

### Create a Minimal VeADK Agent

Source: https://github.com/volcengine/veadk-python/blob/main/README.md

Instantiate a basic agent and run a simple prompt. Ensure the 'veadk' library is installed.

```python
from veadk import Agent
import asyncio

agent = Agent()

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

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

### Configure Environment Variables

Source: https://github.com/volcengine/veadk-python/blob/main/examples/codex_runtime_on_agentkit/README.md

Copy the example environment file and edit it with your API keys. This step is crucial for authentication and access.

```bash
cd examples/codex_runtime_on_agentkit
cp .env.example .env
#edit .env: MODEL_AGENT_API_KEY + VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY
```

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

### Start Training Server

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/optimization.en.mdx

Execute this command to start the training server after restarting the Ray cluster. This script defines the training-related parameters.

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

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

### Install for Local Development

Source: https://github.com/volcengine/veadk-python/blob/main/veadk/extensions/harness/README.md

Install the VeADK Harness extension for local development within the repository. Use the '[harness]' extra for Headroom support.

```bash
pip install .
```

```bash
pip install ".[harness]"
```

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

### Install veadk-python from Source

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/installation.en.mdx

Install the veadk-python library directly from the main branch of the GitHub repository for a preview release, or from a specific branch.

```bash
pip install git+https://github.com/volcengine/veadk-python.git@main
```

```bash
pip install git+https://github.com/volcengine/veadk-python.git@[branch-name]
```

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

### Run VeADK Frontend

Source: https://github.com/volcengine/veadk-python/blob/main/frontend/README.md

Serve the VeADK web UI and ADK API. Point to your agent directories or use the default examples.

```bash
cd path/to/your/agents     # parent dir containing agent_a/, agent_b/, ...
veadk frontend             # serves UI + ADK API on http://127.0.0.1:8000
# or point elsewhere:  veadk frontend --agents-dir ./examples
```

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

### Install and Configure VeADK Python

Source: https://github.com/volcengine/veadk-python/blob/main/examples/04_web_search/README.md

Install the `veadk-python` package and configure your environment variables, including API keys for the model and Volcengine.

```bash
pip install veadk-python
cp .env.example .env   # set MODEL_AGENT_API_KEY + VOLCENGINE_ACCESS_KEY/SECRET_KEY
python main.py
```

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

### Run Development Server

Source: https://github.com/volcengine/veadk-python/blob/main/docs/README.md

Commands to start the development server for the Next.js application using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

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

### LAS Agent Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/builtin-mcp.en.mdx

This example demonstrates how to set up and run an agent that uses the `las` tool to query a LAS dataset and generate a poem based on the results. Ensure the necessary environment variables (`MODEL_AGENT_API_KEY`, `TOOL_LAS_URL`, `TOOL_LAS_DATASET_ID`) are configured.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.las import las

agent = Agent(
    name="las_agent",
    model_name="doubao-seed-1-8-251228",
    description="Answer using data in LAS.",
    instruction=(
        "You are a poet. First use the las tool to search the ds_public dataset for "
        "relevant content, then write a poem based on the results."
    ),
    tools=[las],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("Write a Chinese-style poem about wood and love")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

```

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

### Image Generation Agent Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/builtin.mdx

This example demonstrates how to use the `image_generate` tool with an Agent to create an image based on a text prompt. Ensure API keys and model names are configured in environment variables or `config.yaml`.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.image_generate import image_generate

agent = Agent(
    name="image_generate_agent",
    model_name="doubao-seed-1-8-251228",
    description="根据需求生成图片。",
    instruction="你是一个图片生成专家，根据用户的需求调用 image_generate 工具生成图片。",
    tools=[image_generate],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("生成一只可爱的小猫")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

```

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

### Set Up Environment Variables

Source: https://github.com/volcengine/veadk-python/blob/main/examples/sso_frontend_on_agentkit/README.md

Navigate to the example directory, copy the environment file, and source it to load necessary variables for local deployment and runtime authentication.

```bash
cd examples/sso_frontend_on_agentkit
cp .env.example .env
# Edit .env:
#   VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY   (local deploy auth)
#   OAUTH2_USER_POOL_ID / OAUTH2_USER_POOL_CLIENT_ID  (pool & client UIDs)
set -a && source .env && set +a
```

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

### Install VeADK Python Package

Source: https://github.com/volcengine/veadk-python/blob/main/examples/README.md

Install the VeADK Python package. Use the 'extensions' extra for RAG examples.

```bash
pip install veadk-python
# for the RAG example:
pip install "veadk-python[extensions]"
```

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

### Configure Environment and Run

Source: https://github.com/volcengine/veadk-python/blob/main/examples/05_knowledgebase_rag/README.md

Copy the example environment file and set the agent API key and embedding configuration. Then, run the main Python script.

```bash
cp .env.example .env   # set MODEL_AGENT_API_KEY (and embedding config)
python main.py
```

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

### Cross-Session Recall Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/memory/long-term/index.en.mdx

Demonstrates an end-to-end flow where an agent recalls information from a previous session. This example uses the 'local' backend and requires `pip install "veadk-python[extensions]"`. The agent is instructed to use the `load_memory` tool for recall.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.long_term_memory import LongTermMemory

APP_NAME = "ltm_demo"
USER_ID = "user-42"


def build_runner() -> Runner:
    ltm = LongTermMemory(backend="local", app_name=APP_NAME)
    agent = Agent(
        name="ltm_agent",
        instruction=(
            "You are a personal assistant. When the user asks about something they "
            "told you earlier, use the `load_memory` tool to recall it."
        ),
        long_term_memory=ltm,
        auto_save_session=True,
    )
    return Runner(agent=agent, app_name=APP_NAME, user_id=USER_ID)


async def main() -> None:
    runner = build_runner()

    print(
        "Session 1 ->",
        await runner.run(
            messages="Note this: I'm allergic to peanuts and I'm vegetarian.",
            session_id="session-1",
        ),
    )

    print(
        "Session 2 ->",
        await runner.run(
            messages="Recommend a dish for me, considering my dietary restrictions.",
            session_id="session-2",
        ),
    )


if __name__ == "__main__":
    asyncio.run(main())
```

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

### Code Execution Agent Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/builtin.en.mdx

This agent utilizes the run_code and web_search tools to perform data analysis, such as analyzing stock trends. It can install missing dependencies within the sandbox. Configure Volcengine AK/SK and AgentKit Tool IDs.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.run_code import run_code
from veadk.tools.builtin_tools.web_search import web_search

agent = Agent(
    name="data_analysis_agent",
    model_name="doubao-seed-1-8-251228",
    description="A data analysis agent for the stock market.",
    instruction=(
        "You are a senior engineer running code in a sandbox. Use web_search to find "
        "company operating data, and libraries like akshare to download stock data; "
        "install missing dependencies from code inside the sandbox when needed."
    ),
    tools=[run_code, web_search],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("Analyze the recent stock trend of Sungrow")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

```

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

### Install Veadk with Extensions

Source: https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb

Installs the veadk-python library along with its extensions using pip. The --quiet flag suppresses installation output.

```python
%pip install veadk-python[extensions] --quiet
```

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

### Initialize and Launch Agent Project

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/cli/agentkit-cli.en.mdx

This sequence demonstrates the common workflow of initializing a new project and then building and deploying it in a single step.

```bash
veadk agentkit init
veadk agentkit launch
```

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

### Web Search Agent Example

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/builtin.en.mdx

Demonstrates how to set up an agent that uses the web_search tool to answer questions requiring up-to-date information. Ensure Volcengine credentials and API keys are configured.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.web_search import web_search

agent = Agent(
    name="web_search_agent",
    model_name="doubao-seed-1-8-251228",
    description="An agent that answers questions with web search.",
    instruction="You are a helpful assistant. Use the web_search tool when you need fresh information.",
    tools=[web_search],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("What's the weather in Hangzhou today?")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

```

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

### Initialize KnowledgeBase and Add Documents

Source: https://github.com/volcengine/veadk-python/blob/main/examples/05_knowledgebase_rag/README.md

Create a local KnowledgeBase, add documents from a directory, and attach it to an Agent. The Agent automatically gets a retrieval tool.

```python
knowledgebase = KnowledgeBase(backend="local", index="company_faq")
knowledgebase.add_from_directory("./docs")

agent = Agent(knowledgebase=knowledgebase)   # retrieval tool added automatically
```

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

### Verify veadk-python Installation

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/installation.en.mdx

Check if the veadk-python library has been installed correctly by running the version command.

```bash
veadk --version
```

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

### Initialize Veadk KnowledgeBase and Agent

Source: https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb

Sets up the Veadk KnowledgeBase with the Viking DB backend and adds the downloaded PDF. It then initializes the Agent with the configured knowledge base.

```python
from veadk import Agent
from veadk.knowledgebase.knowledgebase import KnowledgeBase
from veadk.memory.short_term_memory import ShortTermMemory

app_name = "veadk_playground_app"
user_id = "veadk_playground_user"
session_id = "veadk_playground_session"

knowledgebase = KnowledgeBase(backend="viking", app_name=app_name)  # 指定 viking 后端

knowledgebase.add_from_files(files=[pdf_path])  # 直接添加文档，无需手动切片

agent = Agent(knowledgebase=knowledgebase)
```

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

### Install google-adk

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/agent/responses-api.en.mdx

Install or upgrade the google-adk library to version 1.21.0 or higher to use the Responses API.

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

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

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

### Build and Run VeADK Frontend

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/frontend.mdx

Build the frontend and then run a single command to provide both the UI and agent API. Open the UI at http://127.0.0.1:8000.

```bash
# 1. Build the frontend
cd frontend && npm install && npm run build

# 2. In the repository root, provide UI + agent API in a single process
veadk frontend --agents-dir examples
# Open http://127.0.0.1:8000
```

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

### Install Feishu Channel Extension

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/feishu-channel.en.mdx

Install the Feishu Channel extension with the VeADK extensions package or as a standalone dependency.

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

```bash
pip install lark-oapi
```

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

### Initialize New Project Interactively

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/cli/veadk-cli.en.mdx

Runs an interactive flow to set up a new project from a template. You will be prompted for project details.

```bash
veadk init
```

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

### Install Mem0 Dependency

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/memory/long-term/mem0.en.mdx

Install the necessary mem0 Python package using pip to enable the Mem0 backend.

```bash
pip install mem0
```

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

### Initialize Reinforcement Learning Project (Ark Platform)

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/optimization.en.mdx

Initialize a reinforcement learning project for the Ark Platform. This command creates a new directory with the basic project structure.

```bash
veadk rl init --platform ark --workspace veadk_rl_ark_project
```

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

### Install veadk-python Package

Source: https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb

Installs the veadk-python package. For zsh users, ensure package names are enclosed in double quotes.

```python
%pip install veadk-python --quiet
```

```bash
pip install "veadk-python"
pip install "agent-pilot-sdk>=0.0.9"
```

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

### Build and Serve VeADK Frontend

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/frontend.en.mdx

Build the React UI and then serve both the UI and the agent API from a single process. Open the UI in your browser.

```bash
# 1. build the UI
cd frontend && npm install && npm run build

# 2. serve UI + agent API from one process (repo root)
veadk frontend --agents-dir examples
# open http://127.0.0.1:8000
```

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

### Install VeADK Python Package

Source: https://github.com/volcengine/veadk-python/blob/main/examples/01_quickstart/README.md

Install the VeADK Python library using pip. This is a prerequisite for running VeADK applications.

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

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

### Install veadk-python via PyPI

Source: https://github.com/volcengine/veadk-python/blob/main/README.md

Install the veadk-python package using pip. To include extensions, use the `[extensions]` extra.

```python
pip install veadk-python

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

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

### Install VeADK Harness Extension

Source: https://github.com/volcengine/veadk-python/blob/main/veadk/extensions/harness/README.md

Install the VeADK Harness extension with the optional in-process Headroom compaction provider using pip.

```bash
pip install "veadk-python[harness]"
```

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

### Configure API Key

Source: https://github.com/volcengine/veadk-python/blob/main/examples/01_quickstart/README.md

Copy the example environment file and set your API key in the `.env` file. This is necessary for the agent to authenticate with the model service.

```bash
cp .env.example .env
# then edit .env and set MODEL_AGENT_API_KEY
```

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

### Create and Use Mobile Control Tool

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/builtin.en.mdx

This example demonstrates how to create a mobile control tool and use it within an agent to perform tasks on a cloud phone. Ensure you have purchased the cloud phone service and set up your instance.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.mobile_run import create_mobile_use_tool

agent = Agent(
    name="mobile_agent",
    model_name="doubao-seed-1-8-251228",
    description="An agent that operates a cloud phone.",
    instruction="Use the mobile tool to complete tasks on the cloud phone.",
    tools=[create_mobile_use_tool()],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run('Open the shopping app and search for "headphones"')
    print(response)


if __name__ == "__main__":
    asyncio.run(main())
```

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

### Install veadk-python with PIP

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/installation.en.mdx

Install the stable release of veadk-python using pip. Use the optional extras for additional functionality like the knowledge base.

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

```bash
pip install -U "veadk-python[extensions]"
```

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

### Run a Basic Agent

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/index.en.mdx

This snippet demonstrates how to initialize and run a basic agent with a simple instruction. Ensure you have the veadk library installed and asyncio available.

```python
import asyncio
from veadk import Agent, Runner

agent = Agent(instruction="You are a helpful assistant.")
print(asyncio.run(Runner(agent=agent).run("Hi, introduce yourself")))
```

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

### Using web_fetch Tool with an Agent

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/tools/builtin.mdx

This example shows how to set up an Agent to utilize the web_fetch tool for retrieving and processing content from URLs. The web_fetch tool itself does not require credentials, making it suitable for public links.

```python
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.web_fetch import web_fetch

agent = Agent(
    name="web_fetch_agent",
    model_name="doubao-seed-1-8-251228",
    description="An agent that reads web pages and PDFs.",
    instruction="Use the web_fetch tool to fetch the given URL, then answer based on its content.",
    tools=[web_fetch],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run(
        "抓取 https://arxiv.org/pdf/1706.03762 并总结这篇论文的核心思想"
    )
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

```

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

### Start API Server Locally

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/references/api-server.en.mdx

Starts the VeADK API server for local development. It defaults to listening on http://localhost:8000. Endpoints are unauthenticated by default.

```bash
veadk web              # local, defaults to http://localhost:8000
```

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

### Initialize KnowledgeBase with OpenSearch and Add Documents

Source: https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb

Initializes a KnowledgeBase instance using OpenSearch as the backend and adds documents from a local file. An Agent and Runner are then set up with this knowledge base.

```python
from veadk import Agent, Runner
from veadk.knowledgebase.knowledgebase import KnowledgeBase
from veadk.memory.short_term_memory import ShortTermMemory

app_name = "veadk_playground_app"
user_id = "veadk_playground_user"
session_id = "veadk_playground_session"


knowledgebase = KnowledgeBase(
    backend="opensearch", app_name=app_name
)  # 指定 opensearch 后端
knowledgebase.add_from_files(files=[knowledgebase_file])

agent = Agent(knowledgebase=knowledgebase)

runner = Runner(
    agent=agent,
    short_term_memory=ShortTermMemory(),
    app_name=app_name,
    user_id=user_id,
)
```

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

### Configure Agent with Knowledge Base Connection

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/cli/harness-cli.en.mdx

This example demonstrates adding an agent named 'kb-agent' and configuring its knowledge base connection to use the 'viking' backend. It also specifies the project and region for the Viking database.

```bash
veadk harness add --name kb-agent \
  --knowledgebase-type viking \
  --knowledgebase-project my-project --knowledgebase-region cn-beijing
```

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

### Clone and Install VeADK with Dev Dependencies

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/references/contributing.en.mdx

Clone the VeADK repository and install it in editable mode with development dependencies. This ensures all necessary tools for development are available.

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

pip install -e ".[dev]"
```

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

### Install Pre-commit Hooks

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/references/contributing.en.mdx

Install the pre-commit hooks to automatically run linters (Ruff) and secret detection (gitleaks) before each commit. This helps maintain code quality and security.

```bash
pre-commit install
```

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

### OpenSearch with Agent, File Ingestion, and Web Search Tool

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/knowledgebase/overview.en.mdx

This example shows how to use OpenSearch as a backend, ingest data from files, and integrate an agent with both the knowledge base and the web_search tool.

```python
import asyncio
from datetime import datetime

from veadk import Agent, Runner
from veadk.knowledgebase import KnowledgeBase
from veadk.tools.builtin_tools.web_search import web_search

APP_NAME = "opensearch_demo"

kb = KnowledgeBase(backend="opensearch", index=APP_NAME)
kb.add_from_files(["tmp/demo.txt"])  # write your knowledge into tmp/demo.txt first


def calculate_date_difference(date1: str, date2: str) -> int:
    """Calculate the absolute number of days between two dates.

    Args:
        date1: the first date, in "YYYY-MM-DD" format.
        date2: the second date, in "YYYY-MM-DD" format.

    Returns:
        The number of days between the two dates.
    """
    d1 = datetime.strptime(date1, "%Y-%m-%d")
    d2 = datetime.strptime(date2, "%Y-%m-%d")
    return abs((d2 - d1).days)


agent = Agent(
    name="chat_agent",
    model_name="doubao-seed-1-8-251228",
    instruction=(
        "You are an excellent assistant. Query the knowledge base first; "
        "if it is insufficient or the question involves real-time information, "
        "use `web_search`; then combine everything into a complete, accurate answer."
    ),
    knowledgebase=kb,
    tools=[calculate_date_difference, web_search],
)

runner = Runner(agent=agent, app_name=APP_NAME)

if __name__ == "__main__":
    print(asyncio.run(runner.run(messages="How many days apart are Freud and Adler?")))
```

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

### Install VeADK Extensions Package

Source: https://github.com/volcengine/veadk-python/blob/main/docs/content/docs/framework/troubleshooting.en.mdx

Install the VeADK extensions package to resolve 'not found' errors for packages like llama-index. In some shells, quotes may be necessary.

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

```bash
pip install "veadk-python[extensions]"
```