使用场景
开放式研究
回答那些跨越你尚未确定站点的问题——智能体自己发现信息源，而不是接收一份 URL 列表。
竞品快照
询问竞争对手当前的定价档位或功能集，得到综合后的答案，而不是一堆原始 HTML。
有边界的自主性
max_steps、max_urls 和 max_seconds 在模型之外强制执行，因此单次运行绝不会超出你设定的预算。
机器可读的答案
当结果要送入下游系统而非供人阅读时，把 output_format 设为 json。
Endpoint
POST
/api/v1/tools/agentAuth Required
Free 计划 1 req/s
8 credits
Parameters
三个
max_* 上限是由编排器强制执行的硬性停止条件，不是传给模型的建议。触发其中任一上限的运行会返回它已经收集到的内容，并在 stop_reason 中说明是哪个上限生效。| Name | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | Required | - | 用自然语言描述你需要什么。至少 10 个字符。 Example: Find the current pricing tiers for the top 3 MCP web-scraping providers |
max_steps | number | Optional | 10 | 规划与执行步骤的硬性上限（1-50）。 Example: 10 |
max_urls | number | Optional | 20 | 智能体最多可访问的 URL 数量硬性上限（1-100）。 Example: 20 |
max_seconds | number | Optional | 120 | 整次运行的墙钟时间硬性上限，单位为秒（10-600）。 Example: 120 |
output_format | string | Optional | "markdown" | 答案的形态：`text`、`json` 或 `markdown`。 Example: markdown |
请求示例
cURL
terminalBash
curl -X POST https://crawlforge.dev/api/v1/tools/agent \
-H "X-API-Key: cf_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Find the current pricing tiers for the top 3 MCP web-scraping providers",
"max_steps": 10,
"max_urls": 20,
"max_seconds": 120,
"output_format": "markdown"
}'TypeScript
agent.tsTypescript
const response = await fetch('https://crawlforge.dev/api/v1/tools/agent', {
method: 'POST',
headers: {
'X-API-Key': process.env.CRAWLFORGE_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
prompt: 'Find the current pricing tiers for the top 3 MCP web-scraping providers',
max_steps: 10,
max_urls: 20,
max_seconds: 120,
output_format: 'markdown',
}),
});
const data = await response.json();
if (data.success) {
console.log('Answer:', data.data.answer);
console.log('Steps taken:', data.data.steps_taken);
console.log('Sources read:', data.data.urls_visited);
// Anything other than 'completed' means a hard limit stopped the run early.
if (data.data.stop_reason !== 'completed') {
console.warn('Stopped early:', data.data.stop_reason);
}
console.log('Credits used:', data.credits_used);
console.log('Credits remaining:', data.credits_remaining);
} else {
console.error('Error:', data.error);
}Python
agent.pyPython
import requests
import os
response = requests.post(
'https://crawlforge.dev/api/v1/tools/agent',
headers={
'X-API-Key': os.environ['CRAWLFORGE_API_KEY'],
'Content-Type': 'application/json',
},
json={
'prompt': 'Find the current pricing tiers for the top 3 MCP web-scraping providers',
'max_steps': 10,
'max_urls': 20,
'max_seconds': 120,
'output_format': 'markdown'
}
)
data = response.json()
if data['success']:
print(f"Answer: {data['data']['answer']}")
print(f"Steps taken: {data['data']['steps_taken']}")
print(f"Sources read: {data['data']['urls_visited']}")
# Anything other than 'completed' means a hard limit stopped the run early.
if data['data']['stop_reason'] != 'completed':
print(f"Stopped early: {data['data']['stop_reason']}")
print(f"Credits used: {data['credits_used']}")
print(f"Credits remaining: {data['credits_remaining']}")
else:
print(f"Error: {data['error']}")响应示例
200 OK8420ms
{ "success": true, "data": { "prompt": "Find the current pricing tiers for the top 3 MCP web-scraping providers", "answer": "## Pricing comparison\n\n- **CrawlForge** — Free (1,000 credits), Hobby $19/mo, Professional $99/mo...", "output_format": "markdown", "steps_taken": 6, "urls_visited": [ "https://example.com/pricing", "https://example.org/plans" ], "limits": { "max_steps": 10, "max_urls": 20, "max_seconds": 120 }, "stop_reason": "completed" }, "credits_used": 8, "credits_remaining": 992, "processing_time": 8420}Field Descriptions
data.answer综合得出的答案，按请求的 `output_format` 呈现data.steps_taken本次运行实际使用的规划/执行步骤数data.urls_visited智能体在作答过程中读取的全部 URL——可用于审计信息源data.limits回显本次运行生效的硬性上限data.stop_reason智能体自行完成时为 `completed`；否则为终止它的那个上限credits_used本次运行扣除的 credits（每次运行 8 credits，与步骤数无关）credits_remaining你剩余的 credits 余额错误处理
输入无效（400 Bad Request）
提示词短于 10 个字符，或某个 max_* 值超出允许范围（max_steps 1-50，max_urls 1-100，max_seconds 10-600）。
智能体运行失败（500 Internal Server Error）
本次运行无法完成。失败的运行不扣除 credits——请用更聚焦的提示词或更小的 max_steps 重试。
credits 不足（402 Payment Required）
你的账户 credits 不足。购买更多 credits 或升级你的计划。
超出速率限制（429 Too Many Requests）
你已超出所在计划的速率限制。稍等片刻，或升级你的计划以获得更高上限。
专业提示：
stop_reason 不为 completed 的运行同样扣除 8 credits。调试提示词期间先设一个较小的 max_seconds，等智能体能稳定自行完成后再调高。credits 成本
8 credits
每次运行 8 credits
每次 agent 运行固定扣除 8 credits，与它走了多少步、访问了多少 URL 无关——你设定的上限约束的是墙钟时间，而不是价格。
Free 计划： 1,000 个一次性 credits = 125 次运行
Hobby 计划： 每月 5,000 credits = 625 次运行（19 美元/月）
Professional 计划： 每月 50,000 credits = 6,250 次运行（99 美元/月）
Business 计划： 每月 250,000 credits = 31,250 次运行（399 美元/月）
相关工具
准备好试用 agent 了吗？免费注册，获得 1,000 credits 开始构建。