创建与编排 Agent

Agent Studio（/app/apps/{agent_id}）在桌面端以双列布局显示编排区和实时预览：

• 左侧编排区（Orchestration Editor）：配置模型、系统提示词、变量、知识库、工具与运行参数。
• 右侧即时预览面板（Live Preview Panel）：在不离开页面或发布更改的情况下，与草稿 Agent 进行对话测试。
• 顶部操作栏：展示 Agent 元数据、发布状态（草稿 / 已发布）、嵌入入口（Embed）与高级设置（Settings）。

手机端隐藏并排预览，避免压缩编排区。点击顶部工具栏的 预览，即可在全屏抽屉式面板中打开对话；关闭预览即可返回编辑。

创建 Agent

1. 前往应用，选择创建应用 > Agent。
2. 填写名称（1-100 字符）与描述（最多 500 字符）。
3. 选择所属团队。
4. 进入 Agent Studio 编排页后选择右上角 Agent 设置，配置模型、开场消息、建议问题与可见性。
5. 可见性默认为私有（仅创建者可访问），可切换为团队。

最大迭代次数（Max Iterations） 是 Agent 的设置项 max_iterations：Agent 在一次回复里最多执行多少轮工具调用，默认 5，取值范围 1-200（后端校验）。设得过低会让复杂任务提前以 max_iterations_reached 结束；设得过高则可能在工具反复失败时消耗大量 Token。

编写提示词与变量

