nimble-agents

Nimble Agents

通过 Nimble agents 提取结构化网页数据。始终以已执行的结果或可运行的代码收尾。

用户请求：$ARGUMENTS

前提条件

确保 Nimble MCP 服务已连接：

Claude Code：

export NIMBLE_API_KEY="your_api_key"
claude mcp add --transport http nimble-mcp-server https://mcp.nimbleway.com/mcp \
  --header "Authorization: Bearer ${NIMBLE_API_KEY}"

VS Code（Copilot / Continue）：

{
  "nimble-mcp-server": {
    "command": "npx",
    "args": ["-y", "mcp-remote@latest", "https://mcp.nimbleway.com/mcp",
             "--header", "Authorization:Bearer YOUR_API_KEY"]
  }
}

API 密钥： online.nimbleway.com/signup → Account Settings → API Keys

核心原则

• 最快获取数据的路径。 默认流程：发现 Agent → 获取架构 → 运行 → 展示结果。规划和生成是升级路径。
• 始终先搜索现有 Agent。 考虑生成前，先调用 nimble_agents_list。这是硬性规则。
• 始终优先更新，而非生成。 如果存在匹配度较高的 Agent（域名／类型相同，即使缺少字段或范围不同），应更新它，而不是从头生成。更新可以保留经过验证的提取逻辑，并且更快、更省成本、更可靠。只有当 nimble_agents_list 对目标域名返回 0 条结果时，才生成新的 Agent。如果存在匹配度较高的 Agent，绝不要将“创建新 Agent”作为推荐选项。
• 每个决策点都要使用 AskUserQuestion——没有例外。 始终提供每个步骤中所示的标准 AskUserQuestion 提示。绝不跳过，也绝不在未询问的情况下自动进入下一步。绝不要使用纯编号列表展示选项。限制：2–4 个选项，标题最多 12 个字符，标签为 1–5 个词。推荐选项放在首位，并添加“（推荐）”。
• 始终先获取架构，再运行。 调用 nimble_agents_run 前，先调用 nimble_agents_get。使用 Markdown 表格展示输入参数和输出字段。切换 Agent 时同样适用。
• 代码生成（步骤 2B）仅适用于大规模、高吞吐量任务。 普通交互式请求绝不生成代码。脚本模式必须同时满足以下所有条件：规模超过 50 项，且用户明确要求代码／脚本／CSV／批量输出。多来源请求、数据集请求和比较请求不会自动触发脚本模式——先以交互方式运行。默认路径始终是：发现 → 运行 → 展示结果。
• 生成脚本前验证响应结构。 检查 nimble_agents_get 返回的 skills 和 entity_type，以确定 REST API 响应的嵌套结构。参见 references/agent-api-reference.md > “Response shape inference” 和 references/sdk-patterns.md > “Response structure verification”。
• google_search 不是通用搜索工具。 它是用于排名跟踪和 SEO 分析的 SERP 分析 Agent。查找信息时，使用 nimble_web_search。参见 references/error-recovery.md。
• 所有网页搜索都必须使用 nimble_web_search（MCP）。 绝不使用 WebSearch、WebFetch 或 curl。参见防护规则。
• 前台禁止使用变更工具（generate、update、status、publish）。 始终委托给 Task Agent。参见委托模型。
• Task Agent 必须使用 run_in_background=False。 后台模式会导致 MCP 无法访问。参见委托模型。
• 前台 MCP 调用仅限 3 个工具： nimble_agents_list、nimble_agents_get、nimble_agents_run。
• 绝不要使用 nimble_find_search_agent、nimble_run_search_agent、nimble_url_extract 或任何 WSA 模板工具。

委派模型

前台对话负责协调并呈现结果。任务 Agent 负责所有 MCP 密集型工作。

前台 — 仅允许使用以下 3 个 MCP 工具（直接调用）：

工具	用途	最大调用次数
nimble_agents_list	路由到现有 Agent	每个来源 1 次
nimble_agents_get	运行前显示架构	每个 Agent 1 次
nimble_agents_run	交互式执行（≤5 项）	每项 1 次

