Package {aisdk}

aisdk: AI SDK for R

Description

A production-grade AI SDK for R featuring a layered architecture, middleware support, robust error handling, and support for multiple AI model providers.

Architecture

The SDK uses a 4-layer architecture:

• Specification Layer: Abstract interfaces (LanguageModelV1, EmbeddingModelV1)

• Utilities Layer: Shared tools (HTTP, retry, registry, middleware)

• Provider Layer: Concrete implementations (OpenAIProvider, etc.)

• Core Layer: High-level API (generate_text, stream_text, embed)

Quick Start

library(aisdk)

# Create an OpenAI provider
openai <- create_openai()

# Generate text
result <- generate_text(
  model = openai$language_model("gpt-4o"),
  prompt = "Explain R in one sentence."
)
print(result$text)

# Or use the registry for cleaner syntax
get_default_registry()$register("openai", openai)
result <- generate_text("openai:gpt-4o", "Hello!")

Author(s)

Maintainer: Yonghe Xia xiayh17@gmail.com

See Also

Useful links:

• https://github.com/YuLab-SMU/aisdk

• https://yulab-smu.top/aisdk/

• Report bugs at https://github.com/YuLab-SMU/aisdk/issues

SDK Feature Flags

Description

Global feature flags for controlling SDK behavior. These flags allow gradual migration to new features while maintaining backward compatibility.

Usage

.sdk_features

Format

An object of class environment of length 7.

System Prompt for Auto-Fix

Description

System Prompt for Auto-Fix

Usage

AUTO_FIX_SYSTEM_PROMPT

Format

An object of class character of length 1.

Agent Class

Description

R6 class representing an AI agent. Agents are the worker units in the multi-agent architecture. Each agent has a name, description (for semantic routing), system prompt (persona), and a set of tools it can use.

Key design principle: Agents are stateless regarding conversation history. The ChatSession holds the shared state (history, memory, environment).

Public fields

Methods

Public methods

• Agent$new()

• Agent$run()

• Agent$stream()

• Agent$as_tool()

• Agent$create_session()

• Agent$print()

• Agent$clone()

Method new()

Initialize a new Agent.

Usage

Agent$new(
  name,
  description,
  system_prompt = NULL,
  tools = NULL,
  skills = NULL,
  model = NULL,
  capability_models = NULL
)

Arguments

Returns

An Agent object.

Method run()

Run the agent with a given task.

Usage

Agent$run(
  task,
  session = NULL,
  context = NULL,
  model = NULL,
  max_steps = 10,
  ...
)

Arguments

Returns

A GenerateResult object from generate_text.

Method stream()

Run the agent with streaming output.

Usage

Agent$stream(
  task,
  callback = NULL,
  session = NULL,
  context = NULL,
  model = NULL,
  max_steps = 10,
  ...
)

Arguments

Returns

A GenerateResult object (accumulated).

Method as_tool()

Convert this agent to a Tool.

Usage

Agent$as_tool()

Details

This allows the agent to be used as a delegate target by a Manager agent. The tool wraps the agent's run() method and uses the agent's description for semantic routing.

Returns

A Tool object that wraps this agent.

Method create_session()

Create a stateful ChatSession from this agent.

Usage

Agent$create_session(model = NULL, ...)

Arguments

Returns

A ChatSession object initialized with this agent's config.

Method print()

Print method for Agent.

Usage

Agent$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

Agent$clone(deep = FALSE)

Arguments

AgentRegistry Class

Description

R6 class for managing a collection of Agent objects. Provides storage, lookup, and automatic delegation tool generation for multi-agent systems.

Methods

Public methods

• AgentRegistry$new()

• AgentRegistry$register()

• AgentRegistry$get()

• AgentRegistry$has()

• AgentRegistry$list_agents()

• AgentRegistry$get_all()

• AgentRegistry$unregister()

• AgentRegistry$generate_delegate_tools()

• AgentRegistry$generate_prompt_section()

• AgentRegistry$print()

• AgentRegistry$clone()

Method new()

Initialize a new AgentRegistry.

Usage

AgentRegistry$new(agents = NULL)

Arguments

Method register()

Register an agent.

Usage

AgentRegistry$register(agent)

Arguments

Returns

Invisible self for chaining.

Method get()

Get an agent by name.

Usage

AgentRegistry$get(name)

Arguments

Returns

The Agent object, or NULL if not found.

Method has()

Check if an agent is registered.

Usage

AgentRegistry$has(name)

Arguments

Returns

TRUE if registered, FALSE otherwise.

Method list_agents()

List all registered agent names.

Usage

AgentRegistry$list_agents()

Returns

Character vector of agent names.

Method get_all()

Get all registered agents.

Usage

AgentRegistry$get_all()

Returns

List of Agent objects.

Method unregister()

Unregister an agent.

Usage

AgentRegistry$unregister(name)

Arguments

Returns

Invisible self for chaining.

Method generate_delegate_tools()

Generate delegation tools for all registered agents.

Usage

AgentRegistry$generate_delegate_tools(
  flow = NULL,
  session = NULL,
  model = NULL
)

Arguments

Details

Creates a list of Tool objects that wrap each agent's run() method. These tools can be given to a Manager agent for semantic routing.

Returns

A list of Tool objects.

Method generate_prompt_section()

Generate a prompt section describing available agents.

Usage

AgentRegistry$generate_prompt_section()

Details

Creates a formatted string listing all agents and their descriptions. Useful for injecting into a Manager's system prompt.

Returns

A character string.

Method print()

Print method for AgentRegistry.

Usage

AgentRegistry$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

AgentRegistry$clone(deep = FALSE)

Arguments

Anthropic Language Model Class

Description

Language model implementation for Anthropic's Messages API.

Super class

aisdk::LanguageModelV1 -> AnthropicLanguageModel

Methods

Public methods

• AnthropicLanguageModel$new()

• AnthropicLanguageModel$get_config()

• AnthropicLanguageModel$do_generate()

• AnthropicLanguageModel$do_stream()

• AnthropicLanguageModel$format_tool_result()

• AnthropicLanguageModel$get_history_format()

• AnthropicLanguageModel$clone()

Method new()

Initialize the Anthropic language model.

Usage

AnthropicLanguageModel$new(model_id, config, capabilities = list())

Arguments

Method get_config()

Get the configuration list.

Usage

AnthropicLanguageModel$get_config()

Returns

A list with provider configuration.

Method do_generate()

Generate text (non-streaming).

Usage

AnthropicLanguageModel$do_generate(params)

Arguments

Returns

A GenerateResult object.

Method do_stream()

Generate text (streaming).

Usage

AnthropicLanguageModel$do_stream(params, callback)

Arguments

Returns

A GenerateResult object.

Method format_tool_result()

Format a tool execution result for Anthropic's API.

Usage

AnthropicLanguageModel$format_tool_result(
  tool_call_id,
  tool_name,
  result_content
)

Arguments

Returns

A list formatted as a message for Anthropic's API.

Method get_history_format()

Get the message format for Anthropic.

Usage

AnthropicLanguageModel$get_history_format()

Method clone()

The objects of this class are cloneable with this method.

Usage

AnthropicLanguageModel$clone(deep = FALSE)

Arguments

Anthropic Provider Class

Description

Provider class for Anthropic. Can create language models.

Public fields

Methods

Public methods

• AnthropicProvider$new()

• AnthropicProvider$enable_caching()

• AnthropicProvider$language_model()

• AnthropicProvider$clone()

Method new()

Initialize the Anthropic provider.

Usage

AnthropicProvider$new(
  api_key = NULL,
  base_url = NULL,
  api_version = NULL,
  headers = NULL,
  name = NULL,
  timeout_seconds = NULL,
  total_timeout_seconds = NULL,
  first_byte_timeout_seconds = NULL,
  connect_timeout_seconds = NULL,
  idle_timeout_seconds = NULL
)

Arguments

Method enable_caching()

Enable or disable prompt caching.

Usage

AnthropicProvider$enable_caching(enable = TRUE)

Arguments

Method language_model()

Create a language model.

Usage

AnthropicProvider$language_model(model_id = "claude-sonnet-4-20250514")

Arguments

Returns

An AnthropicLanguageModel object.

Method clone()

The objects of this class are cloneable with this method.

Usage

AnthropicProvider$clone(deep = FALSE)

Arguments

Capturing Agent Output Renderer

Description

A Renderer that records every agent-output event into an in-memory log instead of displaying it – useful for testing, replay, and reusing agent-output logic in non-terminal UIs.

Super class

aisdk::Renderer -> CaptureRenderer

Public fields

Methods

Public methods

• CaptureRenderer$new()

• CaptureRenderer$process_chunk()

• CaptureRenderer$start_thinking()

• CaptureRenderer$stop_thinking()

• CaptureRenderer$render_tool_start()

• CaptureRenderer$render_tool_result()

• CaptureRenderer$reset_for_new_step()

• CaptureRenderer$events()

• CaptureRenderer$clone()

Method new()

Create a capturing renderer with an empty log.

Usage

CaptureRenderer$new()

Method process_chunk()

Record a streamed text chunk.

Usage

CaptureRenderer$process_chunk(text, done = FALSE)

