Merge pull request volcengine#25 from volcengine/feat-fine-samples-readme

feat: refine samples readme

Author: codingmokey2025

02-use-cases/ai_coding/README.ai.md

@@ -0,0 +1,151 @@
+# AI Coding Agent - 智能编程助手
+
+## 项目概述
+
+这是一个基于火山引擎AgentKit构建的智能编程助手系统，专门用于帮助用户解决各类编程问题。系统集成了代码执行沙箱、TOS对象存储服务功能，能够提供专业、高效的编程辅助体验。
+
+## 功能特性
+
+### 🔧 核心功能
+
+- **智能编程对话**：基于AI的智能编程助手，能够理解用户编程需求并提供准确代码解决方案
+- **代码执行验证**：在沙箱环境中执行代码，验证代码的正确性和运行效果
+- **前端代码托管**：自动将前端代码（HTML/CSS/JS）上传至TOS对象存储，并生成可访问的预览链接
+- **多语言支持**：支持Python、Java、JavaScript、Go等多种编程语言
+- **长期记忆**：支持会话记忆和用户历史记录存储
+- **观测能力**：集成OpenTelemetry追踪和APMPlus监控
+
+## 项目结构
+
+```
+ai-coding/
+├── agent.py    # 主智能体应用，包含智能体配置和运行逻辑
+├── tools.py              # 工具函数模块，包含TOS上传、URL生成等功能
+├── requirements.txt      # Python依赖包列表
+└── README.md            # 项目说明文档
+```
+
+## 技术架构
+
+### 系统架构图
+
+```
+用户请求
+    ↓
+AgentKit - Runtime
+    ↓
+AI Coding Agent (主智能体)
+    ├── 代码执行工具 (run_code)
+    ├── TOS上传工具 (upload_frontend_code_to_tos)
+    ├── URL生成工具 (get_url_of_frontend_code_in_tos)
+```
+
+### 工具集成
+
+系统集成了以下核心工具：
+
+- **代码执行工具**：基于沙箱环境的安全代码执行
+- **TOS上传与下载工具**：自动化前端代码托管
+
+## 快速开始
+
+### 1. 前置准备
+
+#### 获取AK/SK
+
+1. 登录火山引擎控制台 (https://console.volcengine.com)
+2. 进入"访问控制" → "密钥管理"
+3. 点击"创建密钥"，生成新的Access Key和Secret Key
+4. 为AK/SK配置AgentKit产品权限：
+   - 进入"访问控制" → "策略管理"
+   - 将`AgentKitFullAccess`策略授权给指定用户,确保用户的AK/SK具有完整的AgentKit权限
+
+#### 获取AgentKit工具ID
+
+1. 登录火山引擎AgentKit控制台
+2. 进入"工具管理" → "工具列表"
+3. 创建新工具：
+   - 工具名称：ai-coding-agent
+   - 描述：AI编程助手工具
+4. 复制显示的工具ID，用于后续配置
+
+### 2. 安装依赖
+
+```bash
+cd 02-use-cases/ai_coding
+uv pip install -r requirements.txt
+# 或
+pip3 install -r requirements.txt
+```
+
+### 3. 配置环境变量
+
+本地必需：
+
+```bash
+export VOLCENGINE_ACCESS_KEY=AK
+export VOLCENGINE_SECRET_KEY=SK
+export DATABASE_TOS_BUCKET=agentkit-platform-{{your account_id}}
+export AGENTKIT_TOOL_ID={{your tool_id}}
+```
+
+说明：
+
+- `DATABASE_TOS_BUCKET`用来存储前端代码
+
+### 4. 启动与部署
+
+#### 本地调试
+
+本地可以使用 veadk web 进行调试
+
+```bash
+# 1. 进入 ai_coding 的上级目录
+cd 02-use-cases
+
+# 2. [可选] 创建配置配置 .env 文件，如果 步骤2 已经配置了环境变量，这里可以跳过
+touch .env
+# 配置 .env 文件, 
+echo "VOLCENGINE_ACCESS_KEY=AK" >> .env
+echo "VOLCENGINE_SECRET_KEY=SK" >> .env
+# 可选：如果未设置已有知识库，agent会自动创建知识库并做初始化导入， 这一步需要设置 DATABASE_TOS_BUCKET， 主要上传知识库内容并导入
+echo "DATABASE_TOS_BUCKET=agentkit-platform-{{your account_id}}" >> .env
+echo "AGENTKIT_TOOL_ID={{your tool_id}}" >> .env
+# 3.启动 veadk web 调试
+veadk web 
+```
+
+veadk web 默认会监听 8000 端口， 服务启动后，你可以在浏览器中访问 `http://127.0.0.1:8000`， agent 选择 `ai_coding`， 即可在 web 右侧的输入框中输入问题， 并查看智能体的回复。
+
+#### 部署到火山引擎 AgentKit（runtime）：
+
+使用 agentkit 部署到火山引擎。
+
+```bash
+# 1. 进入到 ai_coding 目录
+cd 02-use-cases/ai_coding
+
+# 2. 配置 agentkit
+agentkit config \
+--agent_name ai_coding \
+--entry_point 'agent.py' \
+--runtime_envs DATABASE_TOS_BUCKET=agentkit-platform-{{your account_id}} \
+--runtime_envs AGENTKIT_TOOL_ID={{your tool_id}} \
+--launch_type cloud
+
+# 3. 部署到 runtime 
+agentkit launch
+```
+
+发布成功后，可以登录火山引擎 AgentKit 控制台，点击 Runtime 查看部署的智能体。
+
+## 使用与测试
+
+示例 Prompt：
+
+- 前端代码生成：请帮我用JavaScript写一个防抖功能
+- python代码生成：请帮我写一个斐波那契数列生成函数
+
+## 常见问题
+
+- 首次运行报错 `DATABASE_TOS_BUCKET not set`：需设置用于代码上传的 TOS Bucket 名称。