任务 Agent — 负责其他所有工作（必须执行，不得例外）：

阶段	任务 Agent	前台执行
发现（nimble_web_search 深度搜索）	步骤 1D	启动任务，呈现报告
Agent 创建/更新（nimble_agents_generate、nimble_agents_update_from_agent、nimble_agents_update_session、nimble_agents_status、nimble_agents_publish）	步骤 3	启动任务，呈现报告
脚本生成（编写用于调用现有 Agent 的代码）	步骤 2B	启动任务，呈现脚本

严禁在前台使用 nimble_agents_generate、nimble_agents_update_from_agent、nimble_agents_update_session、nimble_agents_status 和 nimble_agents_publish。这些操作始终必须使用 Task(subagent_type="general-purpose", run_in_background=False)。

**为什么使用 run_in_background=False：**后台任务 Agent（run_in_background=True）无法访问 MCP 工具 — 它们会悄悄退回到 bash/curl 并失败。使用 run_in_background=False 可确保能够访问 MCP 工具。任务 Agent 仍在自己的上下文窗口中运行（不会污染前台）；唯一的代价是前台需要等待任务完成。平台解决此限制后，切回 run_in_background=True。

对于多来源工作流，按顺序启动任务 Agent（每个来源/阶段一个）。收集报告后，再呈现整合后的计划。

MCP 工具注册表

所有任务 Agent 提示词都必须包含工具注册表代码块，以便子 Agent 知道准确的 MCP 工具名称。将此代码块复制到每条任务提示词中：

**MCP tool registry (call these as MCP tool invocations, NOT bash/curl):**
| Short name | Full MCP tool name |
|------------|--------------------|
| nimble_agents_list | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_list |
| nimble_agents_get | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_get |
| nimble_agents_generate | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_generate |
| nimble_agents_update_from_agent | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_update_from_agent |
| nimble_agents_update_session | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_update_session |
| nimble_agents_status | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_status |
| nimble_agents_publish | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_publish |
| nimble_agents_run | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_run |
| nimble_web_search | mcp__plugin_nimble_nimble-mcp-server__nimble_web_search |

**CRITICAL: Use MCP tool calls only. NEVER use bash, curl, wget, WebSearch, or WebFetch to call APIs or search the web. NEVER construct MCP endpoint URLs manually.**

响应形状

层	路径	形状	使用场景
MCP 工具（nimble_agents_run）	data.results	始终为数组	交互式运行（步骤 2A）
REST API — 电商 SERP	data.parsing	list（数组）	脚本生成（步骤 2B）
REST API — 非电商 SERP	data.parsing.entities.{Type}	包含嵌套数组的 dict	脚本生成（步骤 2B）
REST API — PDP	data.parsing	dict（扁平）	脚本生成（步骤 2B）

遍历 REST 响应前，始终检查 typeof/isinstance。

步骤 1：路由

从 $ARGUMENTS 中检测 3 项：

1. 清晰度 — clear（默认）或 needs-planning

只有在以下内容全部缺失时，才选择 needs-planning：目标 URL/网站/域名、明确要提取的数据、范围明确的单一任务。大多数请求都属于 clear。

2. Agent 匹配 — 针对每个来源/域名，使用最具体的简短关键词（1–2 个词，例如域名或产品类型）调用一次 nimble_agents_list。这始终是第一个操作。对于多来源请求（例如“比较 Amazon 和 Walmart 的价格”），每个来源调用一次。不要使用不同查询重试同一来源——如果某个来源返回 0 个结果，将其路由到 Discovery（步骤 1D）。

结果	路由
完全匹配	显示 schema 摘要 + AskUserQuestion：“使用此 Agent”（推荐）/“创建新 Agent” → 步骤 3
接近匹配（相同领域/类型，但缺少字段或范围不同）	显示 schema 差异 + AskUserQuestion：“更新此 Agent”（推荐）/“创建新 Agent”。始终推荐更新——这样可以保留现有提取逻辑，且比从头生成更快。
2 个或更多可能的匹配项	显示表格 + 使用最匹配项的 AskUserQuestion，并提供“更新最接近的 Agent”（推荐）。选择字段重合最多的 Agent。
0 个匹配项	启动 Discovery Task Agent（步骤 1D）→ 调查结果用于步骤 3。只有在这种情况下才适合生成新 Agent。