Arguments

Method start_thinking()

Record the start of a thinking stream.

Usage

CaptureRenderer$start_thinking()

Method stop_thinking()

Record the end of a thinking stream.

Usage

CaptureRenderer$stop_thinking()

Method render_tool_start()

Record the start of a tool call.

Usage

CaptureRenderer$render_tool_start(name, arguments)

Arguments

Method render_tool_result()

Record a tool result.

Usage

CaptureRenderer$render_tool_result(
  name,
  result,
  success = TRUE,
  raw_result = NULL
)

Arguments

Method reset_for_new_step()

Record a ReAct step boundary.

Usage

CaptureRenderer$reset_for_new_step()

Method events()

Return the recorded events.

Usage

CaptureRenderer$events()

Returns

A list of recorded events.

Method clone()

The objects of this class are cloneable with this method.

Usage

CaptureRenderer$clone(deep = FALSE)

Arguments

ChatSession Class

Description

R6 class representing a stateful chat session. Automatically manages conversation history, supports tool execution, and provides persistence.

Methods

Public methods

• ChatSession$new()

• ChatSession$send()

• ChatSession$send_stream()

• ChatSession$continue_run()

• ChatSession$append_message()

• ChatSession$get_history()

• ChatSession$get_last_response()

• ChatSession$clear_history()

• ChatSession$switch_model()

• ChatSession$get_model_options()

• ChatSession$get_model_call_options()

• ChatSession$set_model_options()

• ChatSession$clear_model_options()

• ChatSession$set_capability_model()

• ChatSession$get_capability_model()

• ChatSession$list_capability_models()

• ChatSession$clear_capability_model()

• ChatSession$get_model_id()

• ChatSession$get_model()

• ChatSession$get_tools()

• ChatSession$stats()

• ChatSession$save()

• ChatSession$as_list()

• ChatSession$restore()

• ChatSession$restore_from_list()

• ChatSession$print()

• ChatSession$get_memory()

• ChatSession$get_run_state()

• ChatSession$set_run_state()

• ChatSession$set_memory()

• ChatSession$list_memory()

• ChatSession$get_metadata()

• ChatSession$set_metadata()

• ChatSession$merge_metadata()

• ChatSession$list_metadata()

• ChatSession$get_context_state()

• ChatSession$set_context_state()

• ChatSession$clear_context_state()

• ChatSession$get_context_management_mode()

• ChatSession$get_context_management_config()

• ChatSession$set_context_management_mode()

• ChatSession$set_context_management_config()

• ChatSession$get_context_metrics()

• ChatSession$assemble_messages()

• ChatSession$refresh_context_state()

• ChatSession$list_context_handles()

• ChatSession$create_context_query_tools()

• ChatSession$sub_session_query()

• ChatSession$clear_memory()

• ChatSession$get_envir()

• ChatSession$eval_in_session()

• ChatSession$list_envir()

• ChatSession$checkpoint()

• ChatSession$restore_checkpoint()

• ChatSession$clone()

Method new()

Initialize a new ChatSession.

Usage

ChatSession$new(
  model = NULL,
  system_prompt = NULL,
  tools = NULL,
  hooks = NULL,
  history = NULL,
  max_steps = 10,
  registry = NULL,
  memory = NULL,
  metadata = NULL,
  envir = NULL,
  agent = NULL
)

Arguments

Method send()

Send a message and get a response.

Usage

ChatSession$send(prompt, ...)

Arguments

Returns

The GenerateResult object from the model.

Method send_stream()

Send a message with streaming output.

Usage

ChatSession$send_stream(prompt, callback, ...)

Arguments

Returns

The GenerateResult object invisibly (output is via callback).

Method continue_run()

Inject a manual continuation instruction into the current task.

Usage

ChatSession$continue_run(
  action = "continue",
  guidance = NULL,
  stream = TRUE,
  callback = NULL,
  ...
)

Arguments

Returns

The GenerateResult object, or an invisible waiting-user result for manual action.

Method append_message()

Append a message to the history.

Usage

ChatSession$append_message(role, content, reasoning = NULL)

Arguments

Method get_history()

Get the conversation history.

Usage

ChatSession$get_history()

Returns

A list of message objects.

Method get_last_response()

Get the last response from the assistant.

Usage

ChatSession$get_last_response()

Returns

The content of the last assistant message, or NULL.

Method clear_history()

Clear the conversation history.

Usage

ChatSession$clear_history(keep_system = TRUE)

Arguments

Method switch_model()

Switch to a different model.

Usage

ChatSession$switch_model(model)

Arguments

Method get_model_options()

Get model runtime options for this session.

Usage

ChatSession$get_model_options()

Returns

A list with context overrides and call options.

Method get_model_call_options()

Get generation options applied to every model call.

Usage

ChatSession$get_model_call_options()

Returns

A named list of call options.

Method set_model_options()

Set runtime options for this session's model.

Usage

ChatSession$set_model_options(
  context_window = NULL,
  max_output_tokens = NULL,
  max_tokens = NULL,
  thinking = NULL,
  thinking_budget = NULL,
  reasoning_effort = NULL,
  reset = FALSE
)

Arguments

Returns

Invisible self for chaining.

Method clear_model_options()

Clear model runtime options for this session.

Usage

ChatSession$clear_model_options(keys = NULL)

Arguments

Returns

Invisible self for chaining.

Method set_capability_model()

Set a model route for a session capability.

Usage

ChatSession$set_capability_model(
  capability,
  model,
  type = "auto",
  required_model_capabilities = NULL
)

Arguments

Returns

Invisible self for chaining.

Method get_capability_model()

Get the configured model for a session capability.

Usage

ChatSession$get_capability_model(capability, default = NULL)

Arguments

Returns

A model ID string, model object, or default.

Method list_capability_models()

List session capability model routes.

Usage

ChatSession$list_capability_models()

Returns

A data frame of configured session routes.

Method clear_capability_model()

Clear one or all session capability model routes.

Usage

ChatSession$clear_capability_model(capability = NULL)

Arguments

Returns

Invisible self for chaining.

Method get_model_id()

Get current model identifier.

Usage

ChatSession$get_model_id()

Returns

Model ID string.

Method get_model()

Get the resolved language model for this session.

Usage

ChatSession$get_model()

Returns

A LanguageModelV1 object.

Method get_tools()

Get tools configured on this session.

Usage

ChatSession$get_tools()

Returns

A list of Tool objects.

Method stats()

Get token usage statistics.

Usage

ChatSession$stats()

Returns

A list with token counts and message stats.

Method save()

Save session to a file.

Usage

ChatSession$save(path, format = NULL)

Arguments

Method as_list()

Export session state as a list (for serialization).

Usage

ChatSession$as_list()

Returns

A list containing session state.

Method restore()

Restore session from a file.

Usage

ChatSession$restore(path, format = NULL)

Arguments

Method restore_from_list()

Restore session state from a list.

Usage

ChatSession$restore_from_list(data)

Arguments

Method print()

Print method for ChatSession.

Usage

ChatSession$print()

Method get_memory()

Get a value from shared memory.

Usage

ChatSession$get_memory(key, default = NULL)

Arguments

Returns

The stored value or default.

Method get_run_state()

Return the most recent structured run state.

Usage

ChatSession$get_run_state()

Returns

A run state list.

Method set_run_state()

Store the current structured run state.

Usage

ChatSession$set_run_state(run_state)

Arguments

Returns

Invisible self.

Method set_memory()

Set a value in shared memory.

Usage

ChatSession$set_memory(key, value)

Arguments

Returns

Invisible self for chaining.

Method list_memory()

List all keys in shared memory.

Usage

ChatSession$list_memory()

Returns

Character vector of memory keys.

Method get_metadata()

Get a value from session metadata.

Usage

ChatSession$get_metadata(key, default = NULL)

Arguments

Returns

The stored metadata value or default.

Method set_metadata()

Set a value in session metadata.

Usage

ChatSession$set_metadata(key, value)

Arguments

Returns

Invisible self for chaining.

Method merge_metadata()

Merge a named list into session metadata.

Usage

ChatSession$merge_metadata(values)

Arguments

Returns

Invisible self for chaining.

Method list_metadata()

List metadata keys.

Usage

ChatSession$list_metadata()

Returns

Character vector of metadata keys.

Method get_context_state()

Get the adaptive context state for this session.

Usage

ChatSession$get_context_state()

Returns

A normalized context state list.

Method set_context_state()

Store adaptive context state for this session.

Usage

ChatSession$set_context_state(state)

Arguments

Returns

Invisible self for chaining.

Method clear_context_state()

Clear adaptive context state back to defaults.

Usage

ChatSession$clear_context_state()

Returns

Invisible self for chaining.

Method get_context_management_mode()

Get the context management mode for this session.

Usage

ChatSession$get_context_management_mode()

Returns

One of "off", "basic", or "adaptive".

Method get_context_management_config()

Get the full adaptive context-management configuration.

Usage

ChatSession$get_context_management_config()

Returns

A normalized context-management configuration list.

Method set_context_management_mode()

Override the context management mode for this session.

Usage

ChatSession$set_context_management_mode(mode)

Arguments

Returns

