Skip to content

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

Add output format for Code Use

kalil0321e7d62598a850
diff --git a/docs/customize/code-agent/output-format.mdx b/docs/customize/code-agent/output-format.mdx
new file mode 100644
index 000000000..438a2fbfb
--- /dev/null
+++ b/docs/customize/code-agent/output-format.mdx
@@ -0,0 +1,194 @@
+---
+title: "Output Format"
+description: "Understanding CodeAgent return values and how to access execution history"
+icon: "arrow-right-to-bracket"
+mode: "wide"
+---
+
+## NotebookSession
+
+The `run()` method returns a `NotebookSession` object containing all executed code cells and their results:
+
+```python
+session = await agent.run()
+
+# Access basic properties
+session.id # Unique session identifier
+session.cells # List of CodeCell objects
+session.current_execution_count # Total number of executed cells
+session.namespace # Dictionary with all variables from execution
+
+# Helper methods
+session.get_cell(cell_id) # Get a specific cell by ID
+session.get_latest_cell() # Get the most recently executed cell
+```
+
+## CodeCell Properties
+
+Each cell in `session.cells` represents one executed code block:
+
+```python
+for cell in session.cells:
+ cell.id # Unique cell identifier
+ cell.cell_type # 'code' or 'markdown'
+ cell.source # The code that was executed
+ cell.output # Output from code execution (if any)
+ cell.execution_count # Execution order number
+ cell.status # 'pending', 'running', 'success', or 'error'
+ cell.error # Error message if execution failed
+ cell.browser_state # Browser state after execution
+```
+
+## Accessing Results
+
+### Basic Usage
+
+```python
+session = await agent.run()
+
+# Iterate through all executed cells
+for cell in session.cells:
+ print(f"Cell {cell.execution_count}:")
+ print(f" Code: {cell.source}")
+ if cell.error:
+ print(f" Error: {cell.error}")
+ elif cell.output:
+ print(f" Output: {cell.output}")
+ print(f" Status: {cell.status}")
+
+# Get the last cell
+last_cell = session.get_latest_cell()
+if last_cell:
+ print(f"Last output: {last_cell.output}")
+
+# Access variables from the execution namespace
+products = session.namespace.get('products', [])
+print(f"Extracted {len(products)} products")
+```
+
+### Checking Task Completion
+
+When the agent calls `done()`, the result is stored in the namespace:
+
+```python
+session = await agent.run()
+
+# Check if task was completed
+task_done = session.namespace.get('_task_done', False)
+task_result = session.namespace.get('_task_result')
+task_success = session.namespace.get('_task_success')
+
+if task_done:
+ print(f"Task completed: {task_success}")
+ print(f"Result: {task_result}")
+```
+
+### Getting All Outputs
+
+```python
+session = await agent.run()
+
+# Get all outputs (excluding errors)
+outputs = [cell.output for cell in session.cells if cell.output]
+
+# Get all errors
+errors = [cell.error for cell in session.cells if cell.error]
+
+# Get successful cells only
+successful_cells = [cell for cell in session.cells if cell.status == 'success']
+```
+
+## History Property
+
+For compatibility with evaluation systems, CodeAgent also provides a `history` property that mimics the Agent's history format:
+
+```python
+# Access history property (returns mock AgentHistoryList)
+history = agent.history
+
+# Access the history list
+history.history # List of CodeAgentHistory objects (converted to dict-like objects)
+history.usage # UsageSummary with token usage information
+
+# Access individual history items
+for step in history.history:
+ # Model output (code generated by LLM)
+ if step.model_output:
+ code = step.model_output.model_output
+ full_response = step.model_output.full_response
+
+ # Execution results
+ for result in step.result:
+ output = result.extracted_content
+ error = result.error
+ is_done = result.is_done
+ success = result.success
+
+ # Browser state
+ url = step.state.url
+ title = step.state.title
+ screenshot_path = step.state.screenshot_path
+ screenshot = step.state.get_screenshot() # Returns base64 string
+
+ # Metadata (timing and tokens)
+ if step.metadata:
+ duration = step.metadata.duration_seconds
+ input_tokens = step.metadata.input_tokens
+ output_tokens = step.metadata.output_tokens
+```
+
+## Screenshots
+
+Access screenshot paths using the agent's `screenshot_paths()` method:
+
+```python
+# Get all screenshot paths
+paths = agent.screenshot_paths()
+
+# Get last N screenshots
+last_3 = agent.screenshot_paths(n_last=3)
+```
+
+## Complete Example
+
+```python
+import asyncio
+from browser_use import CodeAgent
+
+async def main():
+ agent = CodeAgent(task="Extract products from example.com")
+ session = await agent.run()
+
+ # Check completion
+ if session.namespace.get('_task_done'):
+ print("✅ Task completed!")
+ print(f"Result: {session.namespace.get('_task_result')}")
+ else:
+ print("⚠️ Task incomplete")
+
+ # Review all code execution
+ print(f"\nExecuted {len(session.cells)} cells:")
+ for i, cell in enumerate(session.cells, 1):
+ print(f"\nCell {i}:")
+ print(f" Status: {cell.status}")
+ if cell.error:
+ print(f" ❌ Error: {cell.error}")
+ elif cell.output:
+ print(f" ✓ Output: {cell.output[:100]}...")
+
+ # Access extracted data
+ if 'products' in session.namespace:
+ products = session.namespace['products']
+ print(f"\n📦 Extracted {len(products)} products")
+
+ # Get screenshots
+ screenshots = agent.screenshot_paths()
+ print(f"\n📸 Captured {len([p for p in screenshots if p])} screenshots")
+
+asyncio.run(main())
+```
+
+## Data Models
+
+See the complete data model definitions in the [CodeAgent views source code](https://github.com/browser-use/browser-use/blob/main/browser_use/code_use/views.py).
+
diff --git a/docs/docs.json b/docs/docs.json
index e4e47e2b2..8c814d4a8 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -168,6 +168,7 @@
"isDefaultOpen": false,
"pages": [
"customize/code-agent/basics",
+ "customize/code-agent/output-format",
"customize/code-agent/exporting",
"customize/code-agent/all-parameters",
"customize/code-agent/example-products"
@@ -332,4 +333,4 @@
"linkedin": "https://linkedin.com/company/browser-use"
}
}
-}
+}
\ No newline at end of file