ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

2026-08-20 13:12:50 +00:00
commit b119135836
10275 changed files with 3284984 additions and 0 deletions
@@ -0,0 +1,93 @@
+---
+title: "Add Tools"
+description: ""
+icon: "plus"
+mode: "wide"
+---
+
+
+Examples:
+- deterministic clicks
+- file handling
+- calling APIs
+- human-in-the-loop
+- browser interactions
+- calling LLMs
+- get 2fa codes
+- send emails
+- Playwright integration (see [GitHub example](https://github.com/browser-use/browser-use/blob/main/examples/browser/playwright_integration.py))
+- ...
+
+Simply add `@tools.action(...)` to your function.
+
+```python
+from browser_use import Tools, Agent
+
+tools = Tools()
+
+@tools.action(description='Ask human for help with a question')
+def ask_human(question: str) -> ActionResult:
+    answer = input(f'{question} > ')
+    return f'The human responded with: {answer}'
+```
+
+```python
+agent = Agent(task='...', llm=llm, tools=tools)
+```
+
+- **`description`** *(required)* - What the tool does, the LLM uses this to decide when to call it.
+- **`allowed_domains`** - List of domains where tool can run (e.g. `['*.example.com']`), defaults to all domains
+
+The Agent fills your function parameters based on their names, type hints, & defaults.
+
+
+## Available Objects
+
+Your function has access to these objects:
+
+- **`browser_session: BrowserSession`** - Current browser session for CDP access
+- **`cdp_client`** - Direct Chrome DevTools Protocol client
+- **`page_extraction_llm: BaseChatModel`** - The LLM you pass into agent. This can be used to do a custom llm call here.
+- **`file_system: FileSystem`** - File system access
+- **`available_file_paths: list[str]`** - Available files for upload/processing
+- **`has_sensitive_data: bool`** - Whether action contains sensitive data
+
+## Pydantic Input
+
+You can use Pydantic for the tool parameters:
+
+```python
+from pydantic import BaseModel
+
+class Cars(BaseModel):
+    name: str = Field(description='The name of the car, e.g. "Toyota Camry"')
+    price: int = Field(description='The price of the car as int in USD, e.g. 25000')
+
+@tools.action(description='Save cars to file')
+def save_cars(cars: list[Cars]) -> str:
+    with open('cars.json', 'w') as f:
+        json.dump(cars, f)
+    return f'Saved {len(cars)} cars to file'
+
+task = "find cars and save them to file"
+```
+## Domain Restrictions
+
+Limit tools to specific domains:
+
+```python
+@tools.action(
+    description='Fill out banking forms',
+    allowed_domains=['https://mybank.com']
+)
+def fill_bank_form(account_number: str) -> str:
+    # Only works on mybank.com
+    return f'Filled form for account {account_number}'
+```
+
+## Advanced Example
+
+For a comprehensive example of custom tools with Playwright integration, see:
+**[Playwright Integration Example](https://github.com/browser-use/browser-use/blob/main/examples/browser/playwright_integration.py)**
+
+This shows how to create custom actions that use Playwright's precise browser automation alongside Browser-Use.
@@ -0,0 +1,42 @@
+---
+title: "Available Tools"
+description: "Here is the [source code](https://github.com/browser-use/browser-use/blob/main/browser_use/tools/service.py) for the default tools:"
+icon: "list"
+mode: "wide"
+---
+
+
+
+
+### Navigation & Browser Control
+- **`search_google`** - Search queries in Google
+- **`go_to_url`** - Navigate to URLs  
+- **`go_back`** - Go back in browser history
+- **`wait`** - Wait for specified seconds
+
+### Page Interaction
+- **`click_element_by_index`** - Click elements by their index
+- **`input_text`** - Input text into form fields
+- **`upload_file_to_element`** - Upload files to file inputs
+- **`scroll`** - Scroll the page up/down
+- **`scroll_to_text`** - Scroll to specific text on page
+- **`send_keys`** - Send special keys (Enter, Escape, etc.)
+
+### Tab Management  
+- **`switch_tab`** - Switch between browser tabs
+- **`close_tab`** - Close browser tabs
+
+### Content Extraction
+- **`extract_structured_data`** - Extract data from webpages using LLM
+
+### Form Controls
+- **`get_dropdown_options`** - Get dropdown option values
+- **`select_dropdown_option`** - Select dropdown options
+
+### File Operations
+- **`write_file`** - Write content to files
+- **`read_file`** - Read file contents  
+- **`replace_file_str`** - Replace text in files
+
+### Task Completion
+- **`done`** - Complete the task (always available)
@@ -0,0 +1,31 @@
+---
+title: "Basics"
+description: "Tools are the functions that the agent has to interact with the world."
+icon: "play"
+mode: "wide"
+---
+
+
+## Quick Example
+
+
+```python
+from browser_use import Tools, ActionResult, Browser
+
+tools = Tools()
+
+@tools.action('Ask human for help with a question')
+def ask_human(question: str, browser: Browser) -> ActionResult:
+    answer = input(f'{question} > ')
+    return f'The human responded with: {answer}'
+
+agent = Agent(
+    task='Ask human for help',
+    llm=llm,
+    tools=tools,
+)
+```
+
+<Note>
+Use `browser` parameter in tools for deterministic [Actor](/customize/actor/basics) actions.
+</Note>
@@ -0,0 +1,14 @@
+---
+title: "Remove Tools"
+description: "You can exclude default tools:"
+icon: "minus"
+mode: "wide"
+---
+
+
+```python
+from browser_use import Tools
+
+tools = Tools(exclude_actions=['search_google', 'wait'])
+agent = Agent(task='...', llm=llm, tools=tools)
+```
@@ -0,0 +1,79 @@
+---
+title: "Tool Response"
+description: ""
+icon: "arrow-turn-down-left"
+mode: "wide"
+---
+
+Tools return results using `ActionResult` or simple strings.
+
+## Return Types
+
+```python
+@tools.action('My tool')
+def my_tool() -> str:
+    return "Task completed successfully"
+
+@tools.action('Advanced tool')
+def advanced_tool() -> ActionResult:
+    return ActionResult(
+        extracted_content="Main result",
+        long_term_memory="Remember this info",
+        error="Something went wrong",
+        is_done=True,
+        success=True,
+        attachments=["file.pdf"],
+    )
+```
+
+## ActionResult Properties
+
+- `extracted_content` (default: `None`) - Main result passed to LLM, this is equivalent to returning a string.
+- `include_extracted_content_only_once` (default: `False`) - Set to `True` for large content to include it only once in the LLM input.
+- `long_term_memory` (default: `None`) - This is always included in the LLM input for all future steps.
+- `error` (default: `None`) - Error message, we catch exceptions and set this automatically. This is always included in the LLM input.
+- `is_done` (default: `False`) - Tool completes entire task
+- `success` (default: `None`) - Task success (only valid with `is_done=True`)
+- `attachments` (default: `None`) - Files to show user
+- `metadata` (default: `None`) - Debug/observability data
+
+## Why `extracted_content` and `long_term_memory`?
+With this you control the context for the LLM.
+
+### 1. Include short content always in context
+```python
+def simple_tool() -> str:
+    return "Hello, world!"  # Keep in context for all future steps 
+```
+
+### 2. Show long content once, remember subset in context
+```python
+return ActionResult(
+    extracted_content="[500 lines of product data...]",     # Shows to LLM once
+    include_extracted_content_only_once=True,               # Never show full output again
+    long_term_memory="Found 50 products"        # Only this in future steps
+)
+```
+We save the full `extracted_content` to files which the LLM can read in future steps.
+
+### 3. Dont show long content, remember subset in context
+```python
+return ActionResult(
+    extracted_content="[500 lines of product data...]",      # The LLM never sees this because `long_term_memory` overrides it and `include_extracted_content_only_once` is not used
+    long_term_memory="Saved user's favorite products",      # This is shown to the LLM in future steps
+)
+```
+
+## Terminating the Agent
+
+Set `is_done=True` to stop the agent completely. Use when your tool finishes the entire task:
+
+```python
+@tools.action(description='Complete the task')
+def finish_task() -> ActionResult:
+    return ActionResult(
+        extracted_content="Task completed!",
+        is_done=True,        # Stops the agent
+        success=True         # Task succeeded 
+    )
+```