Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.cs
new file mode 100644
index 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.cs
index 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 FirecrawlClient
private 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 FirecrawlClient
return 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.cs
index 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 FirecrawlHttpClient
private 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 FirecrawlHttpClient
return 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 FirecrawlHttpClient
private 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.cs
new file mode 100644
index 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.md
index 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