始终优先更新，而非生成。 同一域名下的接近匹配 Agent 已有可用的 URL 模式、分页逻辑和解析规则。更新它以添加/更改字段只是小幅调整。从头生成则需要重新构建所有内容，并可能导致质量下降。只有目标域名完全不存在 Agent 时，才生成新 Agent。

3. 执行模式 — interactive（默认）或 script

始终默认使用交互模式。 只有同时满足以下两个条件时，才路由到脚本生成（步骤 2B）：(a) 规模明确超过 50 项，或用户提供了批量输入文件；(b) 用户明确要求代码、脚本、CSV 导出或批处理。“数据集”“比较”“多来源”或“2 个来源”等词语不会触发脚本模式——应以交互方式运行这些任务。脚本生成会编写调用现有 Agent 的代码，而不会创建新 Agent。如果尚无 Agent，应先解决此问题（步骤 3），再生成脚本。

步骤 1P：规划模式（少见——仅用于 needs-planning）

1. 澄清 — 使用 AskUserQuestion 解决关键的未知项（最多 2 个问题）。重点询问：网站、数据字段、输出格式。
2. 探索 — 对每个目标调用 nimble_agents_list（前台执行，每个目标调用 1 次）。对于不熟悉的领域，启动 Discovery Task Agent（步骤 1D）。
3. 呈现计划 — 差距分析表：

#	网站/数据源	Agent	状态
1	amazon.com 产品	amazon-product-details	已存在
2	walmart.com 产品	—	生成

4. 执行 — 对现有 Agent 执行步骤 2，对新 Agent 生成执行步骤 3（作为 Task Agent）。

步骤 1D：Discovery（Task Agent——用于不熟悉的领域）

当 nimble_agents_list 返回 0 个匹配项，且目标域名需要探索时启动。以 Task(subagent_type="general-purpose", run_in_background=False) 运行。前台告知用户：“正在探索 {domain}，了解可用数据……”

Task 提示词模板：

Explore {domain} for {user_intent}.

**MCP tool registry (call these as MCP tool invocations, NOT bash/curl):**
| Short name | Full MCP tool name |
|------------|--------------------|
| nimble_web_search | mcp__plugin_nimble_nimble-mcp-server__nimble_web_search |

**CRITICAL: Use MCP tool calls only. NEVER use bash, curl, wget, WebSearch, or WebFetch to call APIs or search the web. NEVER construct MCP endpoint URLs manually.**

Use `nimble_web_search` (MCP) with deep_search=true to discover the site and available data:
1. Search "{domain} {keywords}" with deep_search=true, max_results=5 — this fetches and extracts full page content from each result, giving you product listings, detail pages, and field structures in one call.

**Return a structured report:**
- DOMAIN: {domain}
- ESTIMATED_ITEMS: count matching query
- LISTING_URL_PATTERN: e.g., /category/filter?color=green
- DETAIL_URL_PATTERN: e.g., /p/{slug}-{SKU}.html
- AVAILABLE_FIELDS: list of extractable fields (name, price, description, materials, etc.)
- MISSING_FIELDS: fields the user wants but the site doesn't have (e.g., ratings, reviews)
- RECOMMENDED_APPROACH: generate custom agent / use existing agent from {alternative} / combine sources
- SAMPLE_URLS: 2–3 example URLs for agent generation
- LIMITATIONS: login walls, pagination limits, JS rendering, etc.

Do NOT use AskUserQuestion. Do NOT use nimble_find_search_agent, nimble_run_search_agent, or nimble_url_extract.
Do NOT use WebSearch, WebFetch, bash curl, or any non-MCP search/fetch method.

收到报告后，前台对话将：

1. 向用户呈现主要发现。
2. 如果存在数据缺口（例如缺少评分），通过 AskUserQuestion 询问用户如何继续。
3. 携带 Discovery 上下文路由到步骤 3（生成），或在现有 Agent 已满足需求时路由到步骤 2。

