% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/agent__initialize.R
\name{initialize_agent}
\alias{initialize_agent}
\title{Initialize the ASA Search Agent}
\usage{
initialize_agent(
  agent_backend = NULL,
  backend = NULL,
  model = NULL,
  conda_env = NULL,
  proxy = NA,
  use_browser = ASA_DEFAULT_USE_BROWSER,
  search = NULL,
  use_memory_folding = ASA_DEFAULT_MEMORY_FOLDING,
  memory_threshold = ASA_DEFAULT_MEMORY_THRESHOLD,
  memory_keep_recent = ASA_DEFAULT_MEMORY_KEEP_RECENT,
  fold_char_budget = ASA_DEFAULT_FOLD_CHAR_BUDGET,
  use_observational_memory = ASA_DEFAULT_USE_OBSERVATIONAL_MEMORY,
  om_observation_token_budget = ASA_DEFAULT_OM_OBSERVATION_TOKENS,
  om_reflection_token_budget = ASA_DEFAULT_OM_REFLECTION_TOKENS,
  om_buffer_tokens = ASA_DEFAULT_OM_BUFFER_TOKENS,
  om_buffer_activation = ASA_DEFAULT_OM_BUFFER_ACTIVATION,
  om_block_after = ASA_DEFAULT_OM_BLOCK_AFTER,
  om_async_prebuffer = ASA_DEFAULT_OM_ASYNC_PREBUFFER,
  om_cross_thread_memory = ASA_DEFAULT_OM_CROSS_THREAD_MEMORY,
  rate_limit = ASA_DEFAULT_RATE_LIMIT,
  timeout = ASA_DEFAULT_TIMEOUT,
  tor = tor_options(),
  verbose = TRUE,
  recursion_limit = NULL
)
}
\arguments{
\item{agent_backend}{Agent runtime backend. Use \code{"agent"} (default) for
the built-in ASA LangGraph pipeline, \code{"free-code"} to run the
external free-code agent behind ASA-managed provider and search wrappers,
or \code{"opencode"} to run the OpenCode CLI behind the same ASA-managed
provider and search wrappers.}

\item{backend}{LLM backend to use. One of: "openai", "groq", "xai",
"gemini", "exo", "ollama", "openrouter", "anthropic", "bedrock".
Ollama also supports shorthand like
\code{"ollama-lfm2:24b-a2b"} when \code{model}
is omitted.}

\item{model}{Model identifier (e.g., "gpt-4.1-mini", "llama-3.3-70b-versatile")}

\item{conda_env}{Name of the conda environment with Python dependencies}

\item{proxy}{Proxy URL for search tools.
Use \code{NA} (default) to auto-detect from environment variables
(\code{ASA_PROXY}, \code{HTTP_PROXY}, \code{HTTPS_PROXY}).
Use \code{NULL} to disable proxying.
Use \code{ASA_DEFAULT_PROXY} (or \code{"socks5h://127.0.0.1:9050"}) to route
searches through Tor.}

\item{use_browser}{Enable Selenium browser tier for DuckDuckGo search
(default: TRUE). Set to FALSE to avoid Chromedriver requirements.}

\item{search}{Optional search options (created with \code{\link{search_options}})
used as defaults for \code{\link{run_task}}/\code{\link{asa_enumerate}} when
no \code{asa_config} is provided. This is useful for setting OpenWebpage
tuning knobs (e.g., \code{webpage_max_chars}, \code{webpage_max_chunks},
\code{webpage_chunk_chars}) once when initializing an agent.}

\item{use_memory_folding}{Enable DeepAgent-style memory compression (default: TRUE)}

\item{memory_threshold}{Number of messages before folding triggers (default: 10;
message-count backstop alongside \code{fold_char_budget})}

\item{memory_keep_recent}{Number of recent exchanges to preserve after folding
(default: 4). An exchange is a user turn plus the assistant response,
including any tool calls and tool outputs.}

\item{fold_char_budget}{Total character budget across all messages before
memory folding triggers (default: 30000). Lower values fold more
aggressively; higher values preserve more raw conversation.}

\item{use_observational_memory}{Enable observational memory pipeline.}

\item{om_observation_token_budget}{Token budget for stored observation messages.}

\item{om_reflection_token_budget}{Token budget for reflection summaries.}

\item{om_buffer_tokens}{Token budget for buffered context before reflection.}

\item{om_buffer_activation}{Fraction of buffer usage that triggers reflection.}

\item{om_block_after}{Fraction of context usage where buffering blocks generation.}

\item{om_async_prebuffer}{Whether to pre-buffer observations asynchronously.}

\item{om_cross_thread_memory}{Whether observational memory is shared across threads.}

\item{rate_limit}{Requests per second for rate limiting (default: 0.1)}

\item{timeout}{Request timeout in seconds (default: 120)}

\item{tor}{Tor registry options from \code{\link{tor_options}}. Disable shared
tracking by setting \code{dirty_tor_exists = FALSE}.}

\item{verbose}{Print status messages (default: TRUE)}

\item{recursion_limit}{Optional default maximum number of agent steps to
store in the initialized agent. When \code{NULL} (default), step limits
fall back to mode-specific defaults at run time (memory folding: 100;
standard agent: 20). Per-call \code{run_task(..., recursion_limit = ...)}
overrides this value.}
}
\value{
An object of class \code{asa_agent} containing the initialized agent
  and configuration.
}
\description{
Initializes the Python environment and creates the LangGraph agent with
search tools (Wikipedia, DuckDuckGo). The agent can use multiple LLM
backends and supports DeepAgent-style memory folding.
}
\details{
The agent is created with these tools:
\itemize{
  \item Wikipedia: For looking up encyclopedic information
  \item DuckDuckGo Search: For web searches with a 4-tier fallback system
    (PRIMP -> Selenium -> DDGS library -> raw requests)
  \item OpenWebpage: (Optional) Fetch and extract readable text from a public
    webpage URL. This capability is disabled by default and must be enabled
    per-call (e.g., via \code{run_task(..., allow_read_webpages = TRUE)}).
}

Memory folding (enabled by default) compresses older messages into a summary
to manage context length in long conversations, following the DeepAgent paper.
}
\section{API Keys}{

The following environment variables should be set based on your backend:
\itemize{
  \item OpenAI: \code{OPENAI_API_KEY}
  \item Groq: \code{GROQ_API_KEY}
  \item xAI: \code{XAI_API_KEY}
  \item Gemini: \code{GOOGLE_API_KEY} (or \code{GEMINI_API_KEY})
  \item Anthropic: \code{ANTHROPIC_API_KEY}
  \item Bedrock: \code{AWS_ACCESS_KEY_ID} + \code{AWS_SECRET_ACCESS_KEY}
    (optionally \code{AWS_DEFAULT_REGION}, defaults to "us-east-1")
  \item OpenRouter: \code{OPENROUTER_API_KEY}
  \item Exo: no API key required (local server)
  \item Ollama: no API key required (local server)
}
}

\section{OpenRouter Models}{

When using the \code{"openrouter"} backend, model names must be in
\code{provider/model-name} format. Examples:
\itemize{
  \item \code{"openai/gpt-4o"}
  \item \code{"anthropic/claude-3-sonnet"}
  \item \code{"google/gemma-2-9b-it:free"}
  \item \code{"meta-llama/llama-3-70b-instruct"}
}
See \url{https://openrouter.ai/models} for available models.
}

\examples{
\dontrun{
# Initialize with OpenAI
agent <- initialize_agent(
  backend = "openai",
  model = "gpt-4.1-mini"
)

# Initialize with Groq and custom settings
agent <- initialize_agent(
  backend = "groq",
  model = "llama-3.3-70b-versatile",
  use_memory_folding = FALSE,
  proxy = NULL  # No Tor proxy
)

# Initialize with OpenRouter (access to 100+ models)
agent <- initialize_agent(
  backend = "openrouter",
  model = "anthropic/claude-3-sonnet"  # Note: provider/model format
)

# Initialize with a local Ollama model
agent <- initialize_agent(
  backend = "ollama",
  model = "lfm2:24b-a2b"
)
}

}
\seealso{
\code{\link{run_task}}, \code{\link{run_task_batch}}
}
