agent_execute
Execute web searches to autonomously find and extract specific data based on your prompt, returning structured results without requiring URLs.
Instructions
Execute Firecrawl Agent to search, navigate, and gather data from the web. The agent autonomously finds and extracts information based on your prompt. Waits for completion and returns results. Use this for immediate results.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Describe what data you want to extract. Be specific about what information you need. Examples: "Find the founders of Anthropic", "Get pricing information for Claude API", "Extract contact emails from YCombinator companies" | |
| 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/server.ts:224-267 (handler)MCP tool handler case for 'agent_execute' that calls FirecrawlClient.executeAgent and handles the response formatting.
case 'agent_execute': { const { prompt, urls, schema, maxCredits } = args as { prompt: string; urls?: string[]; schema?: Record<string, any>; maxCredits?: number; }; const result = await firecrawl.executeAgent({ 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, data: result.data, creditsUsed: result.creditsUsed, }, null, 2 ), }, ], }; } - src/types/firecrawl.ts:6-11 (schema)TypeScript interface FirecrawlAgentRequest defining the input schema for the agent_execute tool.
export interface FirecrawlAgentRequest { prompt: string; schema?: Record<string, any>; urls?: string[]; maxCredits?: number; } - src/server.ts:58-88 (registration)Registration of the 'agent_execute' tool in the TOOLS array, including MCP inputSchema.
name: 'agent_execute', description: 'Execute Firecrawl Agent to search, navigate, and gather data from the web. The agent autonomously finds and extracts information based on your prompt. Waits for completion and returns results. Use this for immediate results.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'Describe what data you want to extract. Be specific about what information you need. Examples: "Find the founders of Anthropic", "Get pricing information for Claude API", "Extract contact emails from YCombinator companies"', }, 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'], }, }, - Core implementation of agent execution via HTTP POST to Firecrawl API /v1/agent endpoint.
async executeAgent(request: FirecrawlAgentRequest): Promise<FirecrawlAgentResponse> { try { const response = await fetch(`${this.apiBase}/v1/agent`, { 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, data: data.data, creditsUsed: data.creditsUsed, }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } }