Getting started with foundryR

In foundryR: Data Frame Workflows for 'Microsoft Foundry'

fixture_dir <- "getting-started"
recording <- nzchar(Sys.getenv("FOUNDRY_RECORD_DOCS"))
have_fixtures <- dir.exists(fixture_dir) && length(list.files(fixture_dir)) > 0
run_api <- requireNamespace("httptest2", quietly = TRUE) &&
  (recording || have_fixtures)

# Attach foundryR before start_vignette(): httptest2 only sources the package's
# inst/httptest2/start-vignette.R (which sets replay placeholders) from attached
# packages.
library(foundryR)

if (run_api) {
  httptest2::start_vignette(fixture_dir)
}

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = run_api
)

What you need from Azure

foundryR talks to deployed Azure AI Foundry and Azure OpenAI resources. Before writing R code, create or identify:

1. An Azure OpenAI resource or Azure AI Foundry project with an OpenAI endpoint.
2. At least one chat or Responses API deployment, for example gpt-5-nano.
3. An embedding deployment, for example text-embedding-3-small, if you plan to use embeddings.
4. A Content Safety resource if you plan to use moderation, groundedness, or prompt-shield checks.
5. Either API keys or a Microsoft Entra ID token.

In the Azure portal, open your Azure OpenAI resource, then use Keys and Endpoint to copy the endpoint URL and an API key. In Azure AI Foundry, use the deployments page to create model deployments and record their deployment names.

Deployment name vs base model name

The value you pass to model = is the deployment name you chose in Azure, not necessarily the base model name. If you deploy base model gpt-5-nano with deployment name my-gpt4, use model = "my-gpt4" in foundryR. The same rule applies to embedding deployments.

Install foundryR

install.packages("pak")
pak::pak("farach/foundryR")

Configure credentials

Set credentials for the current R session. Credential setup is shown but not run when building this vignette:

library(foundryR)

foundry_set_endpoint(Sys.getenv("AZURE_FOUNDRY_ENDPOINT"))
foundry_set_key("your-api-key")

For persistent local configuration in your own workflow, store = TRUE uses the package configuration file under tools::R_user_dir("foundryR", "config") unless you set the foundryR.config_file option. It does not modify .Renviron. The file is plain text, so prefer session-only credentials or refreshable token providers for production use.

This demonstration instead uses a temporary file and placeholder values, then removes the file and restores the previous options and environment variables:

local({
  config_file <- tempfile("foundryR-config-", fileext = ".json")
  old_options <- options(foundryR.config_file = config_file)
  old_env <- Sys.getenv(
    c("AZURE_FOUNDRY_ENDPOINT", "AZURE_FOUNDRY_KEY"),
    unset = NA_character_
  )
  on.exit({
    options(old_options)
    Sys.unsetenv(names(old_env)[is.na(old_env)])
    keep <- !is.na(old_env)
    if (any(keep)) {
      do.call(Sys.setenv, as.list(old_env[keep]))
    }
    unlink(config_file)
  }, add = TRUE)

  foundry_set_endpoint("https://example.openai.azure.com", store = TRUE)
  foundry_set_key("example-key-not-a-secret", store = TRUE)
})

You can also edit your chosen .Renviron file manually with a text editor. The vignette does not open an editor or write this file. Add values like these, then restart R:

AZURE_FOUNDRY_ENDPOINT=https://<resource-name>.openai.azure.com
AZURE_FOUNDRY_KEY=your-api-key
AZURE_FOUNDRY_MODEL=my-gpt4
AZURE_FOUNDRY_EMBED_MODEL=my-embedding-deployment

Keyless authentication with Microsoft Entra ID

API keys are convenient for local testing. For enterprise environments that already use service principals, managed identity, or Azure role-based access control, use a Microsoft Entra ID bearer token:

foundry_set_token("your-entra-token")

foundryR sends the token in the Authorization header. If both a token and an API key are configured, the token takes precedence for supported calls.

Validate setup

These checks contact your configured Azure resource and are not run during rendering.

foundry_check_setup()

Test a specific deployment:

foundry_check_setup(model = "gpt-5-nano")

If you need to see deployments exposed by the v1 model metadata endpoint, use:

models <- foundry_models()
models[, c("id", "owned_by")]

First Responses API call

The Responses API is the newer v1 surface for stateful turns, strict structured outputs, tools, and richer token metadata. The examples below omit model =, so foundryR reads the deployment from AZURE_FOUNDRY_MODEL; pass model = to target a specific deployment.

library(foundryR)

response <- foundry_response("Answer in one sentence: what is R?")

response$output_text

Chain a follow-up turn with previous_response_id:

follow_up <- foundry_response(
  "Explain why that matters for data analysis in one sentence.",
  previous_response_id = response$response_id
)

follow_up$output_text

First strict extraction

Use JSON Schema when you need model output to become analyzable columns:

schema <- list(
  type = "object",
  properties = list(
    sentiment = list(type = "string", enum = c("positive", "negative", "neutral")),
    topic = list(type = "string")
  ),
  required = c("sentiment", "topic"),
  additionalProperties = FALSE
)

foundry_extract(
  c("The tutorial was clear.", "I needed more examples."),
  schema = schema
)

foundry_extract() uses strict JSON Schema mode by default for supported models.

First embedding

Embeddings convert text to numeric vectors for clustering, semantic search, near-duplicate detection, and downstream models:

texts <- c(
  "The tutorial was clear.",
  "The lecture needed more examples.",
  "The assignment instructions were easy to follow."
)

embeddings <- foundry_embed(texts, model = "text-embedding-3-small")
foundry_similarity(embeddings)

Configure Content Safety

Content Safety uses a separate Azure AI Content Safety resource. In the Azure portal, create an Azure AI Content Safety resource, open Keys and Endpoint, then configure foundryR:

foundry_set_content_safety_endpoint(Sys.getenv("AZURE_CONTENT_SAFETY_ENDPOINT"))
foundry_set_content_safety_key("your-content-safety-key")

Use groundedness and shields as auditable safety gates:

source <- "The program enrolled 82 students in 2026."
answer <- "The program enrolled 82 students in 2026."

grounded <- foundry_groundedness(
  text = answer,
  grounding_sources = source,
  query = "How many students enrolled?",
  task = "QnA"
)

shield <- foundry_shield(user_prompt = "Summarize this document.")

grounded
shield

Most foundryR calls stay within your Azure OpenAI or Content Safety resources. Web search is different. Microsoft documents that Grounding with Bing can send data outside the compliance and geographic boundary and can incur separate costs. Do not send secrets or regulated data to web-search prompts.

Chat completions

Chat completions are still available for simple assistant replies:

foundry_chat("Answer in one sentence: what is the tidyverse?")

For interactive streaming chat and chat-first agent workflows, use ellmer.

Next steps

• vignette("foundryr-vs-ellmer") compares foundryR with ellmer.
• vignette("annotation-workflow") shows extract, batch, embed, and validate.
• vignette("responses-api") covers Responses API tools and web search.
• vignette("content-safety") covers moderation, groundedness, and shields.
• vignette("tidymodels") covers step_foundry_embed().

if (run_api) {
  httptest2::end_vignette()
}

foundryR documentation built on Sept. 25, 2026, 1:10 a.m.