最佳实践 - Agent Studio

以下是基于实际开发经验总结的高代码应用最佳实践，帮助您更高效地构建和部署 AI Agent 应用。

项目结构

核心要求：入口文件必须命名为 main.py。必须提供 GET /health 接口。使用 AgentScope Runtime 时该接口自动注册，无需手动实现。对话接口默认使用 /process 路径，遵循 Agent API 协议规范。 requirements.txt 中必须使用 == 固定依赖版本号（如 dashscope==1.20.14），避免使用 >= 等范围约束符。范围约束会导致每次构建拉取不同版本的依赖包，可能引起构建失败或运行时行为不一致。本地调试通过后，可使用 pip freeze > requirements.txt 导出精确版本。

工具选择指南

根据不同场景选择合适的工具类型：场景推荐工具说明企业知识问答知识库将产品文档、FAQ、操作手册等导入知识库，Agent 可精准检索回答。外部服务调用 MCP 服务需要搜索、金融数据、企业查询等外部能力时，优先从 MCP 广场选择已有服务，减少开发量。多 Agent 协作应用组件将复杂任务拆分为多个专业子 Agent（如翻译、摘要、分析），通过应用组件串联协作。数据查询分析数据连接器需要访问企业内部表格数据或文件时使用，支持结构化和非结构化数据。 多种工具可以组合使用。例如：知识库提供领域知识 + MCP 搜索服务提供实时信息 + 数据连接器访问业务数据，共同构建一个功能完整的 Agent。

MCP 工具开发最佳实践

编写高质量的 MCP 工具函数，提升 Agent 的工具调用效果：工具描述要精确：name 和 description 直接影响大模型的工具选择决策。描述应清晰说明工具的功能、适用场景和预期输入。

# 好的描述 — 大模型能准确判断何时使用
@mcp.tool(
name="search_product_docs",
description="在产品文档知识库中搜索与用户问题相关的技术文档和操作指南，适用于回答产品功能、配置方法、故障排查等问题")

# 不好的描述 — 大模型难以判断使用场景
@mcp.tool(
name="search",
description="搜索工具")

参数描述要完整：每个参数都应该通过 Field(description=...) 提供清晰的描述，包括预期格式、取值范围和默认值说明。

async def search(
query: Annotated[str, Field(description="搜索关键词，支持自然语言描述")],
top_k: Annotated[int, Field(description="返回结果数量，范围 1-20，默认 5")] = 5,
category: Annotated[str, Field(description="文档分类过滤，可选值：'all'/'api'/'guide'/'faq'")] = "all"
) -> str:

返回结构化结果：工具返回值应该格式化为大模型易于理解的文本，包含关键信息和上下文。

async def search(query, top_k=5):
results = await do_search(query, top_k)
# 格式化为大模型易读的结构
formatted = []
for i, r in enumerate(results, 1):
formatted.append(f"[{i}] {r.title}\n    摘要: {r.summary}\n    来源: {r.source}")
return "\n\n".join(formatted) if formatted else "未找到相关结果"

异常处理要友好：工具函数中的异常应转化为大模型可理解的错误信息，而非原始堆栈。

async def query_data(query):
try:
result = await connector.query(query)
return str(result)
except ConnectionError:
return "数据连接器暂时不可用，请稍后重试"
except ValueError as e:
return f"查询参数有误：{e}，请检查输入格式"

测试与调试

充分利用控制台提供的两种测试模式：测试模式适用场景使用建议 API 测试调试自定义接口、验证请求/响应格式、测试不同 Path 和 Header 开发初期用于验证接口连通性和参数格式。可自定义 HTTP Method、Path、Header 和 Body。文本对话体验模拟真实用户对话、验证多轮对话能力、检验工具调用效果开发中后期用于端到端验证。重点测试工具触发是否准确、回复质量是否满意。调试建议：在部署页面的日志子 Tab 中查看运行时日志，排查工具调用错误。在应用观测页面中观察调用次数、错误率和响应时间，识别性能瓶颈。使用 复制调用命令 按钮获取 curl 命令，在本地终端直接调试。开启应用观测功能，使用 @trace 装饰器追踪大模型调用耗时和工具执行链路。

生产环境部署

将高代码应用从开发测试推进到生产环境时，建议按照以下步骤操作：配置应用网关：在网关页面创建 API 网关实例，配置自定义域名和路由规则，将应用服务暴露在稳定的域名上。 应用部署地域应与网关所在地域相同，否则会导致路由不可达。开启 Token 鉴权：在网关配置中开启使用 Token 鉴权，确保只有经过授权的请求才能访问 API。关闭测试域名公网访问：在部署页面的触发器配置中，开启禁止公网访问开关，仅保留网关域名作为唯一入口。调整资源规格：根据预期流量调整 vCPU、内存和最小实例数。设置最小实例数 >= 1 可避免冷启动延迟。对于高性能、有状态或长程任务场景，可考虑使用 K8s 部署方式（需先开通容器服务 ACK），详见选择部署方式。开启应用观测：启用应用观测功能并在代码中植入 @trace 装饰器，持续监控应用的调用质量和性能。

前端集成

高代码应用的前端页面提供三种集成方式，根据需求选择合适的方案：方式适用场景说明直接体验快速验证、内部演示使用右侧文本对话体验模式，零代码即可体验，适合开发阶段快速验证。自定义交互卡片轻量定制、品牌展示在代码中定义交互卡片样式，直接在对话体验窗中展示自定义 UI 元素，无需独立前端项目。开发文档请参见 Spark Design 自定义卡片。自定义前端 WebUI 完全定制、生产级前端基于 Spark Design 前端框架开发完全自定义的前端页面，适合对 UI 有高度定制需求的生产环境。开发文档请参见 Spark Design 开发文档。 建议开发阶段使用"直接体验"快速验证功能，交付阶段根据需求复杂度选择"交互卡片"或"自定义 WebUI"。

性能优化建议

使用流式响应：Agent API 协议默认支持 SSE 流式输出。确保代码中使用异步生成器 (async yield) 返回结果，用户可实时看到输出，提升体验。合理设置最小实例数：生产环境建议最小实例数 >= 1，避免冷启动带来的首次请求延迟（通常 10-30 秒）。注意最小实例数会持续产生费用。工具调用并行化：当 Agent 需要调用多个独立工具时，使用 asyncio.gather() 并行执行，减少总响应时间。缓存频繁查询：对于变化不频繁的知识库查询或外部 API 调用结果，在内存中缓存以减少重复请求。

​项目结构

​推荐开发流程

​工具选择指南

​MCP 工具开发最佳实践

​测试与调试

​生产环境部署

​前端集成

​性能优化建议