agent_start
Initiates web research tasks to extract structured data from specified or discovered URLs, returning a job ID for progress monitoring.
Instructions
Start a Firecrawl Agent job asynchronously. Returns a job ID immediately without waiting for completion. Use this for long-running research tasks. Poll with agent_status to check progress.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Describe what data you want to extract. Be specific about what information you need. | |
| urls | No | Optional: Specific URLs to search. If not provided, agent will search the web. | |
| schema | No | Optional: JSON schema for structured output. Define the exact structure you want the data returned in. | |
| maxCredits | No | Optional: Maximum credits to spend on this request. Use to control costs. |
Implementation Reference
- src/services/firecrawl-client.ts:65-95 (handler)Core handler that implements agent_start by POSTing the agent request to Firecrawl API /v1/agent/start endpoint and returning the job ID.
async startAgent(request: FirecrawlAgentRequest): Promise<FirecrawlAgentResponse> { try { const response = await fetch(`${this.apiBase}/v1/agent/start`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.apiKey}`, }, body: JSON.stringify(request), }); const data = await response.json() as any; if (!response.ok) { return { success: false, error: data.error || `HTTP ${response.status}: ${response.statusText}`, }; } return { success: true, id: data.id, }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } } - src/server.ts:269-313 (handler)MCP server tool call handler for 'agent_start': destructures arguments, calls FirecrawlClient.startAgent, formats response with jobId or error.
case 'agent_start': { const { prompt, urls, schema, maxCredits } = args as { prompt: string; urls?: string[]; schema?: Record<string, any>; maxCredits?: number; }; const result = await firecrawl.startAgent({ prompt, urls, schema, maxCredits, }); if (!result.success) { return { content: [ { type: 'text', text: `Error: ${result.error}`, }, ], isError: true, }; } return { content: [ { type: 'text', text: JSON.stringify( { success: true, jobId: result.id, message: 'Agent job started. Use agent_status with this jobId to check progress.', }, null, 2 ), }, ], }; } - src/server.ts:89-120 (schema)MCP tool schema definition for agent_start, including name, description, and JSON inputSchema matching FirecrawlAgentRequest.
{ name: 'agent_start', description: 'Start a Firecrawl Agent job asynchronously. Returns a job ID immediately without waiting for completion. Use this for long-running research tasks. Poll with agent_status to check progress.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'Describe what data you want to extract. Be specific about what information you need.', }, urls: { type: 'array', items: { type: 'string' }, description: 'Optional: Specific URLs to search. If not provided, agent will search the web.', }, schema: { type: 'object', description: 'Optional: JSON schema for structured output. Define the exact structure you want the data returned in.', }, maxCredits: { type: 'number', description: 'Optional: Maximum credits to spend on this request. Use to control costs.', }, }, required: ['prompt'], }, }, - src/types/firecrawl.ts:6-11 (schema)TypeScript interface defining the input parameters for agent_start, used in FirecrawlClient.startAgent.
export interface FirecrawlAgentRequest { prompt: string; schema?: Record<string, any>; urls?: string[]; maxCredits?: number; } - src/server.ts:215-217 (registration)Registers the ListTools handler that exposes the agent_start tool via the TOOLS array.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: TOOLS }; });