对于多来源工作流，针对每个不熟悉的域名并行启动一个 Discovery Agent。汇总所有报告后，再呈现综合计划。

步骤 2：运行现有 Agent

根据执行模式分为两条子路径。

2A：交互式（小规模，展示输出）

2A-1. 调用 nimble_agents_get。以 Markdown 表格展示架构：

• 输入参数： name、required、type、description、example
• 输出字段： skills 字典中的关键字段

完整的 input_properties 格式和映射规则，请参见 references/agent-api-reference.md >“输入参数映射”。

2A-2. 执行前务必通过 AskUserQuestion 确认：

question: "Run {agent_name} with these parameters?"
header: "Confirm"
options:
  - label: "Run agent (Recommended)"
    description: "Execute {agent_name} with {summary of inferred parameters}"
  - label: "Change parameters"
    description: "Adjust input parameters before running"
  - label: "Create new agent"
    description: "Create a custom agent instead (Step 3)"

2A-3. 调用 nimble_agents_run。以 Markdown 表格展示结果。务必询问接下来要做什么：

question: "What next?"
header: "Next step"
options:
  - label: "Done"
    description: "Finish with these results"
  - label: "Run again"
    description: "Re-run with different parameters"

除非用户明确提到需要大规模提取（>50 项）或批处理，否则不要提供脚本生成作为下一步。脚本生成并不是交互式运行后的自然后续步骤。

批量（2–5 个 URL）： 对每个 URL 分别运行，汇总结果，并处理单个失败而不中止整个流程。参见 references/batch-patterns.md >“交互式批量提取”。

2B：脚本生成（仅适用于大规模、高流量任务）

仅当用户明确需要大规模处理 >50 项，或请求生成批处理代码/脚本时，才进入此步骤。 普通请求——即使涉及多个来源或“数据集”——也通过步骤 2A 进行交互式处理。生成一个可运行的脚本，通过 SDK/REST API 大规模调用现有 Nimble Agent。这不会创建新 Agent——该 Agent 必须已存在。此步骤以 Task Agent 的形式运行。前台根据上下文推断语言，启动 Agent，并展示生成的脚本以供确认。

2B-1. 根据项目上下文推断语言（启动前由前台执行）：

项目文件	语言
pyproject.toml、requirements.txt、*.py	Python
package.json、tsconfig.json	TypeScript/Node
go.mod	Go（REST API）
以上均无	默认使用 Python

2B-2. 启动脚本生成 Task Agent：Task(subagent_type="general-purpose", run_in_background=False)。

Task 提示词模板：

Write a {language} script that calls existing Nimble agent(s) at scale via SDK/REST API.

**MCP tool registry (call these as MCP tool invocations, NOT bash/curl):**
| Short name | Full MCP tool name |
|------------|--------------------|
| nimble_agents_get | mcp__plugin_nimble_nimble-mcp-server__nimble_agents_get |

**CRITICAL: Use MCP tool calls only. NEVER use bash, curl, wget, WebSearch, or WebFetch to call APIs or search the web. NEVER construct MCP endpoint URLs manually.**

**Existing agents to call:** {agent_names}
**User intent:** {user_prompt}
**Output format:** {csv/json/etc}
**Scale:** {number of items/queries}

This is SCRIPT GENERATION — writing code that calls existing agents. Do NOT create new agents
(no nimble_agents_generate/update/publish). The agents listed above already exist.

Steps:
1. Call `nimble_agents_get` for each agent to inspect input_properties and skills.
2. Read the reference files:
   - `references/sdk-patterns.md` (Python) or `references/rest-api-patterns.md` (other languages)
   - `references/batch-patterns.md` (for multi-store normalization)
3. Write a complete, ready-to-run script with:
   - Smoke test first — validate a single query before full batch. Abort on failure.
   - Progress reporting — compact single-line status after each poll cycle.
   - Pagination handling for large result sets.
   - Multi-store field normalization (if applicable).
   - Output to {format}.
   - Incremental file writes for large pipelines (50+ jobs).

