智能体开发API文档生成高阶版提示词

角色定义与任务定位

请以“资深智能体开发架构师兼技术文档专家”的身份，运用本提示词方案。你的核心目标是：系统化地生成一份面向开发者、具备高度可用性与专业性的智能体API接口文档。你的产出不是简单的参数罗列，而是能指导开发集成、阐明设计逻辑、确保交互可靠的结构化技术文档。

适用场景

• 为自主开发的智能体（Agent）生成对外服务的API接口说明。
• 为内部智能体平台编写统一、标准的API文档规范。
• 将智能体的核心能力（如意图识别、任务规划、工具调用）封装为可调用的服务文档。
• 对现有智能体API文档进行重构、优化与质量提升。

核心提示词

以下提示词框架可直接使用或嵌入更复杂的指令中：

• “作为智能体‘[智能体名称]’的API文档生成器，请严格遵循OpenAPI 3.0.3规范，为以下端点生成详细文档：端点路径：[例如 /v1/agent/process]，HTTP方法：[例如 POST]。文档需包含：清晰的接口概述、标准的请求/响应格式示例（JSON）、所有必需和可选参数（包括名称、类型、是否必填、描述、示例值）、可能的错误状态码及含义、以及一个完整的调用流程伪代码示例。”
• “请为智能体的‘工具调用（Tool Calling）’API生成结构化文档。重点描述：工具发现端点、工具执行端点的请求结构、异步回调机制、执行状态查询，并附带一个‘天气查询工具’的完整调用示例。”
• “生成智能体‘会话管理’API文档。需涵盖：创建会话、发送消息（支持流式响应）、获取会话历史、管理会话上下文的端点。在参数部分，详细说明‘system_prompt’、‘temperature’、‘max_tokens’等控制参数对智能体行为的影响。”

风格方向

• 专业严谨：采用技术文档的客观、准确、无歧义表述风格，避免口语化和营销词汇。
• 用户友好：在保持专业性的同时，通过清晰的层级划分、必要的术语解释和贴心的使用提示，降低开发者阅读门槛。
• 结构化呈现：强制使用分节标题（概述、请求、响应、错误码、示例）、代码块、表格等元素，确保视觉逻辑清晰。
• 一致性：全文术语、格式、示例风格保持统一，符合业界主流API文档（如Stripe、GitHub API）的审美与实用标准。

构图建议（信息架构）

• 顶部总览：文档开头应提供智能体的核心功能简介和API基础信息（如Base URL、认证方式）。
• 模块化分区：按功能模块组织API，例如：身份验证、会话管理、工具调用、监控与日志。
• 单端点纵深结构：每个端点下，按“概述 -> 请求参数（表格化） -> 响应体（表格化+示例） -> 错误码 -> 调用示例”的顺序展开。
• 附录与导航：在文档末尾或侧边栏提供术语表、常见问题、版本更新日志，并确保有便捷的目录导航。

细节强化

• 参数描述：不仅说明“是什么”，更要说明“为什么”和“如何用”。例如，描述“stream”参数时，应说明其用于启用Server-Sent Events（SSE）流式输出。
• 示例价值：示例代码应贴近真实开发场景，展示完整的请求头、认证信息、请求体和成功/失败的响应。
• 错误处理：详细列出每个错误码（如4001-参数无效，5002-智能体引擎超时）的具体触发条件和建议的客户端处理策略。
• 版本控制：明确标注API版本，并对不推荐使用的（deprecated）端点给出迁移指南。
• 安全说明：清晰说明认证方式（如API Key、OAuth 2.0），并给出密钥管理的最佳实践建议。

使用建议

• 将“核心提示词”中的占位符（如[智能体名称]）替换为您的实际项目信息后，可直接输入至高级语言模型或文档生成工具。
• 生成初稿后，建议重点人工复核“错误码”和“边界条件”描述的准确性与完整性，这是自动生成的薄弱环节。
• 可结合Swagger UI、Redoc等工具，将生成的OpenAPI规范文档自动渲染为交互式文档页面，提升开发者体验。
• 本方案侧重于内容生成框架，实际使用时可根据智能体的具体能力（如多模态处理、长上下文记忆）增删相应的API模块与描述细节。