1. 在提示词中明确角色、任务、约束、工具使用条件和失败处理。
2. 输入 { 打开变量选择器。{query} 为当前用户消息。
3. 在变量中添加用户输入字段。变量名最长 50 字符；可配置显示名、必填、隐藏、默认值、选项、数值范围或最大长度。
4. 在右侧预览中填入变量，确认替换结果。

配置知识库与 RAG

1. 在知识库区域选择添加。
2. 选择知识库以及 vector、fulltext 或 hybrid 检索方式。
3. 设置 Top K（1-100，默认 5）和阈值（0-1，默认 0.3）。
4. 可选启用**重排序（Rerank）**以提高召回精度。
5. 设置整体 RAG 模式：关闭、自动（Auto） 或 智能体（Agentic）。

知识库顺序通过 knowledge_base_configs 列表定义，编辑 Agent 时可调整排列顺序，该顺序在 Agent 检索上下文时生效。 未关联知识库时，后端会将持久化的 rag_mode 规范化为 off，编辑器也会隐藏 RAG 模式选择器；关联知识库后才显示该选择器。

添加工具和能力

在工具区域选择内置工具、自定义工具、MCP 或 Skill。

工具显示"需要配置"时，先前往能力完成凭据。自定义工具先在能力中创建和测试，再按 Agent 启用。

配置附件、媒体与记忆

启用附件、生图、生视频和跨会话记忆前，先在 Agent 编排中开启对应能力：

媒体生成只覆盖图片和视频两种（没有音频/TTS 生成能力）。生图与生视频都会把 generate_image / generate_video 工具注入模型，并调用团队已授权的对应模型；关闭开关后模型看不到这些工具。

关于上下文：长对话的压缩是单次摘要——请求超过触发预算时，把较早历史生成一条摘要替换掉，只保留最近一段原文；它只作用于当前会话，不等同于跨会话记忆。记忆是独立的实体/关系图谱，跨会话持久保存。

详细配置请参阅附件与媒体和记忆与上下文。

设置可见性与发布

1. 选择私有或团队可见性。
2. 选择发布。发布后状态变为 published，Agent 可接收消息。
3. 发布后可打开公开页面、嵌入和访问 API。

保存、调试与发布

1. 选择保存。验证错误会列出具体字段。
2. 在调试与预览发送覆盖正常和失败路径的问题。
3. 有工具时验证工具参数、失败提示与最大迭代终止行为。
4. 选择发布。

要隐藏助手消息下方的生成文件列表，请在 Agent 设置中开启隐藏产物列表。该设置默认关闭；开启后只隐藏列表，不会删除生成的文件。

监控与统计

每个 Agent 有独立的监控页（/app/apps/{agent_id}/monitor），在 Agent 侧边栏选择监控打开。页面按 24h、7d（默认）、30d 展示概览卡片、使用趋势、工具调用分布、执行健康度、首 Token 延迟和用户干预。

底层数据来自三个只读端点（GET /api/v1/agents/{agent_id}/stats*，period: 24h、7d、30d、all）：

API 端点

管理端点位于 /api/v1/admin/agents，需要 admin:app:* 权限。

// 列出所有 Agent（按状态、可见性、团队、创建者、关键词过滤）
const agents = await api.get("/api/v1/admin/agents", { params: { status: ["published"] } });

// 为团队创建 Agent
const agent = await api.post("/api/v1/admin/agents", {
    name: "Support Agent",
    team_id: "team-123",
    model_id: "model-456",  // TeamModel ID（团队授权的模型）
    system_prompt: "You are a helpful assistant.",
    rag_mode: "agentic"
});

// 更新 Agent（使用 PUT，不是 PATCH）
const updated = await api.put(`/api/v1/admin/agents/${agent_id}`, {
    name: "Support Agent v2"
});

// 发布 / 取消发布 / 复制
await api.post(`/api/v1/admin/agents/${agent_id}/publish`);
await api.post(`/api/v1/admin/agents/${agent_id}/unpublish`);
await api.post(`/api/v1/admin/agents/${agent_id}/duplicate`);

// 获取 Agent 统计（period: 24h, 7d, 30d, all）
const stats = await api.get(`/api/v1/agents/${agent_id}/stats`, { params: { period: "30d" } });

完整 API 请参阅 Agents API。

最佳实践

Agent 设计

• ✅ 编写清晰、具体的系统提示词

• ✅ 部署前充分测试

• ✅ 为任务选择合适的模型

• ✅ 启用 RAG 以提高事实准确性

• ✅ 通过统计端点监控使用量

• ✅ 收集用户反馈并迭代

• ❌ 使用模糊的系统提示词

• ❌ 部署未经测试的 Agent

• ❌ 简单任务使用昂贵模型

• ❌ 忽略错误率

• ❌ 不监控成本

性能

• ✅ 启用流式输出提升体验

• ✅ 优化知识库搜索

• ✅ 设置合理的超时时间

• ❌ 长任务使用同步处理

• ❌ 给 Agent 加载过多知识库

• ❌ 设置过高的 max_tokens

故障排查

Agent 无响应

1. 检查 Agent 状态：确认已发布；检查模型可用性。
2. 检查模型配置：验证 API 密钥有效；测试模型连通性；检查速率限制。
3. 检查知识库：确认已索引；确认搜索正常。
4. 检查审计日志：筛选资源类型为 agent 且资源 ID 匹配的错误。

回复质量差

1. 审查系统提示词：让指令更清晰；添加示例；设定边界。
2. 改善知识库：添加相关文档；更新过时内容；优化分块策略。
3. 启用 Agentic RAG：让 Agent 自主决定何时检索，提升事实准确性。

成本过高

1. 审查用量：通过 GET /api/v1/agents/{agent_id}/stats 查看 Token 用量和会话数，定位高用量 Agent。
2. 优化提示词：缩短系统提示词；减少上下文长度；简单任务使用更便宜的模型。

常见问题

• 模型列表为空：团队未获对话模型授权，或模型已禁用。
• 工具未调用：检查模型函数调用能力、工具是否启用，以及提示词是否定义调用条件。
• 发布失败：确认拥有发布权限，且模型、变量引用和能力配置有效。
• 公开页无法访问：确认 Agent 已发布；私有/团队可见性仍受登录和团队访问控制影响。

限制与未实现功能