Invisible self for chaining.

Method set_context_management_config()

Apply adaptive context-management configuration to this session.

Usage

ChatSession$set_context_management_config(config = NULL, ...)

Arguments

Returns

Invisible self for chaining.

Method get_context_metrics()

Estimate current context metrics for this session.

Usage

ChatSession$get_context_metrics(turn_system_prompt = NULL)

Arguments

Returns

A list of context metrics, or NULL if no model metadata is available.

Method assemble_messages()

Build a budget-aware prompt payload from current session history.

Usage

ChatSession$assemble_messages(turn_system_prompt = NULL)

Arguments

Returns

A list with messages, system, metrics, and state.

Method refresh_context_state()

Refresh the adaptive context state from current history.

Usage

ChatSession$refresh_context_state(
  generation_result = NULL,
  turn_system_prompt = NULL
)

Arguments

Returns

The normalized context state list.

Method list_context_handles()

List compact context handles available to this session.

Usage

ChatSession$list_context_handles()

Returns

A list of context handle records.

Method create_context_query_tools()

Create context query tools bound to this session.

Usage

ChatSession$create_context_query_tools()

Returns

A list of Tool objects.

Method sub_session_query()

Run a bounded child session for a focused query.

Usage

ChatSession$sub_session_query(...)

Arguments

Returns

A compact sub-session result list.

Method clear_memory()

Clear shared memory.

Usage

ChatSession$clear_memory(keys = NULL)

Arguments

Returns

Invisible self for chaining.

Method get_envir()

Get the shared R environment.

Usage

ChatSession$get_envir()

Details

This environment is shared across all agents using this session. Agents can store and retrieve data frames, models, and other R objects.

Returns

An environment object.

Method eval_in_session()

Evaluate an expression in the session environment.

Usage

ChatSession$eval_in_session(expr)

Arguments

Returns

The result of the evaluation.

Method list_envir()

List objects in the session environment.

Usage

ChatSession$list_envir()

Returns

Character vector of object names.

Method checkpoint()

Save a memory snapshot to a file (checkpoint for Mission resume).

Usage

ChatSession$checkpoint(path = NULL)

Arguments

Returns

Invisible file path.

Method restore_checkpoint()

Restore memory and history from a checkpoint file.

Usage

ChatSession$restore_checkpoint(path)

Arguments

Returns

Invisible self for chaining.

Method clone()

The objects of this class are cloneable with this method.

Usage

ChatSession$clone(deep = FALSE)

Arguments

Computer Class

Description

R6 class providing computer abstraction with atomic tools for file operations, bash execution, and R code execution.

Public fields

Methods

Public methods

• Computer$new()

• Computer$bash()

• Computer$read_file()

• Computer$write_file()

• Computer$edit_file()

• Computer$execute_r_code()

• Computer$get_log()

• Computer$clear_log()

• Computer$clone()

Method new()

Initialize computer abstraction

Usage

Computer$new(working_dir = tempdir(), sandbox_mode = "permissive")

Arguments

Method bash()

Execute bash command

Usage

Computer$bash(command, timeout_ms = 30000, capture_output = TRUE)

Arguments

Returns

List with stdout, stderr, exit_code

Method read_file()

Read file contents

Usage

Computer$read_file(path, encoding = "UTF-8")

Arguments

Returns

File contents as character string

Method write_file()

Write file contents

Usage

Computer$write_file(path, content, encoding = "UTF-8")

Arguments

Returns

Success status

Method edit_file()

Edit a file by replacing an exact text pattern.

Usage

Computer$edit_file(path, pattern, replacement, all = FALSE, encoding = "UTF-8")

Arguments

Returns

Success status

Method execute_r_code()

Execute R code in an isolated callr process

Usage

Computer$execute_r_code(code, timeout_ms = 30000, capture_output = TRUE)

Arguments

Returns

List with result, output, error, and execution_mode. execution_mode is always "sandbox_exec" for this computer-layer path, which does not persist values into a live ChatSession$get_envir().

Method get_log()

Get execution log

Usage

Computer$get_log()

Returns

List of logged executions

Method clear_log()

Clear execution log Check bash command for sandbox violations Log execution Resolve path (relative to working_dir or absolute) Check write path for sandbox violations Check R code for sandbox violations

Usage

Computer$clear_log()

Method clone()

The objects of this class are cloneable with this method.

Usage

Computer$clone(deep = FALSE)

Arguments

Embedding Model V1 (Abstract Base Class)

Description

Abstract interface for embedding models.

Public fields

Methods

Public methods

• EmbeddingModelV1$new()

• EmbeddingModelV1$do_embed()

• EmbeddingModelV1$clone()

Method new()

Initialize the embedding model.

Usage

EmbeddingModelV1$new(provider, model_id)

Arguments

Method do_embed()

Generate embeddings for a value. Abstract method.

Usage

EmbeddingModelV1$do_embed(value)

Arguments

Returns

A provider-specific embedding result.

Method clone()

The objects of this class are cloneable with this method.

Usage

EmbeddingModelV1$clone(deep = FALSE)

Arguments

Gemini Image Model Class

Description

Image model implementation for Gemini image generation models.

Super class

aisdk::ImageModelV1 -> GeminiImageModel

Methods

Public methods

• GeminiImageModel$new()

• GeminiImageModel$do_generate_image()

• GeminiImageModel$do_edit_image()

• GeminiImageModel$clone()

Method new()

Initialize the Gemini image model.

Usage

GeminiImageModel$new(model_id, config)

Arguments

Method do_generate_image()

Generate images.

Usage

GeminiImageModel$do_generate_image(params)

Arguments

Returns

A GenerateImageResult object.

Method do_edit_image()

Edit images.

Usage

GeminiImageModel$do_edit_image(params)

Arguments

Returns

A GenerateImageResult object.

Method clone()

The objects of this class are cloneable with this method.

Usage

GeminiImageModel$clone(deep = FALSE)

Arguments

Gemini Language Model Class

Description

Language model implementation for Gemini's generateContent API.

Super class

aisdk::LanguageModelV1 -> GeminiLanguageModel

Methods

Public methods

• GeminiLanguageModel$new()

• GeminiLanguageModel$get_config()

• GeminiLanguageModel$build_payload_internal()

• GeminiLanguageModel$do_generate()

• GeminiLanguageModel$do_stream()

• GeminiLanguageModel$format_tool_result()

• GeminiLanguageModel$get_history_format()

• GeminiLanguageModel$clone()

Method new()

Initialize the Gemini language model.

Usage

GeminiLanguageModel$new(model_id, config)

Arguments

Method get_config()

Get the configuration list.

Usage

GeminiLanguageModel$get_config()

Returns

A list with provider configuration.

Method build_payload_internal()

Build the request payload for generation

Usage

GeminiLanguageModel$build_payload_internal(params, stream = FALSE)

Arguments

Returns

A list with url, headers, and body.

Method do_generate()

Generate text (non-streaming).

Usage

GeminiLanguageModel$do_generate(params)

Arguments

Returns

A GenerateResult object.

Method do_stream()

Generate text (streaming).

Usage

GeminiLanguageModel$do_stream(params, callback)

Arguments

Returns

A GenerateResult object.

Method format_tool_result()

Format a tool execution result for Gemini's API.

Usage

GeminiLanguageModel$format_tool_result(tool_call_id, tool_name, result_content)

Arguments

Returns

A list formatted as a message for Gemini API.

Method get_history_format()

Get the message format for Gemini.

Usage

GeminiLanguageModel$get_history_format()

Method clone()

The objects of this class are cloneable with this method.

Usage

GeminiLanguageModel$clone(deep = FALSE)

Arguments

Gemini Provider Class

Description

Provider class for Google Gemini.

Public fields

Methods

Public methods

• GeminiProvider$new()

• GeminiProvider$language_model()

• GeminiProvider$image_model()

• GeminiProvider$clone()

Method new()

Initialize the Gemini provider.

Usage

GeminiProvider$new(
  api_key = NULL,
  base_url = NULL,
  headers = NULL,
  name = NULL,
  timeout_seconds = NULL,
  total_timeout_seconds = NULL,
  first_byte_timeout_seconds = NULL,
  connect_timeout_seconds = NULL,
  idle_timeout_seconds = NULL
)

Arguments

Method language_model()

Create a language model.

Usage

GeminiProvider$language_model(
  model_id = Sys.getenv("GEMINI_MODEL", "gemini-2.5-flash")
)

Arguments

Returns

A GeminiLanguageModel object.

Method image_model()

Create an image model.

Usage

GeminiProvider$image_model(
  model_id = Sys.getenv("GEMINI_IMAGE_MODEL", "gemini-2.5-flash-image")
)

Arguments

Returns

A GeminiImageModel object.

Method clone()

The objects of this class are cloneable with this method.

Usage

GeminiProvider$clone(deep = FALSE)

Arguments

Generate Image Result

Description

Result object returned by image generation and editing models.

Public fields

Methods

Public methods

• GenerateImageResult$new()

• GenerateImageResult$print()

• GenerateImageResult$clone()

Method new()

Initialize a GenerateImageResult object.

Usage

