创建 IDE 自定义智能体

配置 .agent.md 的说明、工具与模型，并理解 IDE 和云端字段差异。

This page has not been translated into English yet. The original Chinese version is shown below.

Custom agent 将某类工作的行为说明、工具范围与模型选择保存在 Markdown 配置中。JetBrains、Eclipse、Xcode 的 custom agents 当前仍标为 public preview。

创建入口

编辑器	操作与位置
VS Code	Chat agent 下拉 → Configure Custom Agents... → Create new custom agent；Workspace 保存到 .github/agents，User profile 可跨工作区使用
JetBrains	Configure Agents... → Chat Agents → Workspace，创建 .github/agents 中的文件
Eclipse	Configure Agents... → Add...，创建 .github/agents 中的文件
Xcode	agent 下拉 → Create an agent，创建 .github/agents 中的文件

文件使用 .agent.md 后缀。创建后在 Chat 的 agent 下拉中选择该智能体，再输入任务。修改同样从配置菜单进入；Xcode 用智能体旁的铅笔按钮编辑。

最小配置

以下为基于官方字段结构整理的示例，仅开放读取与搜索工具：

---
name: codebase-explorer
description: Explores code structure and reports relevant implementation details
tools: ["read", "search"]
---

阅读与问题相关的代码，列出发现、文件位置和仍未确认的事项。不要提出已完成实现的结论。

description 必填，name 可省略，省略时使用去掉扩展名的文件名。行为提示写在 frontmatter 后，官方给出的长度上限为 30,000 字符。

工具和模型

tools 省略表示开放所有可用工具，tools: [] 才是禁用全部工具；指定列表则筛选工具。可使用 read、search、edit 等别名，以及已配置 MCP 的 server/tool 或 server/*。无法识别的工具名会被忽略。

VS Code、JetBrains、Eclipse 可通过 Configure Tools... 选择实际可用工具，并通过 model 自动补全选择模型。Xcode 的 Customize Agent 对话框可选择模型、工具与 handoffs。

target 可以设为 vscode 或 github-copilot，省略时面向两者；不要编造其他 IDE 名称作为新的合法枚举值。

IDE 与云端的字段边界

IDE 创建教程的通用步骤提到 mcp-servers，但专门配置参考明确写明：IDE 自定义智能体不使用 mcp-servers 和 metadata。在 IDE 中先配置 MCP，再由 tools 选择其工具，不能依赖 agent 文件中的服务器定义自动启动服务。

反过来，IDE 的 argument-hint 与 handoffs 在 GitHub.com cloud agent 中不受支持，会被忽略。共享配置时应核对目标环境，不能认为同一文件所有字段处处生效。

用作子智能体

自定义智能体可以为IDE subagents提供专门职责。其 description 会帮助主会话判断是否委派；工具开关与调用方式仍按具体 IDE 配置。CLI 的文件发现、模型与并发规则参阅CLI 自定义智能体，不要直接套用到 IDE。