% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/provider-aws.R
\name{chat_aws_bedrock}
\alias{chat_aws_bedrock}
\alias{models_aws_bedrock}
\title{Chat with an AWS bedrock model}
\usage{
chat_aws_bedrock(
  system_prompt = NULL,
  base_url = NULL,
  model = NULL,
  api = NULL,
  profile = NULL,
  cache = c("auto", "5m", "1h", "none"),
  params = NULL,
  api_args = list(),
  api_headers = character(),
  echo = NULL
)

models_aws_bedrock(profile = NULL, base_url = NULL, api = NULL)
}
\arguments{
\item{system_prompt}{A system prompt to set the behavior of the assistant.}

\item{base_url}{The base URL to the endpoint; the default is the standard
endpoint for the selected \code{api} and your region, matching the official
SDKs' endpoint override environment variables:
\code{AWS_ENDPOINT_URL_BEDROCK_RUNTIME} for \code{"converse"}, and
\code{AWS_ENDPOINT_URL_BEDROCK_MANTLE} for \code{"messages"} and \code{"responses"}
(which append their API-specific path to the override).
\code{models_aws_bedrock()} talks to a different AWS service, so it honors
\code{AWS_ENDPOINT_URL_BEDROCK} instead.}

\item{model}{The model to use for the chat (defaults to "us.anthropic.claude-sonnet-5").
We regularly update the default, so we strongly recommend explicitly specifying a model for anything other than casual use.
Use \code{models_models_aws_bedrock()} to see all options.
.

While ellmer provides a default model, there's no guarantee that you'll
have access to it, so you'll need to specify a model that you can.
If you're using \href{https://aws.amazon.com/blogs/machine-learning/getting-started-with-cross-region-inference-in-amazon-bedrock/}{cross-region inference},
you'll need to use the inference profile ID, e.g.
\code{model="us.anthropic.claude-sonnet-5"}.}

\item{api}{Which Bedrock API to use: \code{"converse"}, \code{"messages"}, or
\code{"responses"}. The default, \code{NULL}, picks the API from \code{model}, falling
back to \code{"converse"} for unrecognized models.

See details below.}

\item{profile}{AWS profile to use.}

\item{cache}{How long to cache inputs? The default, \code{"auto"}, enables
caching with a 5-minute TTL for models known to support it (Anthropic
Claude and Amazon Nova) and disables caching for all other models.
Set to \code{"5m"} or \code{"1h"} to force caching on, or \code{"none"} to disable it.

Not supported when \code{api = "responses"}, which caches automatically.

See details below.}

\item{params}{Common model parameters, usually created by \code{\link[=params]{params()}}.}

\item{api_args}{Named list of arbitrary extra arguments appended to the body
of every chat API call. Use \code{params} for common parameters. Model-specific
inference parameters can be provided using the
\code{additionalModelRequestFields} field (\code{api = "converse"} only), for example
to enable thinking effort in Anthropic Claude models:

\if{html}{\out{<div class="sourceCode R">}}\preformatted{api_args = list(
  additionalModelRequestFields = list(
    thinking = list(type = "enabled", budget_tokens = 4000)
  )
)
}\if{html}{\out{</div>}}

See \url{https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-call.html}
for more details.}

\item{api_headers}{Named character vector of arbitrary extra headers appended
to every chat API call.}

\item{echo}{One of the following options:
\itemize{
\item \code{none}: don't emit any output (default when running in a function).
\item \code{output}: echo text and tool-calling output as it streams in (default
when running at the console).
\item \code{all}: echo all input and output.
}

Note this only affects the \code{chat()} method.}
}
\value{
A \link{Chat} object.
}
\description{
\ifelse{html}{\figure{support-official.svg}{options: alt='[Official supported provider]'}}{\strong{[Official supported provider]}}

\href{https://aws.amazon.com/bedrock/}{AWS Bedrock} provides a number of
language models, including those from Anthropic's
\href{https://aws.amazon.com/bedrock/claude/}{Claude}. Most are served through
the Bedrock
\href{https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html}{Converse API},
with some only available through the Anthropic Messages or OpenAI Responses
APIs; see the \code{api} argument for details.
\subsection{APIs and endpoints}{

Bedrock serves models from two endpoints, and \code{api} selects which one to use
and which request format to send:
\itemize{
\item \code{"converse"} uses the Converse API on the \code{bedrock-runtime} endpoint. This
reaches the great majority of Bedrock models, and is what ellmer has always
used.
\item \code{"messages"} uses the Anthropic Messages API on the \code{bedrock-mantle}
endpoint. Only Claude models are available here, but it includes some (like
Claude Mythos) that Converse does not serve at all.
\item \code{"responses"} uses the OpenAI Responses API on the \code{bedrock-mantle}
endpoint. This reaches OpenAI and xAI models that Converse can't serve,
typically newer models that Converse hasn't picked up yet. Note that mantle
serves newer models from \verb{/openai/v1} and older open-weight models like
gpt-oss from \verb{/v1}; ellmer uses the former, so reaching the latter needs
an explicit \code{base_url}. They're all available through \code{"converse"} anyway.
}

By default ellmer picks the API from \code{model}, using \code{"converse"} whenever
it can serve the model and for any model ellmer doesn't recognize. Set \code{api}
explicitly to override this.

The set of models that need mantle shrinks over time as AWS adds them to
Converse, so a model that needs \code{"responses"} today may route to
\code{"converse"} in a later ellmer release. Note also that Converse usually
needs an inference profile ID (\code{"us.openai.gpt-5.6-sol"}) while mantle wants
the bare model ID (\code{"openai.gpt-5.6-sol"}); ellmer strips the prefix for
mantle, so the inference profile ID works with either and is the safer
choice.

Note that the two endpoints have separate token quotas, so moving a model
from one to the other changes which quota it consumes.
}

\subsection{Authentication}{

\code{chat_aws_bedrock()} uses \{paws.common\} to resolve credentials,
trying the following strategies in order:
\itemize{
\item A bearer token set in the \code{AWS_BEARER_TOKEN_BEDROCK} or
\code{AWS_BEARER_TOKEN} environment variable. This is used by enterprise
API gateways that issue API keys instead of IAM credentials. See the
\href{https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-use.html}{AWS documentation}
for details.
\item Standard IAM credentials resolved from environment variables, AWS
config files, SSO, or instance metadata. See
\url{https://www.paws-r-sdk.com/#credentials} for details. If your org
uses AWS SSO, you'll need to run \verb{aws sso login} at the terminal.
}
}

\subsection{Prompt caching}{

Bedrock supports
\href{https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html}{prompt caching}
via cache checkpoints. When caching is enabled, ellmer places cache
checkpoints on the system prompt and the last turn, so that the
conversation history is cached across turns.

By default (\code{cache = "auto"}), caching is enabled for models known to
support it (Anthropic Claude and Amazon Nova) and disabled for all other
models. You can also set \code{cache} to \code{"5m"} or \code{"1h"} to force a specific
TTL, or \code{"none"} to disable caching entirely. Note that individual models
may have minimum input token thresholds before caching takes effect.

Note that \code{\link[=token_usage]{token_usage()}} does not currently reflect the cost of writing
to the cache, which is priced at a premium over regular input tokens.
Cache read savings are reported correctly.
}
}
\examples{
\dontrun{
# Basic usage
chat <- chat_aws_bedrock()
chat$chat("Tell me three jokes about statisticians")
}
}
\seealso{
Other chatbots:
\code{\link[=chat_anthropic]{chat_anthropic()}},
\code{\link[=chat_azure_openai]{chat_azure_openai()}},
\code{\link[=chat_cloudflare]{chat_cloudflare()}},
\code{\link[=chat_databricks]{chat_databricks()}},
\code{\link[=chat_deepseek]{chat_deepseek()}},
\code{\link[=chat_github]{chat_github()}},
\code{\link[=chat_google_gemini]{chat_google_gemini()}},
\code{\link[=chat_groq]{chat_groq()}},
\code{\link[=chat_huggingface]{chat_huggingface()}},
\code{\link[=chat_lmstudio]{chat_lmstudio()}},
\code{\link[=chat_mistral]{chat_mistral()}},
\code{\link[=chat_ollama]{chat_ollama()}},
\code{\link[=chat_openai]{chat_openai()}},
\code{\link[=chat_openai_compatible]{chat_openai_compatible()}},
\code{\link[=chat_openrouter]{chat_openrouter()}},
\code{\link[=chat_perplexity]{chat_perplexity()}},
\code{\link[=chat_portkey]{chat_portkey()}},
\code{\link[=chat_posit]{chat_posit()}}
}
\concept{chatbots}