GenerateImageResult$new(
  images = NULL,
  text = NULL,
  usage = NULL,
  finish_reason = NULL,
  warnings = NULL,
  raw_response = NULL
)

Arguments

Method print()

Print method for GenerateImageResult.

Usage

GenerateImageResult$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

GenerateImageResult$clone(deep = FALSE)

Arguments

Generate Result

Description

Result object returned by model generation.

Details

This class uses lock_objects = FALSE to allow dynamic field addition. This enables the ReAct loop and other components to attach additional metadata (like steps, all_tool_calls) without modifying the class.

For models that support reasoning/thinking (like OpenAI o1/o3, DeepSeek, Claude with extended thinking), the reasoning field contains the model's chain-of-thought content.

For Responses API models, response_id contains the server-side response ID which can be used for multi-turn conversations without sending full history.

Public fields

Methods

Public methods

• GenerateResult$new()

• GenerateResult$print()

• GenerateResult$clone()

Method new()

Initialize a GenerateResult object.

Usage

GenerateResult$new(
  text = NULL,
  usage = NULL,
  finish_reason = NULL,
  warnings = NULL,
  raw_response = NULL,
  tool_calls = NULL,
  steps = NULL,
  all_tool_calls = NULL,
  reasoning = NULL,
  response_id = NULL
)

Arguments

Method print()

Print method for GenerateResult.

Usage

GenerateResult$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

GenerateResult$clone(deep = FALSE)

Arguments

Hook Handler

Description

R6 class to manage and execute hooks.

Public fields

Methods

Public methods

• HookHandler$new()

• HookHandler$trigger_generation_start()

• HookHandler$trigger_generation_end()

• HookHandler$trigger_tool_start()

• HookHandler$trigger_tool_end()

• HookHandler$clone()

Method new()

Initialize HookHandler

Usage

HookHandler$new(hooks_list = list())

Arguments

Method trigger_generation_start()

Trigger on_generation_start

Usage

HookHandler$trigger_generation_start(model, prompt, tools)

Arguments

Method trigger_generation_end()

Trigger on_generation_end

Usage

HookHandler$trigger_generation_end(result)

Arguments

Method trigger_tool_start()

Trigger on_tool_start

Usage

HookHandler$trigger_tool_start(tool, args)

Arguments

Method trigger_tool_end()

Trigger on_tool_end

Usage

