Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

add file atttachments to structured output.

Saurav Pandac18ee5412f3e
diff --git a/browser_use/tools/service.py b/browser_use/tools/service.py
index 5381b023f..350ac1971 100644
--- a/browser_use/tools/service.py
+++ b/browser_use/tools/service.py
@@ -2023,16 +2023,34 @@ Validated Code (after quote fixing):
'Complete task with structured output.',
param_model=StructuredOutputAction[output_model],
)
- async def done(params: StructuredOutputAction):
+ async def done(params: StructuredOutputAction, file_system: FileSystem, available_file_paths: list[str]):
# Exclude success from the output JSON
# Use mode='json' to properly serialize enums at all nesting levels
output_dict = params.data.model_dump(mode='json')
+ attachments: list[str] = []
+
+ # 1. Resolve any explicitly requested files via files_to_display
+ if params.files_to_display:
+ for file_name in params.files_to_display:
+ file_content = file_system.display_file(file_name)
+ if file_content:
+ attachments.append(str(file_system.get_dir() / file_name))
+
+ # 2. Auto-attach any session downloads (browser-downloaded files)
+ # that weren't already covered by files_to_display
+ if available_file_paths:
+ existing = set(attachments)
+ for file_path in available_file_paths:
+ if file_path not in existing:
+ attachments.append(file_path)
+
return ActionResult(
is_done=True,
success=params.success,
extracted_content=json.dumps(output_dict, ensure_ascii=False),
long_term_memory=f'Task completed. Success Status: {params.success}',
+ attachments=attachments,
)
else:
diff --git a/browser_use/tools/views.py b/browser_use/tools/views.py
index 27c4ada6e..50275a421 100644
--- a/browser_use/tools/views.py
+++ b/browser_use/tools/views.py
@@ -87,16 +87,19 @@ class DoneAction(BaseModel):
T = TypeVar('T', bound=BaseModel)
-def _hide_success_from_schema(schema: dict) -> None:
- """Remove 'success' from the JSON schema to avoid field name collisions with user models."""
- schema.get('properties', {}).pop('success', None)
+def _hide_internal_fields_from_schema(schema: dict) -> None:
+ """Remove internal fields from the JSON schema to avoid collisions with user models."""
+ props = schema.get('properties', {})
+ props.pop('success', None)
+ props.pop('files_to_display', None)
class StructuredOutputAction(BaseModel, Generic[T]):
- model_config = ConfigDict(json_schema_extra=_hide_success_from_schema)
+ model_config = ConfigDict(json_schema_extra=_hide_internal_fields_from_schema)
success: bool = Field(default=True, description='True if user_request completed successfully')
data: T = Field(description='The actual output data matching the requested schema')
+ files_to_display: list[str] | None = Field(default=[])
class SwitchTabAction(BaseModel):
diff --git a/tests/ci/test_tools.py b/tests/ci/test_tools.py
index f5b152285..975642c7d 100644
--- a/tests/ci/test_tools.py
+++ b/tests/ci/test_tools.py
@@ -1,9 +1,10 @@
import asyncio
+import json
import tempfile
import time
import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
from pytest_httpserver import HTTPServer
from browser_use.agent.views import ActionResult
@@ -491,3 +492,167 @@ class TestToolsIntegration:
)
selected_value = selected_value_result.get('result', {}).get('value')
assert selected_value == 'option2' # Second Option has value "option2"
+
+
+class TestStructuredOutputDoneWithFiles:
+ """Tests for file handling in structured output done action."""
+
+ async def test_structured_output_done_without_files(self, browser_session, base_url):
+ """Structured output done action works without files (backward compat)."""
+
+ class MyOutput(BaseModel):
+ answer: str = Field(description='The answer')
+
+ tools = Tools(output_model=MyOutput)
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ file_system = FileSystem(temp_dir)
+
+ result = await tools.done(
+ data={'answer': 'hello'},
+ success=True,
+ browser_session=browser_session,
+ file_system=file_system,
+ available_file_paths=[],
+ )
+
+ assert isinstance(result, ActionResult)
+ assert result.is_done is True
+ assert result.success is True
+ output = json.loads(result.extracted_content)
+ assert output == {'answer': 'hello'}
+ assert result.attachments == []
+
+ async def test_structured_output_done_with_files_to_display(self, browser_session, base_url):
+ """Structured output done action resolves files_to_display into attachments."""
+
+ class MyOutput(BaseModel):
+ summary: str
+
+ tools = Tools(output_model=MyOutput)
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ file_system = FileSystem(temp_dir)
+ await file_system.write_file('report.txt', 'some report content')
+
+ result = await tools.done(
+ data={'summary': 'done'},
+ success=True,
+ files_to_display=['report.txt'],
+ browser_session=browser_session,
+ file_system=file_system,
+ available_file_paths=[],
+ )
+
+ assert isinstance(result, ActionResult)
+ assert result.is_done is True
+ assert result.success is True
+ output = json.loads(result.extracted_content)
+ assert output == {'summary': 'done'}
+ assert len(result.attachments) == 1
+ assert result.attachments[0].endswith('report.txt')
+
+ async def test_structured_output_done_auto_attaches_downloads(self, browser_session):
+ """Session downloads are auto-attached even without files_to_display."""
+
+ class MyOutput(BaseModel):
+ url: str
+
+ tools = Tools(output_model=MyOutput)
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ file_system = FileSystem(temp_dir)
+
+ # Simulate a browser-downloaded file via available_file_paths
+ import os
+
+ fake_download = os.path.join(temp_dir, 'tax-bill.pdf')
+ with open(fake_download, 'wb') as f:
+ f.write(b'%PDF-1.4 fake pdf content')
+
+ result = await tools.done(
+ data={'url': 'https://example.com/bill.pdf'},
+ success=True,
+ browser_session=browser_session,
+ file_system=file_system,
+ available_file_paths=[fake_download],
+ )
+
+ assert isinstance(result, ActionResult)
+ assert result.is_done is True
+ output = json.loads(result.extracted_content)
+ assert output == {'url': 'https://example.com/bill.pdf'}
+ # The download should be auto-attached
+ assert len(result.attachments) == 1
+ assert result.attachments[0] == fake_download
+
+ async def test_structured_output_done_deduplicates_attachments(self, browser_session):
+ """Downloads already covered by files_to_display are not duplicated."""
+
+ class MyOutput(BaseModel):
+ status: str
+
+ tools = Tools(output_model=MyOutput)
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ file_system = FileSystem(temp_dir)
+ await file_system.write_file('report.txt', 'content here')
+
+ # The same file appears in both files_to_display and available_file_paths
+ fs_path = str(file_system.get_dir() / 'report.txt')
+
+ result = await tools.done(
+ data={'status': 'ok'},
+ success=True,
+ files_to_display=['report.txt'],
+ browser_session=browser_session,
+ file_system=file_system,
+ available_file_paths=[fs_path],
+ )
+
+ assert isinstance(result, ActionResult)
+ # Should have exactly 1 attachment, not 2
+ assert len(result.attachments) == 1
+ assert result.attachments[0] == fs_path
+
+ async def test_structured_output_done_nonexistent_file_ignored(self, browser_session):
+ """Files that don't exist in FileSystem are not included via files_to_display."""
+
+ class MyOutput(BaseModel):
+ value: int
+
+ tools = Tools(output_model=MyOutput)
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ file_system = FileSystem(temp_dir)
+
+ result = await tools.done(
+ data={'value': 42},
+ success=True,
+ files_to_display=['nonexistent.txt'],
+ browser_session=browser_session,
+ file_system=file_system,
+ available_file_paths=[],
+ )
+
+ assert isinstance(result, ActionResult)
+ assert result.is_done is True
+ output = json.loads(result.extracted_content)
+ assert output == {'value': 42}
+ # nonexistent file should not appear in attachments
+ assert result.attachments == []
+
+ async def test_structured_output_schema_hides_internal_fields(self):
+ """The JSON schema for StructuredOutputAction hides success and files_to_display."""
+ from browser_use.tools.views import StructuredOutputAction
+
+ class MyOutput(BaseModel):
+ name: str
+
+ schema = StructuredOutputAction[MyOutput].model_json_schema()
+ top_level_props = schema.get('properties', {})
+ assert 'success' not in top_level_props
+ assert 'files_to_display' not in top_level_props
+ # data should still be present
+ assert 'data' in top_level_props
+