% tinyrox says don't edit this manually, but it can't stop you!
\name{agent}
\alias{agent}
\title{Chat with tool use (agentic mode)}
\usage{
agent(prompt, tools = list(), tool_handler = NULL, system = NULL, model = NULL,
      provider = c("anthropic", "openai", "moonshot", "ollama"),
      max_turns = 20L, verbose = TRUE, history = NULL, history_callback = NULL,
      cache = c("none", "5m", "1h"), thinking_budget_tokens = NULL, ...)
}
\arguments{
\item{prompt}{Character. The user message.}

\item{tools}{List. Tool definitions (from mcp_tools_for_claude or manual).}

\item{tool_handler}{Function. Called with (name, args), returns result string.}

\item{system}{Character. System prompt.}

\item{model}{Character. Model name.}

\item{provider}{Character. Provider: "anthropic", "openai", "moonshot",
or "ollama".}

\item{max_turns}{Integer. Maximum tool-use turns (default: 20).}

\item{verbose}{Logical. Print tool calls and results.}

\item{history}{List or NULL. Previous conversation history to continue from.}

\item{history_callback}{Function or NULL. Called as
\code{history_callback(history)} after each assistant message is
appended and after each tool result is appended. Lets callers
snapshot intermediate state so an interrupt mid-turn doesn't lose
the work that was already done. Errors raised inside the callback
are swallowed so telemetry/snapshotting can't break a turn.}

\item{cache}{Character. Anthropic prompt caching for the system
message: \code{"none"} (default), \code{"5m"}, or \code{"1h"}
ephemeral TTL. Anthropic-only; warns and degrades to \code{"none"}
for other providers.}

\item{thinking_budget_tokens}{Integer or NULL. Anthropic extended
thinking budget; must be at least 1024 and less than
\code{max_tokens}. Anthropic-only; ignored with a warning for
other providers.}

\item{...}{Additional parameters passed to the API.}
}
\value{
List with final response and conversation history. The
  returned \code{$usage} carries cumulative \code{input_tokens},
  \code{output_tokens}, \code{total_tokens}, and \code{cost} (USD
  scalar, derived from the bundled price snapshot; \code{0} for
  Ollama; \code{NA_real_} for models not in the snapshot). It also
  carries cumulative cache activity: \code{cache_read_input_tokens}
  (Anthropic cache reads plus OpenAI/Moonshot cached prompt tokens),
  \code{cache_creation_input_tokens} (total Anthropic cache writes),
  and the per-TTL split \code{cache_creation$ephemeral_5m_input_tokens}
  / \code{cache_creation$ephemeral_1h_input_tokens}. Passing this
  \code{$usage} back to \code{\link{usage_cost}} recomputes the same
  \code{cost}.
}
\description{
Send a prompt to an LLM with tools. Automatically handles tool calls
in a loop until the model responds with text only.
}
\examples{
\dontrun{
# With MCP server
conn <- mcp_connect("r", "mcp_server.R")
tools <- mcp_tools_for_claude(conn)

result <- agent(
  "What files are in the current directory?",
  tools = tools,
  tool_handler = function(name, args) {
    mcp_call(conn, name, args)$text
  }
)
}
}
