Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(dot-net-sdk): add InteractAsync and StopInteractiveBrowserAsync (#5234)
Erik Engervalld53ba685de8c
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/InteractTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/InteractTests.csnew file mode 100644index 000000000..5735ea002--- /dev/null+++ b/apps/dot-net-sdk/Firecrawl.Tests/InteractTests.cs@@ -0,0 +1,98 @@+using System.Net;+using System.Text;+using System.Text.Json;+using Xunit;++namespace Firecrawl.Tests;++public class InteractTests+{+ private sealed class StubHandler : HttpMessageHandler+ {+ private readonly string _body;++ public StubHandler(string body) => _body = body;++ public HttpRequestMessage? Request { get; private set; }++ public string? RequestBody { get; private set; }++ protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)+ {+ Request = request;+ RequestBody = request.Content is null ? null : await request.Content.ReadAsStringAsync(cancellationToken);+ return new HttpResponseMessage(HttpStatusCode.OK)+ {+ Content = new StringContent(_body, Encoding.UTF8, "application/json"),+ };+ }+ }++ private static FirecrawlClient ClientFor(StubHandler handler) =>+ new(apiKey: "fc-test-key", apiUrl: "http://localhost", maxRetries: 0, httpClient: new HttpClient(handler));++ [Fact]+ public async Task InteractAsync_PostsCodeAndReadsOutput()+ {+ var handler = new StubHandler(+ "{\"success\":true,\"stdout\":\"Example Domain\\n\",\"result\":\"\",\"stderr\":\"\",\"exitCode\":0,\"killed\":false,\"truncated\":false,\"cdpUrl\":\"wss://browser.example/cdp\"}");+ var client = ClientFor(handler);++ var response = await client.InteractAsync("job-123", "console.log(await page.title())", timeout: 60);++ Assert.True(response.Success);+ Assert.Equal("Example Domain\n", response.Stdout);+ Assert.Equal(0, response.ExitCode);+ Assert.False(response.Killed);+ Assert.False(response.Truncated);+ Assert.Equal("wss://browser.example/cdp", response.CdpUrl);++ Assert.Equal(HttpMethod.Post, handler.Request!.Method);+ Assert.Equal("http://localhost/v2/scrape/job-123/interact", handler.Request.RequestUri!.ToString());+ using var body = JsonDocument.Parse(handler.RequestBody!);+ var root = body.RootElement;+ Assert.Equal("console.log(await page.title())", root.GetProperty("code").GetString());+ Assert.Equal("node", root.GetProperty("language").GetString());+ Assert.Equal(60, root.GetProperty("timeout").GetInt32());+ Assert.StartsWith("dotnet-sdk@", root.GetProperty("origin").GetString());+ Assert.False(root.TryGetProperty("prompt", out _));+ }++ [Fact]+ public async Task InteractAsync_SendsPromptWithoutCode()+ {+ var handler = new StubHandler("{\"success\":true,\"output\":\"Clicked the button\"}");+ var client = ClientFor(handler);++ var response = await client.InteractAsync("job-123", null, prompt: "Click the first button");++ Assert.Equal("Clicked the button", response.Output);+ using var body = JsonDocument.Parse(handler.RequestBody!);+ Assert.Equal("Click the first button", body.RootElement.GetProperty("prompt").GetString());+ Assert.False(body.RootElement.TryGetProperty("code", out _));+ Assert.False(body.RootElement.TryGetProperty("timeout", out _));+ }++ [Fact]+ public async Task InteractAsync_RequiresCodeOrPrompt()+ {+ var client = ClientFor(new StubHandler("{}"));++ await Assert.ThrowsAsync<ArgumentException>(() => client.InteractAsync("job-123", " "));+ }++ [Fact]+ public async Task StopInteractiveBrowserAsync_SendsDelete()+ {+ var handler = new StubHandler("{\"success\":true,\"sessionDurationMs\":4200,\"creditsBilled\":2}");+ var client = ClientFor(handler);++ var response = await client.StopInteractiveBrowserAsync("job-123");++ Assert.True(response.Success);+ Assert.Equal(4200, response.SessionDurationMs);+ Assert.Equal(2, response.CreditsBilled);+ Assert.Equal(HttpMethod.Delete, handler.Request!.Method);+ Assert.Equal("http://localhost/v2/scrape/job-123/interact", handler.Request.RequestUri!.ToString());+ }+}diff --git a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.csindex e71ebca04..7d0ba8e2a 100644--- a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs+++ b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs@@ -30,6 +30,8 @@ public class FirecrawlClientprivate const double DefaultBackoffFactor = 0.5;private const int DefaultPollIntervalSec = 2;private const int DefaultJobTimeoutSec = 300;+ private const int DefaultInteractTimeoutSec = 30;+ private const int InteractTimeoutHeadroomSec = 60;private readonly FirecrawlHttpClient _http;@@ -89,6 +91,63 @@ public class FirecrawlClientreturn response.Data ?? throw new FirecrawlException("Scrape response contained no data");}+ /// <summary>+ /// Runs code or a natural-language prompt in the browser session of a scrape job.+ /// </summary>+ /// <param name="jobId">The scrape job ID (<c>metadata.scrapeId</c> on the scraped document).</param>+ /// <param name="code">Code to run. Optional when <paramref name="prompt"/> is set.</param>+ /// <param name="language">Runtime for the code: "node", "python", or "bash".</param>+ /// <param name="timeout">Execution timeout in seconds (1-300). The API defaults to 30.</param>+ /// <param name="prompt">Natural-language instruction for the browser agent. Optional when <paramref name="code"/> is set.</param>+ /// <param name="cancellationToken">Cancellation token.</param>+ public async Task<BrowserExecuteResponse> InteractAsync(+ string jobId,+ string? code,+ string language = "node",+ int? timeout = null,+ string? prompt = null,+ CancellationToken cancellationToken = default)+ {+ ArgumentNullException.ThrowIfNull(jobId);++ var hasCode = !string.IsNullOrWhiteSpace(code);+ var hasPrompt = !string.IsNullOrWhiteSpace(prompt);+ if (!hasCode && !hasPrompt)+ throw new ArgumentException("Either code or prompt must be provided", nameof(code));++ var body = new Dictionary<string, object>+ {+ ["language"] = language,+ ["origin"] = SdkOrigin,+ };+ if (hasCode)+ body["code"] = code!;+ if (hasPrompt)+ body["prompt"] = prompt!;+ if (timeout.HasValue)+ body["timeout"] = timeout.Value;++ // Browser setup and cleanup run outside the execution timeout, so allow headroom past it.+ return await _http.PostAsync<BrowserExecuteResponse>(+ $"/v2/scrape/{Uri.EscapeDataString(jobId)}/interact",+ body,+ cancellationToken: cancellationToken,+ minimumTimeout: TimeSpan.FromSeconds((timeout ?? DefaultInteractTimeoutSec) + InteractTimeoutHeadroomSec));+ }++ /// <summary>+ /// Stops the browser session of a scrape job.+ /// </summary>+ public async Task<BrowserDeleteResponse> StopInteractiveBrowserAsync(+ string jobId,+ CancellationToken cancellationToken = default)+ {+ ArgumentNullException.ThrowIfNull(jobId);++ return await _http.DeleteAsync<BrowserDeleteResponse>(+ $"/v2/scrape/{Uri.EscapeDataString(jobId)}/interact", cancellationToken);+ }+// ================================================================// CRAWL// ================================================================diff --git a/apps/dot-net-sdk/Firecrawl/FirecrawlHttpClient.cs b/apps/dot-net-sdk/Firecrawl/FirecrawlHttpClient.csindex 883580ce0..13fe6f5f5 100644--- a/apps/dot-net-sdk/Firecrawl/FirecrawlHttpClient.cs+++ b/apps/dot-net-sdk/Firecrawl/FirecrawlHttpClient.cs@@ -19,6 +19,9 @@ internal class FirecrawlHttpClientprivate readonly int _maxRetries;private readonly double _backoffFactor;+ // Null when there is no timeout: infinite, or a caller-supplied HttpClient whose own Timeout applies.+ private readonly TimeSpan? _timeout;+internal static readonly JsonSerializerOptions JsonOptions = new(){PropertyNamingPolicy = JsonNamingPolicy.CamelCase,@@ -45,15 +48,19 @@ internal class FirecrawlHttpClient}else{- _httpClient = new HttpClient { Timeout = timeout };+ _httpClient = new HttpClient { Timeout = System.Threading.Timeout.InfiniteTimeSpan };+ _timeout = timeout == System.Threading.Timeout.InfiniteTimeSpan ? null : timeout;}}+ /// <param name="minimumTimeout">Raises the configured timeout for this request when it is shorter.+ /// Has no effect on a caller-supplied HttpClient.</param>internal async Task<T> PostAsync<T>(string path,object body,Dictionary<string, string>? extraHeaders = null,- CancellationToken cancellationToken = default)+ CancellationToken cancellationToken = default,+ TimeSpan? minimumTimeout = null){var url = _baseUrl + path;var json = JsonSerializer.Serialize(body, JsonOptions);@@ -75,7 +82,7 @@ internal class FirecrawlHttpClientreturn request;}- return await ExecuteWithRetryAsync<T>(BuildRequest, cancellationToken);+ return await ExecuteWithRetryAsync<T>(BuildRequest, cancellationToken, minimumTimeout);}internal async Task<T> PostMultipartAsync<T>(@@ -207,8 +214,13 @@ internal class FirecrawlHttpClientprivate async Task<T> ExecuteWithRetryAsync<T>(Func<HttpRequestMessage> requestBuilder,- CancellationToken cancellationToken)+ CancellationToken cancellationToken,+ TimeSpan? minimumTimeout = null){+ TimeSpan? timeout = _timeout is { } configured && minimumTimeout > configured+ ? minimumTimeout+ : _timeout;+var attempt = 0;while (true)@@ -216,12 +228,15 @@ internal class FirecrawlHttpClient// Build a fresh request for each attempt (HttpRequestMessage can only be sent once,// and multipart content is not cheaply cloneable).using var request = requestBuilder();+ using var timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);+ if (timeout.HasValue)+ timeoutCts.CancelAfter(timeout.Value);HttpResponseMessage? response = null;try{- response = await _httpClient.SendAsync(request, cancellationToken);- var bodyStr = await response.Content.ReadAsStringAsync(cancellationToken);+ response = await _httpClient.SendAsync(request, timeoutCts.Token);+ var bodyStr = await response.Content.ReadAsStringAsync(timeoutCts.Token);if (response.IsSuccessStatusCode){@@ -255,6 +270,12 @@ internal class FirecrawlHttpClient{throw;}+ catch (OperationCanceledException ex) when (timeout.HasValue && !cancellationToken.IsCancellationRequested)+ {+ throw new TaskCanceledException(+ $"The request was canceled due to the configured timeout of {timeout.Value.TotalSeconds} seconds elapsing.",+ new TimeoutException(ex.Message, ex));+ }catch (OperationCanceledException){throw;diff --git a/apps/dot-net-sdk/Firecrawl/Models/InteractModels.cs b/apps/dot-net-sdk/Firecrawl/Models/InteractModels.csnew file mode 100644index 000000000..920a89967--- /dev/null+++ b/apps/dot-net-sdk/Firecrawl/Models/InteractModels.cs@@ -0,0 +1,75 @@+using System.Text.Json.Serialization;++namespace Firecrawl.Models;++/// <summary>+/// Result of running code or a prompt in a scrape job's browser session.+/// </summary>+public class BrowserExecuteResponse+{+ [JsonPropertyName("success")]+ public bool Success { get; set; }++ /// <summary>+ /// Chrome DevTools Protocol URL for connecting to the browser session.+ /// </summary>+ [JsonPropertyName("cdpUrl")]+ public string? CdpUrl { get; set; }++ [JsonPropertyName("liveViewUrl")]+ public string? LiveViewUrl { get; set; }++ [JsonPropertyName("interactiveLiveViewUrl")]+ public string? InteractiveLiveViewUrl { get; set; }++ /// <summary>+ /// Agent output when a prompt was used.+ /// </summary>+ [JsonPropertyName("output")]+ public string? Output { get; set; }++ [JsonPropertyName("stdout")]+ public string? Stdout { get; set; }++ [JsonPropertyName("result")]+ public string? Result { get; set; }++ [JsonPropertyName("stderr")]+ public string? Stderr { get; set; }++ [JsonPropertyName("exitCode")]+ public int? ExitCode { get; set; }++ /// <summary>+ /// Whether execution was killed by the timeout or the system.+ /// </summary>+ [JsonPropertyName("killed")]+ public bool? Killed { get; set; }++ /// <summary>+ /// Whether the captured output was truncated.+ /// </summary>+ [JsonPropertyName("truncated")]+ public bool? Truncated { get; set; }++ [JsonPropertyName("error")]+ public string? Error { get; set; }+}++/// <summary>+/// Result of stopping a scrape job's browser session.+/// </summary>+public class BrowserDeleteResponse+{+ [JsonPropertyName("success")]+ public bool Success { get; set; }++ [JsonPropertyName("sessionDurationMs")]+ public long? SessionDurationMs { get; set; }++ [JsonPropertyName("creditsBilled")]+ public int? CreditsBilled { get; set; }++ [JsonPropertyName("error")]+ public string? Error { get; set; }+}diff --git a/apps/dot-net-sdk/README.md b/apps/dot-net-sdk/README.mdindex fe7f237b9..b89e10e6d 100644--- a/apps/dot-net-sdk/README.md+++ b/apps/dot-net-sdk/README.md@@ -112,6 +112,33 @@ var doc = await client.ScrapeAsync("https://example.com/restaurant/123",Console.WriteLine(doc.Menu);```+### Interact++Run code or a natural-language prompt in the browser session of a scrape job,+then stop the session when you are done. The job ID is the scraped document's+`metadata.scrapeId`.++```csharp+var doc = await client.ScrapeAsync("https://example.com");+var scrapeId = doc.Metadata!["scrapeId"].ToString()!;++// Run code (language: "node" by default, or "python" / "bash")+var run = await client.InteractAsync(scrapeId, "console.log(await page.title())");+Console.WriteLine(run.Stdout); // Example Domain+Console.WriteLine(run.ExitCode); // 0++// Or describe what to do in plain language+var agent = await client.InteractAsync(scrapeId, null, prompt: "Click the first link");+Console.WriteLine(agent.Output);++// Stop the browser session+var stop = await client.StopInteractiveBrowserAsync(scrapeId);+Console.WriteLine(stop.CreditsBilled);+```++`InteractAsync` returns `Stdout`, `Stderr`, `Result`, `ExitCode`, `Killed`, `Truncated`, and `Output` (for prompts),+plus `CdpUrl`, `LiveViewUrl` and `InteractiveLiveViewUrl` for the session. `timeout` is in seconds (1-300, default 30).+### Crawl```csharp