开源AI工作流：AI Search Agents at Scale

Requirements

• R >= 4.0
• Python 3.12 or 3.13 (managed via conda; 3.14 currently emits upstream pydantic.v1 warnings in LangChain)
• reticulate, jsonlite, rlang

Optional: - Claude Code CLI (for asa_audit() with backend = "claude_code") - processx (recommended for robust CLI invocations; base system2() fallback is used if unavailable) - Tor + stealth Chrome support (requires system Tor plus Python packages undetected-chromedriver and stem, installed by asa::build_backend())

Installation

```r

Install from GitHub

devtools::install_github("cjerzak/asa-software/asa")

Or install locally

devtools::install("path/to/asa") ```

First time only: build the Python backend

asa::build_backend()

Rebuild the conda environment

asa::build_backend(conda_env = "asa_env", python_version = "3.12", force = TRUE) ```

Quick Start

```r

Configuration

Agent Options

agent <- asa::initialize_agent(
  backend = "openai",
  model = "gpt-4.1-mini",
  proxy = NA,                           # NA=auto from env; NULL=disable; set socks5h://127.0.0.1:9050 for Tor
  timeout = 120,                        # Request timeout in seconds
  rate_limit = 0.1                      # Requests per second (conservative default)
)

Configuration Classes

The package provides typed configuration classes for organized settings management:

```r

Create temporal filtering options

temporal <- asa::temporal_options( time_filter = "y", # DuckDuckGo time filter after = "2023-01-01", # ISO 8601 date before = "2024-12-01" )

Create search options

search <- asa::search_options( max_retries = 5, inter_search_delay = 1.0 )

Create unified configuration

config <- asa::asa_config( backend = "openai", model = "gpt-4.1-mini", workers = 4, temporal = temporal, search = search )

Optional Webpage Reading

When enabled, the agent can open full webpages (not just search snippets) and extract the most relevant excerpts. This is disabled by default and must be explicitly turned on per call or via search_options(). Relevance selection uses embeddings when available (local sentence-transformers or OpenAI embeddings via OPENAI_API_KEY), otherwise falls back to lexical overlap. Within a single run, repeated opens of the same URL are cached to avoid re-fetching.

```r

Enable optional webpage reading with embedding-based relevance

search <- asa::search_options( allow_read_webpages = TRUE, webpage_relevance_mode = "embeddings", webpage_embedding_provider = "openai", webpage_embedding_model = "text-embedding-3-small", # Optional: allow larger excerpts (defaults are conservative) webpage_max_chars = 30000, webpage_max_chunks = 10, webpage_chunk_chars = 2000 )

result <- asa::run_task( "Find the exact wording of the mission statement and quote it.", config = asa::asa_config(search = search) )

**In the agent trace:** Each opened page appears as an `OpenWebpage` tool message in `result$trace_json` (preferred) or `result$raw_output`. The tool output is plain text like:

Relevant excerpts:

[1] ... ```

Memory Folding Configuration

Memory folding compresses older conversation messages into summaries, enabling longer research sessions without exceeding context limits. This follows the DeepAgent paper methodology.

```r

Custom memory settings for extended research sessions

agent <- asa::initialize_agent( backend = "openai", model = "gpt-4.1-mini", use_memory_folding = TRUE, # Enable memory compression (default) memory_threshold = 6, # Fold after 6 messages (default: 10) memory_keep_recent = 3 # Keep 3 recent exchanges after fold (default: 4) )

Search Configuration

Fine-tune search behavior globally:

```r

Configure search parameters for reliability

asa::configure_search( max_results = 15, # Results per search (default: 10) timeout = 20, # Request timeout in seconds (default: 30) max_retries = 5, # Retry attempts (default: 3) retry_delay = 3, # Seconds between retries (default: 2) backoff_multiplier = 2.0, # Exponential backoff factor (default: 1.5) inter_search_delay = 3.0 # Delay between searches in seconds (default: 1.5) )

You can also push settings without reinitializing:

asa::configure_tor_registry(registry_path = tor_cfg$registry_path) ```

Even more conservative settings for 5000+ queries/day

asa::configure_search(inter_search_delay = 4.0) agent <- asa::initialize_agent(rate_limit = 0.05) ```

Optional when using cookie auth from a custom Tor instance:

export ASA_TOR_CONTROL_COOKIE="/path/to/control_auth_cookie"

R -q -e 'devtools::test("asa", filter = "tor-proxy-integration")' ```

If ASA_RUN_TOR_TESTS=true and Tor is not reachable, these tests fail fast by design.

Cost considerations: - Web search (DuckDuckGo, Wikipedia): Free - LLM costs vary by backend: OpenAI ~$0.01-0.10/task, Groq ~$0.001/task

Reference

Running Tor integration tests

Tor integration tests are opt-in outside CI and verify: - egress is routed through Tor (IsTor=true), - Tor SOCKS/control ports are reachable, - control-port rotation sanity (NEWNYM path) works.

```bash export ASA_RUN_TOR_TESTS=true export ASA_TOR_TEST_PROXY="socks5h://127.0.0.1:9050" export ASA_TOR_TEST_CONTROL_PORT="9051"

Enable debug logging for troubleshooting

asa::configure_search_logging("DEBUG") # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL ```

Troubleshooting

Rate limited or CAPTCHA blocks? - The package now has adaptive rate limiting (enabled by default) that automatically slows down on errors - For persistent issues, increase delays: configure_search(inter_search_delay = 4.0) - Enable debug logging to see what's happening: configure_search_logging("DEBUG") - Use Tor proxy for IP rotation: rotate_tor_circuit() - Using Tor + stealth Chrome? Rebuild the backend so undetected-chromedriver and stem are installed (asa::build_backend(force = TRUE)), and set TOR_CONTROL_PORT per worker (env is read at call time).

API key not recognized? ```r