必须使用豆包2.1 Pro模型与方舟CLI完成AI Agent初始化部署，网页控制台无法单独生成；需开通Agent Plan算力包、安装CLI、扫码登录、配置region为cn-north-1；项目名须符合DNS规范；agent.yaml中name必须为合法英文标识符；tool路径须以./tools/开头；部署后需用临时Token调用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在火山引擎上创建一个可运行、可调用工具的AI Agent，必须依托豆包2.1 Pro模型能力与方舟CLI命令行工具完成初始化和部署，不能仅靠网页控制台点选生成。
确认开发环境与权限准备
打开火山引擎控制台 → 进入「方舟（Ark）」服务页 → 点击左侧菜单「Agent 开发」→ 确保当前账号已开通「Agent Plan」算力包（未开通则点击「立即开通」，选择「豆包2.1 Pro」规格并完成实名认证）。
在本地终端执行 curl -s https://ark.volcengine.com/install.sh | bash 安装方舟CLI；安装完成后运行 【ark auth login】，按提示扫码绑定火山引擎主账号——这一步失败会导致后续所有命令报“Unauthorized”，且无法跳过。
检查是否已配置默认 Region：运行 ark config get region，若返回为空，需手动执行 ark config set region cn-north-1（华北一区为当前唯一支持Agent部署的可用区）。
立即进入“豆包AI人工智官网入口”；
立即学习“豆包AI人工智能在线问答入口”；
初始化 Agent 项目结构
在空目录中运行 ark agent init my-agent，项目名必须符合 DNS 子域名规范（小写字母+短横线+数字，长度3–63字符），否则后续部署会中断并清空已上传文件。
进入 my-agent 目录后，你会看到三个核心文件：agent.yaml（定义Agent身份、描述、工具列表）、index.ts（主逻辑入口，导出 default 函数）、tools/（存放各工具实现）。
打开 agent.yaml，修改 name 字段为中文名（如“客服小助手”）不会报错，但会导致 API 调用时 endpoint 路径仍使用原始英文名，务必保持 name 值为合法英文标识符。
编写并注册一个可用工具
在 tools/ 目录下新建 weather.ts，粘贴以下代码：
import { Tool } from '@volcengine/ark';
export const weatherTool: Tool = {
name: 'get_weather',
description: '根据城市名获取实时天气与温度',
parameters: {
type: 'object',
properties: { city: { type: 'string', description: '城市中文名，如北京、杭州' } },
required: ['city']
}
};
export async function get_weather({ city }: { city: string }) {
const res = await fetch(`https://api.example-weather.com/v1?city=${encodeURIComponent(city)}`);
return res.json();
}
回到 agent.yaml，在 tools 列表中添加该项：
- ./tools/weather.ts
注意：tool 文件路径必须以 【./tools/】 开头，写成 tools/weather.ts 或 /tools/weather.ts 均会导致构建失败且无明确错误提示。
本地调试与部署上线
第一步：启动本地沙箱调试
执行 ark agent dev，等待控制台输出 “Listening on http://localhost:3000” 后，在新终端中运行：
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"上海今天天气怎么样？"}]}'
第二步：部署到火山引擎边缘节点
执行 ark agent deploy --env prod，该命令会自动完成：打包 TypeScript、上传至火山对象存储、触发边缘函数构建、注入环境变量、生成公网可访问 endpoint。
第三步：获取调用凭证
部署成功后，控制台将输出类似 https://ark-xxxxx.cn-north-1.volces.com/v1/agents/my-agent/chat 的地址；同时自动生成一个有效期7天的临时 Token，首次调用前必须在请求头中加入 Authorization: Bearer <token>。