Return the complete script and a brief summary of:
- Agent schemas used (input params, key output fields)
- Normalization mappings (if multi-store)
- Total estimated API calls

Do NOT use AskUserQuestion. Do NOT use nimble_find_search_agent or nimble_run_search_agent.
Do NOT call nimble_agents_generate, nimble_agents_update_from_agent, nimble_agents_update_session, or nimble_agents_publish.
Do NOT use WebSearch, WebFetch, bash curl, or any non-MCP search/fetch method.

2B-3. 展示生成的脚本，并通过 AskUserQuestion 确认执行（由前台执行）：

question: "Run this script?"
header: "Confirm"
options:
  - label: "Run script (Recommended)"
    description: "Execute the generated script"
  - label: "Edit first"
    description: "Review and modify the script before running"

此处无需进行 Agent 验证。 50 个输入的验证流程（步骤 3）仅适用于 Agent 创建/更新。脚本生成使用的是现有且已验证的 Agent——只需编写脚本并运行即可。

步骤 3：在 Nimble 平台上更新现有 Agent 或创建新 Agent

在 Nimble 平台上更新现有 Agent（优先）或创建新 Agent。若步骤 1 找到了高度匹配的 Agent，默认选择更新——将现有 Agent 名称传递给 Task Agent，使其使用 nimble_agents_update_from_agent，而不是 nimble_agents_generate。只有步骤 1 未找到任何匹配项时，才创建新 Agent。这不是代码/脚本生成——它会创建/修改一个可通过步骤 2A 或 2B 调用的提取定义。始终以 Task Agent 形式运行（run_in_background=False）。

3-1. 创建稳定的 session_id（UUID v4）。

3-2. 仅向用户询问一次（仅限前台——仅用于创建/更新 Agent，绝不用于脚本生成）：

question: "Run refinement-validation before publishing?"
header: "Validate"
options:
  - label: "Yes, validate (Recommended)"
    description: "Discovery → generate → validate 50 inputs (80% pass) → publish. Auto-retries on failure."
  - label: "No, generate only"
    description: "Generate → publish immediately without validation testing"

3-3. 启动 Task Agent

将 refine_validate 设为用户的选择。使用 references/generate-update-and-publish.md 中的提示词模板启动 Task(subagent_type="general-purpose", run_in_background=False, max_turns=50)（包含 MCP 工具注册表、生命周期阶段及所有规则）。告知用户：“Agent 生成已开始。完成后我会汇报结果。”

Task Agent 执行闭环生命周期：发现 → 创建/更新 → 轮询 → 验证 → 发布 → 汇报。失败时会自动触发更新循环（最多 2 轮，墙钟超时为 15 分钟）。完整详情请参见参考文件。

3-4. 展示报告

Task Agent 完成后，展示报告。成功时，转至步骤 2A 或 2B。达到最大循环次数后仍失败，则提供：

question: "Agent validation did not reach 80% pass rate. How to proceed?"
header: "Next step"
options:
  - label: "Publish anyway"
    description: "Publish with current pass rate ({rate}%)"
  - label: "Update agent"
    description: "Provide specific instructions to refine the agent"

第 4 步：最终回复

最后附上简洁的汇总表：

字段	值
使用的 Agent	agent_name
来源	现有 / 生成
提取的记录数	count
输出	已显示 / filename.csv

包含提取结果（如果内容较多，则包含前 N 项）。

文档与故障排除

仅适用于大规模代码生成任务（第 2B 步）——编写大规模调用 Nimble API 的脚本时，请参考以下内容。交互式运行（第 2A 步）或创建 Agent（第 3 步）时，请勿加载这些内容：

1. references/sdk-patterns.md——正确的 SDK 使用模式和常见错误。
2. **https://docs.nimbleway.com/llms-full.txt**——完整的文字文档。
3. **https://docs.nimbleway.com/openapi.json**——API 契约。
4. Context7（如可用）——查询 nimbleway。

对于交互式运行和创建 Agent，nimble_agents_get 提供的 MCP 工具架构已包含所需的全部信息。

错误恢复

请参考 references/error-recovery.md，了解处理模式，包括数据源持续故障、Agent 匹配不明确，以及完整的回退层级。

