> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

安装 VeADK Go 后，可以在 Go 项目中创建、运行和封装智能体。新项目默认使用 V2 模块路径；存量 V1 项目继续使用 V1 维护线。

## 前置条件

* Go 1.26.5 或更高版本。该要求来自当前主线 `go.mod`。
* 调用模型时需要可用的模型和 API Key；安装模块本身不需要模型凭证。
* 使用 V2 Preview 能力时，需要能访问 `veadk-go` 的 `main` 分支或指定提交。

## 新项目安装 V2

在你的项目目录初始化 Go module：

```bash theme={null}
mkdir veadk-go-demo
cd veadk-go-demo
go mod init example.com/veadk-go-demo
```

当前 Preview 文档以 V2 主线为准。若还没有对应的 V2 稳定 tag，使用 `@main` 或明确提交安装：

```bash theme={null}
go get github.com/volcengine/veadk-go/v2@main
```

安装后，代码中使用 V2 import 路径：

```go theme={null}
import (
	veagent "github.com/volcengine/veadk-go/v2/agent/llmagent"
	"google.golang.org/adk/v2/agent"
)
```

<Note>
  V2 包含 ADK v2 和 A2A v2 所需的破坏性更新。稳定 V2 tag 发布后，生产项目应固定到经过验证的版本，而不是长期依赖 `@main`。
</Note>

## 存量项目安装 V1

如果项目仍使用 ADK v1，可以安装 V1 维护版本：

```bash theme={null}
go get github.com/volcengine/veadk-go@v1.0.1
```

V1 import 路径不带 `/v2`：

```go theme={null}
import (
	veagent "github.com/volcengine/veadk-go/agent/llmagent"
	"google.golang.org/adk/agent"
)
```

V1 维护分支是 `release/v1`。查看 V1 示例或修复时，切换到该分支：

```bash theme={null}
git checkout release/v1
```

## 配置模型

VeADK Go 会从当前工作目录读取 `.env` 和 `config.yaml`。`.env` 不会覆盖已经存在的环境变量；`config.yaml` 中的键会转换为环境变量格式，且同样不会覆盖已存在的环境变量。因此，已导出的环境变量优先级高于文件配置。

在项目根目录创建 `config.yaml`：

```yaml theme={null}
model:
  agent:
    provider: openai
    name: deepseek-v4-flash-ga-260731
    api_base: https://ark.cn-beijing.volces.com/api/v3/
```

API Key 建议通过环境变量提供：

```bash theme={null}
export MODEL_AGENT_API_KEY="your-ark-api-key"
```

也可以完全使用环境变量配置模型：

```bash theme={null}
export MODEL_AGENT_PROVIDER="openai"
export MODEL_AGENT_NAME="deepseek-v4-flash-ga-260731"
export MODEL_AGENT_API_BASE="https://ark.cn-beijing.volces.com/api/v3/"
export MODEL_AGENT_API_KEY="your-ark-api-key"
```

<Warning>
  不要把真实 API Key、AK/SK 或 Token 写入版本库。运行示例会向所选模型服务发送提示词，并可能产生模型调用费用。
</Warning>

## 从源码验证

需要验证 V2 能力或本地修改时，克隆源码仓库：

```bash theme={null}
git clone https://github.com/volcengine/veadk-go.git
cd veadk-go
git checkout main
```

在源码仓中可以运行公开示例或测试。首次验证建议先选择不依赖外部模型的示例，例如 Runner 基础示例；需要调用模型的示例需先配置模型凭证。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.