HookHandler$trigger_tool_end(
  tool,
  result,
  success = TRUE,
  error = NULL,
  args = NULL
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

HookHandler$clone(deep = FALSE)

Arguments

Image Model V1 (Abstract Base Class)

Description

Abstract interface for image generation and editing models.

Public fields

Methods

Public methods

• ImageModelV1$new()

• ImageModelV1$has_capability()

• ImageModelV1$generate_image()

• ImageModelV1$edit_image()

• ImageModelV1$do_generate_image()

• ImageModelV1$do_edit_image()

• ImageModelV1$do_stream_image()

• ImageModelV1$stream_image()

• ImageModelV1$clone()

Method new()

Initialize the image model.

Usage

ImageModelV1$new(provider, model_id, capabilities = list())

Arguments

Method has_capability()

Check if the image model has a specific capability.

Usage

ImageModelV1$has_capability(cap)

Arguments

Returns

Logical.

Method generate_image()

Public image generation method.

Usage

ImageModelV1$generate_image(...)

Arguments

Returns

A GenerateImageResult object.

Method edit_image()

Public image editing method.

Usage

ImageModelV1$edit_image(...)

Arguments

Returns

A GenerateImageResult object.

Method do_generate_image()

Generate images. Abstract method.

Usage

ImageModelV1$do_generate_image(params)

Arguments

Returns

A GenerateImageResult object.

Method do_edit_image()

Edit images. Abstract method.

Usage

ImageModelV1$do_edit_image(params)

Arguments

Returns

A GenerateImageResult object.

Method do_stream_image()

Stream image generation with partial-image previews. Optional — subclasses that support it override. Default raises an informative error so stream_image() callers can fall back to generate_image() on providers without streaming support.

Usage

ImageModelV1$do_stream_image(params, callback)

Arguments

Returns

A GenerateImageResult object with the final image.

Method stream_image()

Public image streaming method.

Usage

ImageModelV1$stream_image(callback, ...)

Arguments

Returns

A GenerateImageResult object.

Method clone()

The objects of this class are cloneable with this method.

Usage

ImageModelV1$clone(deep = FALSE)

Arguments

Language Model V1 (Abstract Base Class)

Description

Abstract interface for language models. All LLM providers must implement this class. Uses do_ prefix for internal methods to prevent direct usage by end-users.

Public fields

Methods

Public methods

• LanguageModelV1$new()

• LanguageModelV1$has_capability()

• LanguageModelV1$generate()

• LanguageModelV1$stream()

• LanguageModelV1$do_generate()

• LanguageModelV1$do_stream()

• LanguageModelV1$format_tool_result()

• LanguageModelV1$get_history_format()

• LanguageModelV1$clone()

Method new()

Initialize the model with provider and model ID.

Usage

LanguageModelV1$new(provider, model_id, capabilities = list())

Arguments

Method has_capability()

Check if the model has a specific capability.

Usage

LanguageModelV1$has_capability(cap)

Arguments

Returns

Logical.

Method generate()

Public generation method.

Usage

LanguageModelV1$generate(...)

Arguments

Returns

A GenerateResult object.

Method stream()

Public streaming method.

Usage

LanguageModelV1$stream(callback, ...)

Arguments

Returns

A GenerateResult object.

Method do_generate()

Generate text (non-streaming). Abstract method.

Usage

LanguageModelV1$do_generate(params)

Arguments

Returns

A GenerateResult object.

Method do_stream()

Generate text (streaming). Abstract method.

Usage

LanguageModelV1$do_stream(params, callback)

Arguments

Returns

A GenerateResult object.

Method format_tool_result()

Format a tool execution result for the provider API.

Usage

LanguageModelV1$format_tool_result(tool_call_id, tool_name, result_content)

Arguments

Returns

A provider-specific tool result message.

Method get_history_format()

Get the message history format used by this model.

Usage

LanguageModelV1$get_history_format()

Returns

A character string such as "openai" or "anthropic".

Method clone()

The objects of this class are cloneable with this method.

Usage

LanguageModelV1$clone(deep = FALSE)

Arguments

Middleware (Base Class)

Description

Defines a middleware that can intercept and modify model operations.

Public fields

Methods

Public methods

• Middleware$transform_params()

• Middleware$wrap_generate()

• Middleware$wrap_stream()

• Middleware$clone()

Method transform_params()

Transform parameters before calling the model.

Usage

Middleware$transform_params(params, type, model)

Arguments

Returns

The transformed parameters.

Method wrap_generate()

Wrap the generate operation.

Usage

Middleware$wrap_generate(do_generate, params, model)

Arguments

Returns

The result of the generation.

Method wrap_stream()

Wrap the stream operation.

Usage

Middleware$wrap_stream(do_stream, params, model, callback)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Middleware$clone(deep = FALSE)

Arguments

Object Strategy

Description

Object Strategy

Object Strategy

Details

Strategy for generating structured objects based on a JSON Schema. This strategy instructs the LLM to produce valid JSON matching the schema, and handles parsing and validation of the output.

Super class

aisdk::OutputStrategy -> ObjectStrategy

Public fields

Methods

Public methods

• ObjectStrategy$new()

• ObjectStrategy$get_instruction()

• ObjectStrategy$validate()

• ObjectStrategy$clone()

Method new()

Initialize the ObjectStrategy.

Usage

ObjectStrategy$new(schema, schema_name = "json_schema")

Arguments

Method get_instruction()

Generate the instruction for the LLM to output valid JSON.

Usage

ObjectStrategy$get_instruction()

Returns

A character string with the prompt instruction.

Method validate()

Validate and parse the LLM output as JSON.

Usage

ObjectStrategy$validate(text, is_final = FALSE)

Arguments

Returns

The parsed R object (list), or NULL if parsing fails.

Method clone()

The objects of this class are cloneable with this method.

Usage

ObjectStrategy$clone(deep = FALSE)

Arguments

OpenAI Embedding Model

Description

Embedding model implementation for OpenAI's embeddings API.

Super class

aisdk::EmbeddingModelV1 -> OpenAIEmbeddingModel

Methods

Public methods

• OpenAIEmbeddingModel$new()

• OpenAIEmbeddingModel$do_embed()

• OpenAIEmbeddingModel$clone()

Method new()

Initialize the OpenAI embedding model.

Usage

OpenAIEmbeddingModel$new(model_id, config)

Arguments

Method do_embed()

Generate embeddings for a value.

Usage

OpenAIEmbeddingModel$do_embed(value)

Arguments

Returns

A list with embeddings and usage.

Method clone()

The objects of this class are cloneable with this method.

Usage

OpenAIEmbeddingModel$clone(deep = FALSE)

Arguments

OpenAI Image Model

Description

Image model implementation for OpenAI's image generation and editing APIs. Exported so that OpenAI-compatible providers in companion packages (e.g. aisdk.providers) can construct image models across package boundaries.

Super class

aisdk::ImageModelV1 -> OpenAIImageModel

Methods

Public methods

• OpenAIImageModel$new()

• OpenAIImageModel$do_generate_image()

• OpenAIImageModel$do_generate_image_classic()

• OpenAIImageModel$do_generate_image_via_responses()

• OpenAIImageModel$looks_like_missing_classic_endpoint()

• OpenAIImageModel$get_last_response_id()

• OpenAIImageModel$reset()

• OpenAIImageModel$do_edit_image()

• OpenAIImageModel$do_edit_image_classic()

• OpenAIImageModel$do_stream_image()

• OpenAIImageModel$do_edit_image_via_responses()

• OpenAIImageModel$clone()

Method new()

Initialize the OpenAI image model.

Usage

OpenAIImageModel$new(model_id, config)

Arguments

Method do_generate_image()

Generate images.

Tries the classic POST /v1/images/generations endpoint first. If that returns a 404 with invalid_api_path / "not available" — the signal some OpenAI-compatible proxies emit when they only expose the newer Responses API — falls back to POST /v1/responses with the image_generation tool and decodes the returned base64 image.

On the fallback path, the standard image params (quality, size, output_format, output_compression, background, moderation, n) are forwarded into the tool config, and a previous_response_id from a prior fallback call is auto-attached so multi-turn edits ("now make it realistic") work the same as on the language-model path. Use get_last_response_id() / reset() to inspect or clear that state.

Usage

OpenAIImageModel$do_generate_image(params)

Arguments

Returns

A GenerateImageResult object.

Method do_generate_image_classic()

Generate images via the classic POST /v1/images/generations endpoint. Called by do_generate_image(); exposed for callers that want to bypass the Responses-API fallback on proxies they trust.

Usage

OpenAIImageModel$do_generate_image_classic(params)

Arguments

Returns

A GenerateImageResult object.

Method do_generate_image_via_responses()

Generate images via POST /v1/responses with the image_generation tool. Used as a fallback when the classic ⁠/v1/images/generations⁠ endpoint is unreachable (e.g. OpenAI-compatible proxies that only expose the Responses API).

Usage

OpenAIImageModel$do_generate_image_via_responses(params)

Arguments

Returns

A GenerateImageResult object.

Method looks_like_missing_classic_endpoint()

Heuristic check used by do_generate_image() / do_edit_image() to decide whether a classic-endpoint error looks like "endpoint not available" on the proxy, in which case the Responses-API fallback is taken. Matches both the ⁠/images/generations⁠ and ⁠/images/edits⁠ paths.

Usage

OpenAIImageModel$looks_like_missing_classic_endpoint(err)

Arguments

Returns

TRUE if the error message matches the "missing endpoint" shape.

Method get_last_response_id()

Return the most recent Responses-API response id captured during the ⁠/v1/responses⁠ fallback path. Used to chain multi-turn image edits via previous_response_id.

Usage

OpenAIImageModel$get_last_response_id()

Returns

Character scalar or NULL if no fallback call has succeeded yet.

Method reset()

Clear any stored previous_response_id, ending the current multi-turn image session on the Responses-API fallback path.

Usage

OpenAIImageModel$reset()

Returns

The model, invisibly.

Method do_edit_image()

Edit images.

Tries the classic POST /v1/images/edits multipart endpoint first. If that returns the same "missing endpoint" 404 signal handled by do_generate_image(), falls back to POST /v1/responses with the source image inlined as an input_image data URL and the optional mask passed via input_image_mask on the image_generation tool.

The Responses fallback accepts a single source image per turn (multi-reference edit is classic-only). Image params (quality, size, output_format, background, output_compression, moderation, input_fidelity) are forwarded into the tool config, and previous_response_id is auto-attached from any prior fallback call so iterative edits chain.

Usage

OpenAIImageModel$do_edit_image(params)

Arguments

Returns

A GenerateImageResult object.

Method do_edit_image_classic()

Edit images via the classic POST /v1/images/edits multipart endpoint. Called by do_edit_image(); exposed for callers that want to bypass the Responses-API fallback.

Usage

OpenAIImageModel$do_edit_image_classic(params)

Arguments

Returns

A GenerateImageResult object.

Method do_stream_image()

Stream image generation with partial-image previews via POST /v1/responses. Sets stream = TRUE and partial_images on the image_generation tool config; dispatches SSE events to the user-supplied callback (one per partial frame, one final). Uses the same Responses-API path as the non-streaming fallback, with the same previous_response_id chaining.

Usage

OpenAIImageModel$do_stream_image(params, callback)

Arguments

Returns

A GenerateImageResult with the final image.

Method do_edit_image_via_responses()

Edit images via POST /v1/responses with the image_generation tool in edit mode. Inlines the source image as a base64 data URL inside an input_image block; passes the optional mask via the tool's input_image_mask field.

Usage

OpenAIImageModel$do_edit_image_via_responses(params)

Arguments

Returns

A GenerateImageResult object.

Method clone()

The objects of this class are cloneable with this method.

Usage

OpenAIImageModel$clone(deep = FALSE)

Arguments

OpenAI Language Model Class

Description

Language model implementation for OpenAI's chat completions API. Exported so that OpenAI-compatible providers in companion packages (e.g. aisdk.providers) can inherit from it across package boundaries.

Super class

aisdk::LanguageModelV1 -> OpenAILanguageModel

Methods

Public methods

• OpenAILanguageModel$new()

• OpenAILanguageModel$get_config()

• OpenAILanguageModel$build_payload()

• OpenAILanguageModel$execute_request()

• OpenAILanguageModel$parse_response()

• OpenAILanguageModel$do_generate()

• OpenAILanguageModel$build_stream_payload()

• OpenAILanguageModel$do_stream()

• OpenAILanguageModel$format_tool_result()

• OpenAILanguageModel$get_history_format()

• OpenAILanguageModel$clone()

Method new()

Initialize the OpenAI language model.

Usage

OpenAILanguageModel$new(model_id, config, capabilities = list())

Arguments

Method get_config()

Get the configuration list.

Usage

OpenAILanguageModel$get_config()

Returns

A list with provider configuration.

Method build_payload()

Build the request payload for non-streaming generation. Subclasses can override to customize payload construction.

Usage

OpenAILanguageModel$build_payload(params)

Arguments

Returns

A list with url, headers, and body.

Method execute_request()

Execute the API request.

Usage

OpenAILanguageModel$execute_request(
  url,
  headers,
  body,
  timeout_seconds = NULL,
  total_timeout_seconds = NULL,
  first_byte_timeout_seconds = NULL,
  connect_timeout_seconds = NULL,
  idle_timeout_seconds = NULL
)

Arguments

Returns

The parsed API response.

Method parse_response()

Parse the API response into a GenerateResult. Subclasses can override to extract provider-specific fields (e.g., reasoning_content).

Usage

OpenAILanguageModel$parse_response(response)

Arguments

Returns

A GenerateResult object.

Method do_generate()

Generate text (non-streaming). Uses template method pattern.

Usage

OpenAILanguageModel$do_generate(params)

Arguments

Returns

A GenerateResult object.

Method build_stream_payload()

Build the request payload for streaming generation. Subclasses can override to customize stream payload construction.

Usage

OpenAILanguageModel$build_stream_payload(params)

Arguments

Returns

A list with url, headers, and body.

Method do_stream()

Generate text (streaming).

Usage

OpenAILanguageModel$do_stream(params, callback)

Arguments

Returns

A GenerateResult object.

Method format_tool_result()

Format a tool execution result for OpenAI's API.

Usage

OpenAILanguageModel$format_tool_result(tool_call_id, tool_name, result_content)

Arguments

Returns

A list formatted as a message for OpenAI's API.

Method get_history_format()

Get the message format for OpenAI.

Usage

OpenAILanguageModel$get_history_format()

Method clone()

The objects of this class are cloneable with this method.

Usage

OpenAILanguageModel$clone(deep = FALSE)

Arguments

OpenAI Provider Class

Description

Provider class for OpenAI. Can create language and embedding models.

Public fields

Methods

Public methods

• OpenAIProvider$new()

• OpenAIProvider$language_model()

• OpenAIProvider$responses_model()

• OpenAIProvider$model()

• OpenAIProvider$smart_model()

• OpenAIProvider$embedding_model()

• OpenAIProvider$image_model()

• OpenAIProvider$create_conversation()

• OpenAIProvider$get_conversation()

• OpenAIProvider$delete_conversation()

• OpenAIProvider$clone()

Method new()

Initialize the OpenAI provider.

Usage

OpenAIProvider$new(
  api_key = NULL,
  base_url = NULL,
  organization = NULL,
  project = NULL,
  headers = NULL,
  name = NULL,
  timeout_seconds = NULL,
  total_timeout_seconds = NULL,
  first_byte_timeout_seconds = NULL,
  connect_timeout_seconds = NULL,
  idle_timeout_seconds = NULL,
  disable_stream_options = FALSE,
  api_format = c("auto", "chat", "responses")
)

Arguments

Method language_model()

Create a language model (always Chat Completions API).

Usage

OpenAIProvider$language_model(model_id = Sys.getenv("OPENAI_MODEL", "gpt-4o"))

Arguments

Returns

An OpenAILanguageModel object.

Method responses_model()

Create a language model using the Responses API.

Usage

OpenAIProvider$responses_model(model_id)

Arguments

Details

The Responses API is designed for:

• Models with built-in reasoning (o1, o3 series)

• Stateful multi-turn conversations (server maintains history)

• Advanced features like structured outputs

The model maintains conversation state internally via response IDs. Call model$reset() to start a fresh conversation.

Returns

An OpenAIResponsesLanguageModel object.

Method model()

Default-route factory. Picks chat vs responses based on the api_format set in create_openai(). Recommended entry point for callers that don't care which surface is used.

Usage

OpenAIProvider$model(model_id = Sys.getenv("OPENAI_MODEL", "gpt-4o"))

Arguments

Returns

A LanguageModelV1 instance.

Method smart_model()

Smart model factory that selects the API surface.

Usage

OpenAIProvider$smart_model(
  model_id,
  api_format = private$config$api_format %||% "auto"
)

Arguments

Details

When api_format = "auto", the method picks:

• Responses API for reasoning models (o1, o3, gpt-5, ...)

• Chat Completions API for everything else

Override per-call when the provider's default doesn't match the specific model you're about to use.

Returns

A language model object (either OpenAILanguageModel or OpenAIResponsesLanguageModel).

Method embedding_model()

Create an embedding model.

Usage

OpenAIProvider$embedding_model(model_id = "text-embedding-3-small")

Arguments

Returns

An OpenAIEmbeddingModel object.

Method image_model()

Create an image model.

Usage

OpenAIProvider$image_model(
  model_id = Sys.getenv("OPENAI_IMAGE_MODEL", "gpt-image-2")
)

Arguments

Returns

An OpenAIImageModel object.

Method create_conversation()

Create a server-side conversation object via POST /v1/conversations. Returns the parsed response, including the conversation id you can pass as conversation = "conv_..." to generate_text() / stream_text() so OpenAI manages the message history server-side instead of you sending the full transcript each turn.

Usage

OpenAIProvider$create_conversation(items = NULL, metadata = NULL)

Arguments

Returns

Parsed response list with at least id, object, created_at, metadata.

Method get_conversation()

Retrieve a conversation object by id.

Usage

OpenAIProvider$get_conversation(conversation_id)

Arguments

Returns

Parsed response list.

Method delete_conversation()

Delete a conversation object by id. Server-side history is irrecoverable after this call.

Usage

OpenAIProvider$delete_conversation(conversation_id)

Arguments

Returns

Parsed response list (typically list(id, object, deleted)).

Method clone()

The objects of this class are cloneable with this method.

Usage

OpenAIProvider$clone(deep = FALSE)

Arguments

OpenAI Responses Language Model Class

Description

Language model implementation for OpenAI's Responses API. This API is designed for stateful multi-turn conversations where the server maintains conversation history, and supports advanced features like:

• Built-in reasoning/thinking (for o1, o3 models)

• Server-side conversation state management via response IDs

• Structured output items (reasoning, message, tool calls)

The Responses API uses a different request/response format than Chat Completions:

• Request: input field instead of messages, optional previous_response_id

• Response: output array with typed items instead of choices

Super class

aisdk::LanguageModelV1 -> OpenAIResponsesLanguageModel

Methods

Public methods

• OpenAIResponsesLanguageModel$new()

• OpenAIResponsesLanguageModel$get_config()

• OpenAIResponsesLanguageModel$get_last_response_id()

• OpenAIResponsesLanguageModel$reset()

• OpenAIResponsesLanguageModel$do_generate()

• OpenAIResponsesLanguageModel$do_stream()

• OpenAIResponsesLanguageModel$format_tool_result()

• OpenAIResponsesLanguageModel$get_history_format()

• OpenAIResponsesLanguageModel$clone()

Method new()

Initialize the OpenAI Responses language model.

Usage

OpenAIResponsesLanguageModel$new(model_id, config, capabilities = list())

Arguments

Method get_config()

Get the configuration list.

Usage

OpenAIResponsesLanguageModel$get_config()

Returns

A list with provider configuration.

Method get_last_response_id()

Get the last response ID (for debugging/advanced use).

Usage

OpenAIResponsesLanguageModel$get_last_response_id()

Returns

The last response ID or NULL.

Method reset()

Reset the conversation state (clear response ID). Call this to start a fresh conversation.

Usage

OpenAIResponsesLanguageModel$reset()

Method do_generate()

Generate text (non-streaming) using Responses API.

Reasoning controls (reasoning_effort, reasoning_summary, nested reasoning = list(effort, summary, ...)) are translated into the Responses-API body$reasoning block. The include argument (character vector or list) is forwarded to body$include — pass c("reasoning.encrypted_content") to keep reasoning tokens across stateless turns. Any other unrecognized parameter falls through into the body via modifyList, matching the previous escape-hatch behavior.

Usage

OpenAIResponsesLanguageModel$do_generate(params)

Arguments

Returns

A GenerateResult object.

Method do_stream()

Generate text (streaming) using Responses API.

Usage

OpenAIResponsesLanguageModel$do_stream(params, callback)

Arguments

Returns

A GenerateResult object.

Method format_tool_result()

Format a tool execution result for Responses API.

Usage

OpenAIResponsesLanguageModel$format_tool_result(
  tool_call_id,
  tool_name,
  result_content
)

Arguments

Returns

A list formatted as a message for Responses API.

Method get_history_format()

Get the message format for Responses API.

Usage

OpenAIResponsesLanguageModel$get_history_format()

Method clone()

The objects of this class are cloneable with this method.

Usage

OpenAIResponsesLanguageModel$clone(deep = FALSE)

Arguments

Output Strategy Interface

Description

Output Strategy Interface

Output Strategy Interface

Details

Abstract R6 class defining the interface for output strategies. Subclasses must implement get_instruction() and validate().

Methods

Public methods

• OutputStrategy$new()

• OutputStrategy$get_instruction()

• OutputStrategy$validate()

• OutputStrategy$clone()

Method new()

Initialize the strategy.

Usage

OutputStrategy$new()

Method get_instruction()

Get the system prompt instruction for this strategy.

Usage

OutputStrategy$get_instruction()

Returns

A character string with instructions for the LLM.

Method validate()

Parse and validate the output text.

Usage

OutputStrategy$validate(text, is_final = FALSE)

Arguments

Returns

The parsed and validated object.

Method clone()

The objects of this class are cloneable with this method.

Usage

OutputStrategy$clone(deep = FALSE)

Arguments

Project Memory Class

Description

R6 class for managing persistent project memory using SQLite. Stores code snippets, error fixes, and execution graphs for resuming failed long-running jobs.

Public fields

Methods

Public methods

• ProjectMemory$new()

• ProjectMemory$store_snippet()

• ProjectMemory$store_fix()

• ProjectMemory$find_similar_fix()

• ProjectMemory$search_snippets()

• ProjectMemory$store_workflow_node()

• ProjectMemory$update_node_status()

• ProjectMemory$get_workflow()

• ProjectMemory$get_resumable_nodes()

• ProjectMemory$store_conversation()

• ProjectMemory$get_conversation()

• ProjectMemory$store_review()

• ProjectMemory$store_review_artifact()

• ProjectMemory$get_review()

• ProjectMemory$get_review_artifact()

• ProjectMemory$get_review_runtime_record()

• ProjectMemory$get_reviews_for_file()

• ProjectMemory$record_review_saveback()

• ProjectMemory$update_execution_result()

• ProjectMemory$append_review_event()

• ProjectMemory$update_review_status()

• ProjectMemory$get_pending_reviews()

• ProjectMemory$stats()

• ProjectMemory$clear()

• ProjectMemory$print()

• ProjectMemory$clone()

Method new()

Create or connect to a project memory database.

Usage

ProjectMemory$new(project_root = tempdir(), db_name = "memory.sqlite")

Arguments

Returns

A new ProjectMemory object.

Method store_snippet()

Store a successful code snippet for future reference.

Usage

ProjectMemory$store_snippet(
  code,
  description = NULL,
  tags = NULL,
  context = NULL
)

Arguments

Returns

The ID of the stored snippet.

Method store_fix()

Store an error fix for learning.

Usage

ProjectMemory$store_fix(
  original_code,
  error,
  fixed_code,
  fix_description = NULL
)

Arguments

Returns

The ID of the stored fix.

Method find_similar_fix()

Find a similar fix from memory.

Usage

ProjectMemory$find_similar_fix(error)

Arguments

Returns

A list with the fix details, or NULL if not found.

Method search_snippets()

Search for relevant code snippets.

Usage

ProjectMemory$search_snippets(query, limit = 10)

Arguments

Returns

A data frame of matching snippets.

Method store_workflow_node()

Store execution graph node for workflow persistence.

Usage

ProjectMemory$store_workflow_node(
  workflow_id,
  node_id,
  node_type,
  code,
  status = "pending",
  result = NULL,
  dependencies = NULL
)

Arguments

Returns

The database row ID.

Method update_node_status()

Update workflow node status.

Usage

ProjectMemory$update_node_status(workflow_id, node_id, status, result = NULL)

Arguments

Method get_workflow()

Get workflow state for resuming.

Usage

ProjectMemory$get_workflow(workflow_id)

Arguments

Returns

A list with workflow nodes and their states.

Method get_resumable_nodes()

Resume a failed workflow from the last successful point.

Usage

ProjectMemory$get_resumable_nodes(workflow_id)

Arguments

Returns

List of node IDs that need to be re-executed.

Method store_conversation()

Store a conversation turn for context.

Usage

ProjectMemory$store_conversation(session_id, role, content, metadata = NULL)

Arguments

Method get_conversation()

Get conversation history for a session.

Usage

ProjectMemory$get_conversation(session_id, limit = 100)

Arguments

Returns

A data frame of conversation messages.

Method store_review()

Store or update a human review for an AI-generated chunk.

Usage

ProjectMemory$store_review(
  chunk_id,
  file_path,
  chunk_label,
  prompt,
  response,
  status = "pending",
  ai_agent = NULL,
  uncertainty = NULL,
  session_id = NULL,
  review_mode = NULL,
  runtime_mode = NULL,
  artifact_json = NULL,
  execution_status = NULL,
  execution_output = NULL,
  final_code = NULL,
  error_message = NULL
)

Arguments

Returns

The database row ID.

Method store_review_artifact()

Store structured review artifact metadata for a chunk.

Usage

ProjectMemory$store_review_artifact(
  chunk_id,
  artifact,
  session_id = NULL,
  review_mode = NULL,
  runtime_mode = NULL
)

Arguments

Returns

Invisible TRUE.

Method get_review()

Get a review by chunk ID.

Usage

ProjectMemory$get_review(chunk_id)

Arguments

Returns

A list with review details, or NULL if not found.

Method get_review_artifact()

Get a parsed review artifact by chunk ID.

Usage

ProjectMemory$get_review_artifact(chunk_id)

Arguments

Returns

A list artifact, or NULL if none is stored.

Method get_review_runtime_record()

Get a review together with its parsed artifact.

Usage

ProjectMemory$get_review_runtime_record(chunk_id)

Arguments

Returns

A list with review and artifact, or NULL if not found.

Method get_reviews_for_file()

Get all reviews for a given source file.

Usage

ProjectMemory$get_reviews_for_file(file_path)

Arguments

Returns

A data frame of reviews ordered by updated time.

Method record_review_saveback()

Record a saveback lifecycle event for one or more chunk reviews.

Usage

ProjectMemory$record_review_saveback(
  chunk_ids,
  source_path,
  html_path = NULL,
  status = "requested",
  rerendered = FALSE,
  message = NULL
)

Arguments

Returns

Invisible TRUE.

Method update_execution_result()

Update execution result fields for a chunk review.

Usage

ProjectMemory$update_execution_result(
  chunk_id,
  execution_status,
  execution_output = NULL,
  final_code = NULL,
  error_message = NULL
)

Arguments

Returns

Invisible TRUE.

Method append_review_event()

Append an audit event for a reviewed chunk.

Usage

ProjectMemory$append_review_event(chunk_id, event_type, payload = NULL)

Arguments

Returns

The database row ID.

Method update_review_status()

Update review status.

Usage

ProjectMemory$update_review_status(chunk_id, status)

Arguments

Method get_pending_reviews()

Get pending reviews, optionally filtered by file.

Usage

ProjectMemory$get_pending_reviews(file_path = NULL)

Arguments

Returns

A data frame of pending reviews.

Method stats()

Get memory statistics.

Usage

ProjectMemory$stats()

Returns

A list with counts and sizes.

Method clear()

Clear all memory (use with caution).

Usage

ProjectMemory$clear(confirm = FALSE)

Arguments

Method print()

Print method for ProjectMemory.

Usage

ProjectMemory$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

ProjectMemory$clone(deep = FALSE)

Arguments

Provider Registry

Description

Manages registered providers and allows accessing models by ID.

Methods

Public methods

• ProviderRegistry$new()

• ProviderRegistry$register()

• ProviderRegistry$language_model()

• ProviderRegistry$embedding_model()

• ProviderRegistry$image_model()

• ProviderRegistry$list_providers()

• ProviderRegistry$clone()

Method new()

Initialize the registry.

Usage

ProviderRegistry$new(separator = ":")

Arguments

Method register()

Register a provider.

Usage

ProviderRegistry$register(id, provider)

Arguments

Method language_model()

Get a language model by ID.

Usage

ProviderRegistry$language_model(id)

Arguments

Returns

A LanguageModelV1 object.

Method embedding_model()

Get an embedding model by ID.

Usage

ProviderRegistry$embedding_model(id)

Arguments

Returns

An EmbeddingModelV1 object.

Method image_model()

Get an image model by ID.

Usage

ProviderRegistry$image_model(id)

Arguments

Returns

An ImageModelV1 object.

Method list_providers()

List all registered provider IDs.

Usage

ProviderRegistry$list_providers()

Returns

A character vector of provider IDs.

Method clone()

The objects of this class are cloneable with this method.

Usage

ProviderRegistry$clone(deep = FALSE)

Arguments

Agent Output Renderer (UI-agnostic contract)

Description

Renderer is the canonical, UI-agnostic contract for presenting an agent's streaming output. The agent runtime (driven by stream_text() / run_agent_runtime()) emits agent-output events purely through these semantic methods, so the same agent-output logic can be rendered in a terminal (the built-in cli backend, create_stream_renderer()), a web app (e.g. aisdk.shiny), a test/replay harness (create_capture_renderer()), or any custom UI – by implementing this interface.

The agent-output event model captures what an agent does as it responds:

• text – streamed assistant text, delivered incrementally via process_chunk(text, done); the final call usually has text = NULL and done = TRUE.

• thinking – a reasoning stream bracketed by start_thinking() and stop_thinking().

• tools – tool execution: render_tool_start(name, arguments) followed by render_tool_result(name, result, success, raw_result).

• steps – multi-step ReAct loop boundaries, reset_for_new_step().

Every method is a no-op in the base class, so the base class is itself a usable null renderer and a subclass need only override the events it cares about.

Methods

Public methods

• Renderer$process_chunk()

• Renderer$start_thinking()

• Renderer$stop_thinking()

• Renderer$render_tool_start()

• Renderer$render_tool_result()

• Renderer$reset_for_new_step()

• Renderer$clone()

Method process_chunk()

Render a chunk of streamed assistant text.

Usage

Renderer$process_chunk(text, done = FALSE)

Arguments

Returns

Invisibly NULL.

Method start_thinking()

Signal the start of a thinking/reasoning stream.

Usage

Renderer$start_thinking()

Returns

Invisibly NULL.

Method stop_thinking()

Signal the end of a thinking/reasoning stream.

Usage

Renderer$stop_thinking()

Returns

Invisibly NULL.

Method render_tool_start()

Render the start of a tool call.

Usage

Renderer$render_tool_start(name, arguments)

Arguments

Returns

Invisibly NULL.

Method render_tool_result()

Render a tool result.

Usage

Renderer$render_tool_result(name, result, success = TRUE, raw_result = NULL)

Arguments

Returns

Invisibly NULL.

Method reset_for_new_step()

Reset transient render state at a new ReAct step boundary.

Usage

Renderer$reset_for_new_step()

Returns

Invisibly NULL.

Method clone()

The objects of this class are cloneable with this method.

Usage

Renderer$clone(deep = FALSE)

Arguments

SSEAggregator R6 Class

Description

Accumulates streaming chunks into a final GenerateResult.

Handles two tool call formats:

• OpenAI format: Chunked deltas with index, id, function.name, function.arguments

• Anthropic format: content_block_start with id+name, then input_json_delta chunks

Methods

Public methods

• SSEAggregator$new()

• SSEAggregator$on_text_delta()

• SSEAggregator$on_reasoning_delta()

• SSEAggregator$on_reasoning_start()

• SSEAggregator$on_block_stop()

• SSEAggregator$on_tool_call_delta()

• SSEAggregator$on_tool_start()

• SSEAggregator$on_tool_input_delta()

• SSEAggregator$on_finish_reason()

• SSEAggregator$on_usage()

• SSEAggregator$on_raw_response()

• SSEAggregator$on_done()

• SSEAggregator$build_result()

• SSEAggregator$clone()

Method new()

Initialize the aggregator.

Usage

SSEAggregator$new(callback)

Arguments

Method on_text_delta()

Handle a text content delta.

Usage

SSEAggregator$on_text_delta(text)

Arguments

Method on_reasoning_delta()

Handle a reasoning/thinking content delta.

Usage

SSEAggregator$on_reasoning_delta(text)

Arguments

Method on_reasoning_start()

Signal the start of a reasoning block (Anthropic thinking).

Usage

SSEAggregator$on_reasoning_start()

Method on_block_stop()

Signal content block stop (closes reasoning if open).

Usage

SSEAggregator$on_block_stop()

Method on_tool_call_delta()

Handle OpenAI-format tool call deltas.

Usage

SSEAggregator$on_tool_call_delta(tool_calls)

Arguments

Method on_tool_start()

Handle Anthropic-format tool use block start.

Usage

SSEAggregator$on_tool_start(index, id, name, input = NULL)

Arguments

Method on_tool_input_delta()

Handle Anthropic-format input_json_delta.

Usage

SSEAggregator$on_tool_input_delta(index, partial_json)

Arguments

Method on_finish_reason()

Store finish reason.

Usage

SSEAggregator$on_finish_reason(reason)

Arguments

Method on_usage()

Store usage information.

Usage

SSEAggregator$on_usage(usage)

Arguments

Method on_raw_response()

Store last raw response for diagnostics.

Usage

SSEAggregator$on_raw_response(response)

Arguments

Method on_done()

Signal stream completion.

Usage

SSEAggregator$on_done()

Method build_result()

Finalize accumulated state into a GenerateResult.

Usage

SSEAggregator$build_result()

Returns

A GenerateResult object.

Method clone()

The objects of this class are cloneable with this method.

Usage

SSEAggregator$clone(deep = FALSE)

Arguments

SandboxManager Class

Description

R6 class that manages an isolated R environment for executing LLM-generated R code. Tools are bound as callable functions within this environment, enabling the LLM to batch-invoke and process data locally.

Methods

Public methods

• SandboxManager$new()

• SandboxManager$bind_tools()

• SandboxManager$execute()

• SandboxManager$get_tool_signatures()

• SandboxManager$get_env()

• SandboxManager$list_tools()

• SandboxManager$reset()

• SandboxManager$print()

• SandboxManager$clone()

Method new()

Initialize a new SandboxManager.

Usage

SandboxManager$new(
  tools = list(),
  preload_packages = c("dplyr", "purrr"),
  max_output_chars = 8000,
  parent_env = NULL
)

Arguments

Method bind_tools()

Bind Tool objects into the sandbox as callable R functions.

Usage

SandboxManager$bind_tools(tools)

Arguments

Returns

Invisible self (for chaining).

Method execute()

Execute R code in the sandbox environment.

Usage

SandboxManager$execute(code_str)

Arguments

Returns

A character string with captured stdout, or an error message.

Method get_tool_signatures()

Get human-readable signatures for all bound tools.

Usage

SandboxManager$get_tool_signatures()

Returns

A character string with Markdown-formatted tool documentation.

Method get_env()

Get the sandbox environment.

Usage

SandboxManager$get_env()

Returns

The R environment used by the sandbox.

Method list_tools()

Get list of bound tool names.

Usage

SandboxManager$list_tools()

Returns

Character vector of tool names available in the sandbox.

Method reset()

Reset the sandbox environment (clear all user variables). Tool bindings and preloaded packages are preserved.

Usage

SandboxManager$reset()

Method print()

Print method for SandboxManager.

Usage

SandboxManager$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

SandboxManager$clone(deep = FALSE)

Arguments

SharedSession Class

Description

R6 class representing an enhanced session for multi-agent systems. Extends ChatSession with:

• Execution context tracking (call stack, delegation history)

• Sandboxed code execution with safety guardrails

• Variable scoping and access control

• Comprehensive tracing and observability

Super class

aisdk::ChatSession -> SharedSession

Methods

Public methods

• SharedSession$new()

• SharedSession$push_context()

• SharedSession$pop_context()

• SharedSession$get_context()

• SharedSession$set_global_task()

• SharedSession$execute_code()

• SharedSession$get_var()

• SharedSession$set_var()

• SharedSession$list_vars()

• SharedSession$summarize_vars()

• SharedSession$create_scope()

• SharedSession$delete_scope()

• SharedSession$trace_event()

• SharedSession$get_trace()

• SharedSession$clear_trace()

• SharedSession$trace_summary()

• SharedSession$set_access_control()

• SharedSession$check_permission()

• SharedSession$get_sandbox_mode()

• SharedSession$set_sandbox_mode()

• SharedSession$print()

• SharedSession$clone()

Method new()

Initialize a new SharedSession.

Usage

SharedSession$new(
  model = NULL,
  system_prompt = NULL,
  tools = NULL,
  hooks = NULL,
  max_steps = 10,
  registry = NULL,
  sandbox_mode = "strict",
  trace_enabled = TRUE
)

Arguments

Method push_context()

Push an agent onto the execution stack.

Usage

SharedSession$push_context(agent_name, task, parent_agent = NULL)

Arguments

Returns

Invisible self for chaining.

Method pop_context()

Pop the current agent from the execution stack.

Usage

SharedSession$pop_context(result = NULL)

Arguments

Returns

The popped context, or NULL if stack was empty.

Method get_context()

Get the current execution context.

Usage

SharedSession$get_context()

Returns

A list with current_agent, depth, and delegation_stack.

Method set_global_task()

Set the global task (user's original request).

Usage

SharedSession$set_global_task(task)

Arguments

Returns

Invisible self for chaining.

Method execute_code()

Execute R code in a sandboxed environment.

Usage

SharedSession$execute_code(
  code,
  scope = "global",
  timeout_ms = 30000,
  capture_output = TRUE
)

Arguments

Returns

A list with result, output, error, and duration_ms.

Method get_var()

Get a variable from a specific scope.

Usage

SharedSession$get_var(name, scope = "global", default = NULL)

Arguments

Returns

The variable value or default.

Method set_var()

Set a variable in a specific scope.

Usage

SharedSession$set_var(name, value, scope = "global")

Arguments

Returns

Invisible self for chaining.

Method list_vars()

List variables in a scope.

Usage

SharedSession$list_vars(scope = "global", pattern = NULL)

Arguments

Returns

Character vector of variable names.

Method summarize_vars()

Get a summary of all variables in a scope.

Usage

SharedSession$summarize_vars(scope = "global")

Arguments

Returns

A data frame with name, type, and size information.

Method create_scope()

Create a new variable scope.

Usage

SharedSession$create_scope(scope_name, parent_scope = "global")

Arguments

Returns

Invisible self for chaining.

Method delete_scope()

Delete a variable scope.

Usage

SharedSession$delete_scope(scope_name)

Arguments

Returns

Invisible self for chaining.

Method trace_event()

Record a trace event.

Usage

SharedSession$trace_event(event_type, data = list())

Arguments

Returns

Invisible self for chaining.

Method get_trace()

Get the execution trace.

Usage

SharedSession$get_trace(event_types = NULL, agent = NULL)

Arguments

Returns

A list of trace events.

Method clear_trace()

Clear the execution trace.

Usage

SharedSession$clear_trace()

Returns

Invisible self for chaining.

Method trace_summary()

Get trace summary statistics.

Usage

SharedSession$trace_summary()

Returns

A list with event counts, agent activity, and timing info.

Method set_access_control()

Set access control for an agent.

Usage

SharedSession$set_access_control(agent_name, permissions)

Arguments

Returns

Invisible self for chaining.

Method check_permission()

Check if an agent has permission for an action.

Usage

SharedSession$check_permission(agent_name, action, target)

Arguments

Returns

TRUE if permitted, FALSE otherwise.

Method get_sandbox_mode()

Get sandbox mode.

Usage

SharedSession$get_sandbox_mode()

Returns

The current sandbox mode.

Method set_sandbox_mode()

Set sandbox mode.

Usage

SharedSession$set_sandbox_mode(mode)

Arguments

Returns

Invisible self for chaining.

Method print()

Print method for SharedSession.

Usage

SharedSession$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

SharedSession$clone(deep = FALSE)

Arguments

Skill Class

Description

R6 class representing a skill with progressive loading capabilities. A Skill consists of:

• Level 1: YAML frontmatter (name, description) - always loaded

• Level 2: SKILL.md body (detailed instructions) - on demand

• Level 3: R scripts (executable code) - executed by agent

Public fields

Methods

Public methods

• Skill$new()

• Skill$load()

• Skill$get_manifest()

• Skill$to_store_record()

• Skill$metadata_text()

• Skill$matches_paths()

• Skill$execute_script()

• Skill$list_scripts()

• Skill$list_resources()

• Skill$read_resource()

• Skill$get_asset_path()

• Skill$print()

• Skill$clone()

Method new()

Create a new Skill object by parsing a SKILL.md file.

Usage

Skill$new(path)

Arguments

Returns

A new Skill object.

Method load()

Load the full SKILL.md body content (Level 2).

Usage

Skill$load()

Returns

Character string containing the skill instructions.

Method get_manifest()

Return the raw SKILL.md frontmatter as a list.

Usage

Skill$get_manifest()

Returns

Named list of metadata fields.

Method to_store_record()

Export the skill to a structured record suitable for a skill store.

Usage

Skill$to_store_record(
  include_body = TRUE,
  include_files = TRUE,
  include_assets = FALSE
)

Arguments

Returns

A named list ready for JSON serialization.

Method metadata_text()

Return concise metadata text used for routing and listing.

Usage

Skill$metadata_text()

Returns

Character scalar.

Method matches_paths()

Check whether the skill's paths patterns match any provided file paths.

Usage

Skill$matches_paths(file_paths = character(0), cwd = NULL)

Arguments

Returns

Logical scalar.

Method execute_script()

Execute an R script from the skill's scripts directory (Level 3). Uses callr for safe, isolated execution.

Usage

Skill$execute_script(script_name, args = list())

Arguments

Returns

The result from the script execution.

Method list_scripts()