其他参考资料

仅在大规模脚本生成（第 2B 步）或创建 Agent（第 3 步）期间加载参考文件。交互式运行（第 2A 步）时请勿加载——MCP 工具架构已足够。

仅适用于脚本生成（第 2B 步）：

• references/sdk-patterns.md——运行 Agent、异步端点、批处理流水线、增量文件写入。
• references/rest-api-patterns.md——适用于 TypeScript、Node、curl 和其他非 Python 语言的 REST API 使用模式。
• references/batch-patterns.md——多存储比较、规范化、交互式批处理、代码生成演练。

仅适用于创建/更新 Agent（第 3 步）：

• references/generate-update-and-publish.md——完整的 Agent 创建/更新生命周期：发现、创建、轮询、SDK 验证（50 个输入、80% 阈值）、发布、报告、更新循环。

通用（适用于任何步骤，按需加载）：

• references/agent-api-reference.md——MCP 工具参考及输入参数映射。
• references/error-recovery.md——错误处理与恢复模式。

防护规则

• 绝对不要在前台对话中调用 nimble_agents_generate、nimble_agents_update_from_agent、nimble_agents_update_session、nimble_agents_status 或 nimble_agents_publish。 这些工具必须在 Task Agent 中运行。没有例外——即使只是“快速调用一次”也不行。在前台轮询会占满上下文并浪费令牌。
• Task Agent 必须使用 run_in_background=False。 后台 Task Agent 无法访问 MCP 工具（已知的平台限制）。上游解决此问题后，改回 run_in_background=True。
• 所有网络搜索都必须使用 nimble_web_search（MCP 工具）。 绝对不要使用内置的 WebSearch、WebFetch、curl、wget 或任何其他搜索／抓取方式——无论是在前台还是 Task Agent 中。工具的完整名称是 mcp__plugin_nimble_nimble-mcp-server__nimble_web_search。
• 绝对不要使用 bash/curl 调用 MCP 端点。 Task Agent 必须通过工具名称调用 MCP 工具，而不是构造发往 MCP 服务 URL 的 HTTP 请求。如果 MCP 工具不可用，请报告错误——不要尝试通过 bash 绕过限制。
• 每个 Task Agent 提示都必须包含 委派模型 > MCP 工具注册表中的 MCP 工具注册表区块。 这会告知子 Agent 应使用的确切工具名称。缺少该区块时，子 Agent 可能无法找到 MCP 工具，并改用 bash。
• 前台可用的 MCP 工具仅限： nimble_agents_list、nimble_agents_get、nimble_agents_run。除此之外，不得使用其他工具。
• 绝对不要使用 nimble_find_search_agent、nimble_run_search_agent 或任何 WSA 模板工具。
• 优先更新，生成仅作最后手段。 如果存在匹配度较高的 Agent，始终使用 nimble_agents_update_from_agent 对其进行改进——绝不要为同一领域生成新的 Agent。只有在 nimble_agents_list 返回 0 条结果时，才使用 nimble_agents_generate。更新状态机的使用方式：先调用一次 nimble_agents_update_from_agent 以创建／解析更新会话，然后在每次后续操作中使用相同 session_id 调用 nimble_agents_update_session。同一优化流程中绝不要创建第二个会话。
• 严格遵守 429 规则。 如果 nimble_agents_generate 或 nimble_agents_update_from_agent 返回 429／配额错误，请停止并报告配额耗尽。不要改用任何更新工具，也不要创建新会话。
• 更新已发布的 Agent 时，系统会自动创建其分支。基于 UBCT 的 Agent 无法更新——请改为生成新的 Agent。
• 交互式运行（步骤 2A）时，绝不要加载外部文档（llms-full.txt、openapi.json）、SDK 参考资料或批处理模式文件。 这些内容仅用于大规模脚本生成（步骤 2B）。对于交互式运行，nimble_agents_get 返回的 MCP 工具架构已足够。加载不必要的文档会浪费上下文并拖慢执行。
• 以 Markdown 表格形式呈现工具调用结果。绝不要显示原始 JSON。