Package 'aisdk'

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 [email protected]

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

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

Description

Testing infrastructure for LLM-powered code. Provides testthat integration with custom expectations for evaluating AI agent performance, tool accuracy, and hallucination rates.

Description

Factory functions for creating standard library agents for common tasks. These agents are pre-configured with appropriate system prompts and tools for their respective specializations.

Description

AgentRegistry R6 class for storing and retrieving Agent instances. Used by the Flow system for agent delegation.

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

Description

Analyze an image with a multimodal language model.

Usage

analyze_image(model, image, prompt, system = NULL, registry = NULL, ...)

Arguments

Value

A GenerateResult.

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

Description

Provides diagnostic tools to test internet connectivity, DNS resolution, and API reachability.

Description

Convert common vector-like and tabular objects into a short text preview for summaries and inspection output.

Usage

as_preview_text(x, max_items = 5)

Arguments

Value

A character string preview or NULL when no preview is available.

Description

Collect recent R error context, active script context, session information, and workspace object summaries, then open console_chat() with that context as the initial prompt.

Collects the recent R error/session context and opens console_chat() with that context as the first user message. In RStudio, this function also reads the active source document when available, making it suitable as an Addin binding.

Usage

ask_ai(
  prompt = NULL,
  model = NULL,
  skills = "auto",
  skill = NULL,
  context = NULL,
  startup_dir = getwd(),
  working_dir = tempdir(),
  sandbox_mode = "permissive",
  stream = TRUE,
  verbose = FALSE,
  show_context = FALSE,
  max_context_chars = Inf,
  max_error_age_secs = 300,
  confirm_stale_errors = TRUE,
  ...
)

Arguments

Value

Invisibly returns the ChatSession from console_chat(), or a preview list when show_context = TRUE.

Description

Provides dynamic authorization hooks to pause Agent execution and request user permission for elevated risk operations.

Description

Self-healing runtime for R code execution. Implements a "Hypothesis-Fix-Verify" loop that feeds error messages, stack traces, and context back to an LLM for automatic error correction.

Execute R code with automatic error recovery using LLM assistance. When code fails, the error is analyzed and a fix is attempted automatically.

Usage

auto_fix(
  expr,
  model = NULL,
  max_attempts = 3,
  context = NULL,
  verbose = TRUE,
  memory = NULL
)

Arguments

Value

The result of successful execution, or an error if all attempts fail.

Examples

## Not run: 
# Simple usage - auto-fix a data transformation
result <- auto_fix({
  df <- read.csv("data.csv")
  df %>%
    filter(value > 100) %>%
    summarize(mean = mean(value))
})

# With context for better error understanding
result <- auto_fix(
  expr = {
    model <- lm(y ~ x, data = df)
  },
  context = "Fitting a linear regression model to predict sales"
)

## End(Not run)

Description

Utilities for caching tool execution results and other expensive operations.

Description

Wrap a tool with caching capabilities using the memoise package.

Usage

cache_tool(tool, cache = NULL)

Arguments

Value

A new Tool object that caches its execution.

Description

Try accessor functions in order and return the first successful result. Useful for extension authors who need compatibility across optional dependency APIs.

Usage

call_object_accessor(
  obj,
  fun_names,
  default = NULL,
  package = NULL,
  args = list()
)

Arguments

Value

The accessor result or default.

Description

Configure model routes for task capabilities such as vision inspection, image generation, or code review. These routes let a session keep one default chat model while specific capabilities use better-suited models.

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

Description

Tests connectivity to a specific LLM, provider, or URL. This is helpful for diagnosing network issues, DNS failures, or SSL problems.

Usage

check_api(model = NULL, url = NULL, registry = NULL)

Arguments

Value

A list containing diagnostic results (invisible).

Examples

if (interactive()) {
    # Test by passing a URL directly
    check_api(url = "https://api.openai.com/v1")

    # Test a model directly
    model <- create_openai()$language_model("gpt-4o")
    check_api(model)
}

Description

Analyze R code for unsafe function calls or operations before execution.

Usage

check_ast_safety(code_str)

Arguments

Value

The parsed AST if safe. Throws an error if unsafe.

Description

Check if code is compatible with the current SDK version and suggest migration steps if needed.

Usage

check_sdk_compatibility(code_version)

Arguments

Value

A list with compatible (logical) and suggestions (character vector).

Examples

if (interactive()) {
result <- check_sdk_compatibility("0.8.0")
if (!result$compatible) {
  cat("Migration needed:\n")
  cat(paste(result$suggestions, collapse = "\n"))
}
}

Description

Clear one or all configured capability model routes.

Usage

clear_capability_model(capability = NULL)

Arguments

Value

Invisibly returns the previous route list.

Description

Clears the tracked error and warning context used by ask_ai(). This is useful when you want to start a fresh debugging session without stale error messages from previous operations.

Usage

clear_error_context()

Value

Invisibly returns TRUE.

Examples

## Not run: 
# Clear stale errors before starting a new debugging session
clear_error_context()
ask_ai()

## End(Not run)

Description

Collect recent error details, traceback output, warnings, active script context, session information, and lightweight workspace object summaries.

Usage

collect_ai_context(
  script = NULL,
  error = NULL,
  traceback = NULL,
  warnings = NULL,
  include = c("error", "traceback", "warnings", "script", "session", "objects",
    "history"),
  max_context_chars = Inf,
  max_error_age_secs = 300,
  include_history = TRUE,
  max_history_lines = 10
)

Arguments

Value

A structured context list with class aisdk_ai_context.

Description

Provides feature flags, compatibility shims, and migration utilities for controlled breaking changes in the agent SDK.

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

Description

Helpers for reading project/global aisdk.yaml model configuration files.

Description

Interactive terminal chat interface for ChatSession. Provides a REPL (Read-Eval-Print Loop) for conversing with LLMs. By default, enables an intelligent terminal agent that can execute commands, manage files, and run R code through natural language.

Description

Creates a default agent for console_chat() that enables natural language interaction with the terminal. Users can ask the agent to run commands, execute R code, read/write files, and more through conversational language.

Description

Launch an interactive chat session in the R console. Supports streaming output, slash commands, and colorful display using the cli package.

The console UI has three presentation modes:

• clean: compact default output with a stable status bar

• inspect: keeps the compact transcript but adds a per-turn tool timeline and an overlay-backed inspector

• debug: shows detailed tool logs and thinking output for troubleshooting

In agent mode, console_chat() can execute shell and R tools, summarize tool progress inline, and open an inspector overlay for the latest turn or a specific tool. The current implementation uses a shared frame builder for the status bar, tool timeline, and overlay surfaces, while preserving an append-only terminal fallback.

By default, the console operates in minimal agent mode with four tools: bash, read_file, write_file, and edit_file. Set profile = "legacy" to restore the previous broad all-in-one agent, or agent = NULL for simple chat without tools.

Usage

console_chat(
  session = NULL,
  system_prompt = NULL,
  tools = NULL,
  hooks = NULL,
  stream = TRUE,
  verbose = FALSE,
  agent = "auto",
  skills = NULL,
  working_dir = tempdir(),
  sandbox_mode = "permissive",
  show_thinking = verbose,
  startup_dir = getwd(),
  initial_prompt = NULL,
  profile = c("minimal", "legacy"),
  extensions = "auto"
)

Arguments

Value

The ChatSession object (invisibly) when chat ends.

Examples

if (interactive()) {
  # Start with default agent (intelligent terminal mode)
  console_chat("openai:gpt-4o")

  # Start in debug mode with full tool logs
  console_chat("openai:gpt-4o", verbose = TRUE)

  # Simple chat mode without tools
  console_chat("openai:gpt-4o", agent = NULL)

  # Start with an existing session
  chat <- create_chat_session("anthropic:claude-3-5-sonnet-latest")
  console_chat(chat)

  # Start with a custom agent
  agent <- create_agent("MathAgent", "Does math", system_prompt = "You are a math wizard.")
  console_chat("openai:gpt-4o", agent = agent)

  # Available commands in the chat:
  # /quit or /exit - End the chat
  # /save [path]   - Save session to file
  # /load [path]   - Load session from file
  # /model         - Open the provider/model chooser
  # /model [id]    - Switch to a different model
  # /model current - Show the active model
  # /history       - Show conversation history
  # /stats         - Show token usage statistics
  # /clear         - Clear conversation history
  # /stream [on|off] - Toggle streaming mode
  # /inspect [on|off] - Toggle inspect mode
  # /inspect turn - Open overlay for the latest turn
  # /inspect tool <index> - Open overlay for a tool in the latest turn
  # /inspect next - Move inspector overlay to the next tool
  # /inspect prev - Move inspector overlay to the previous tool
  # /inspect close - Close the active inspect overlay
  # /debug [on|off]  - Toggle detailed tool/thinking output
  # /local [on|off]- Toggle local execution mode (Global Environment)
  # /help          - Show available commands
  # /agent [on|off] - Toggle agent mode
}

Description

Ask a yes/no question with numbered choices. Returns TRUE for yes, FALSE for no, or NULL if cancelled.

Usage

console_confirm(question)

Arguments

Value

TRUE if user selects Yes, FALSE for No, NULL if cancelled.

Examples

if (interactive()) {
  if (isTRUE(console_confirm("Overwrite existing file?"))) {
    message("Overwriting...")
  }
}

Description

Prompt the user for free-text input with optional default value.

Usage

console_input(prompt, default = NULL)

Arguments

Value

The user's input string, default if empty input and default is set, or NULL if empty input with no default.

Examples

if (interactive()) {
  name <- console_input("Project name", default = "my-project")
  api_key <- console_input("API key")
}

Description

Present a numbered list of choices and return the user's selection. Styled with cli to match the console chat interface. Similar to utils::menu() but with cli formatting.

Usage

console_menu(title, choices)

Arguments

Value

The index of the selected choice (integer), or NULL if cancelled (user enters 'q' or empty input).

Examples

if (interactive()) {
  selection <- console_menu("Which database?", c("PostgreSQL", "SQLite", "DuckDB"))
}

Description

Helpers for constructing and validating provider-neutral multimodal content blocks that can later be translated into provider-specific payloads.

Description

Creates an image content object for a multimodal message. Automatically handles URLs, data URIs, raw bytes, and local files. This is kept for backward compatibility and returns the provider-neutral image block used by multimodal providers.

Usage

content_image(image_path, media_type = "auto", detail = "auto")

Arguments

Value

A provider-neutral image block.

Description

Creates a text content object for a multimodal message. This is kept for backward compatibility and returns the provider-neutral text block used by multimodal providers.

Usage

content_text(text)

Arguments

Value

A list representing the text content.

Description

Utilities for capturing and summarizing R objects for LLM context.

Description

Internal helpers for estimating prompt occupancy, classifying context budget regimes, storing compact session-side context state, and assembling a budget-aware prompt view from raw session history.

Description

Internal helpers for collecting execution monitoring, system/device info, and R runtime state signals to populate context state fields.

Description

Resolve a compact context handle to either its summary metadata or a bounded detailed representation.

Usage

context_get(session, handle_id, detail = c("summary", "full"))

Arguments

Value

A list with handle metadata and optional bounded content.

Description

Public helpers for configuring adaptive context management on ChatSession objects without reaching into internal metadata keys.

Description

Search compact handles for live objects, memory entries, transcript segments, retrieval hits, and artifacts.

Usage

context_search(session, query, kinds = NULL, limit = 5L)

Arguments

Value

A list of matching context handles.

Description

User-facing high-level API functions for interacting with AI models.

Description

Functions for generating structured objects from LLMs using schemas.

Generate a structured R object (list) from a language model based on a schema. The model is instructed to output valid JSON matching the schema, which is then parsed and returned as an R list.

Usage

generate_object(
  model = NULL,
  prompt,
  schema,
  schema_name = "result",
  system = NULL,
  temperature = 0.3,
  max_tokens = NULL,
  mode = c("json", "tool"),
  registry = NULL,
  ...
)

Arguments

Value

A GenerateObjectResult with:

• object: The parsed R object (list)

• usage: Token usage information

• raw_text: The raw text output from the LLM

• finish_reason: The reason the generation stopped

Examples

if (interactive()) {
# Define a schema for the expected output
schema <- z_object(
  title = z_string(description = "Title of the article"),
  keywords = z_array(z_string()),
  sentiment = z_enum(c("positive", "negative", "neutral"))
)

# Generate structured object
result <- generate_object(
  model = "openai:gpt-4o",
  prompt = "Analyze this article: 'R programming is great for data science!'",
  schema = schema
)

print(result$object$title)
print(result$object$sentiment)
}

Description

Factory function to create a new Agent object.

Usage

create_agent(
  name,
  description,
  system_prompt = NULL,
  tools = NULL,
  skills = NULL,
  model = NULL,
  capability_models = NULL
)

Arguments

Value

An Agent object.

Examples

if (interactive()) {
  # Create a simple math agent
  math_agent <- create_agent(
    name = "MathAgent",
    description = "Performs arithmetic calculations",
    system_prompt = "You are a math assistant. Return only numerical results."
  )

  # Run the agent
  result <- math_agent$run("Calculate 2 + 2", model = "openai:gpt-4o")

  # Create an agent with skills
  stock_agent <- create_agent(
    name = "StockAnalyst",
    description = "Stock analysis agent",
    skills = "auto"
  )
}

Description

Factory function to create a new AgentRegistry.

Usage

create_agent_registry(agents = NULL)

Arguments

Value

An AgentRegistry object.

Examples

if (interactive()) {
# Create registry with agents
cleaner <- create_agent("Cleaner", "Cleans data")
plotter <- create_agent("Plotter", "Creates visualizations")

registry <- create_agent_registry(list(cleaner, plotter))
print(registry$list_agents())  # "Cleaner", "Plotter"
}

Description

Factory function to create an Anthropic provider.

Usage

create_anthropic(
  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

Value

An AnthropicProvider object.

Supported Models

• claude-opus-4-7: Anthropic's most capable model for complex reasoning and coding. (Reasoning, Vision, Tools, Structured) | ctx: 1000k

• claude-opus-4-6: Previous generation of Claude Opus with 1M context. (Reasoning, Vision, Tools, Structured) | ctx: 1000k

• claude-opus-4-5: Claude Opus 4.5 with 200K context. (Reasoning, Vision, Tools, Structured) | ctx: 200k

• claude-sonnet-4-6: Balanced model for coding and agentic workflows with 1M context. (Reasoning, Vision, Tools, Structured) | ctx: 1000k

• claude-sonnet-4-5: Claude Sonnet 4.5 with 200K context. (Reasoning, Vision, Tools, Structured) | ctx: 200k

• claude-sonnet-4: Original Claude Sonnet 4 with 200K context. (Reasoning, Vision, Tools, Structured) | ctx: 200k

• claude-haiku-4-5: Fast and cost-effective model for simple tasks and chatbots. (Vision, Tools, Structured) | ctx: 200k

Examples

if (interactive()) {
  anthropic <- create_anthropic(api_key = "sk-ant-...")
  model <- anthropic$language_model("claude-sonnet-4-20250514")
}

Description

Creates a tool that allows an agent to pause execution and ask the user for help, clarification, or guidance. This is reserved for real user decisions such as destructive actions, credentials, cost/permission gates, ambiguous requirements, or information only the user can provide.

Usage

create_ask_user_tool()

Details

The ask_user tool lets agents pause for genuine user decisions instead of guessing through risks or missing requirements.

The tool accepts:

• question: The main question or explanation to show the user (required)

• context: Optional context about why the agent is asking (what was tried, what failed)

• options: Optional list of suggested responses for the user to choose from

When options are provided, the user can either select a numbered option or type their own custom response.

Value

A Tool object that can be used with agents

Examples

## Not run: 
# Create the tool
ask_tool <- create_ask_user_tool()

# Use in an agent
agent <- Agent$new(
  name = "helper",
  tools = list(ask_tool, other_tools...)
)

# The agent can then use it when user input is required:
# ask_user(
#   question = "This will overwrite report.html. Should I continue?",
#   context = "The target file already exists in the project directory.",
#   options = ["Overwrite it", "Choose another path", "Cancel"]
# )

## End(Not run)

Description

Returns a CaptureRenderer that records agent-output events instead of displaying them. Call its events() method to retrieve the recorded events.

Usage

create_capture_renderer()

Value

A CaptureRenderer.

Description

Factory function to create a new ChatSession object.

Usage

create_chat_session(
  model = NULL,
  system_prompt = NULL,
  tools = NULL,
  hooks = NULL,
  max_steps = 10,
  metadata = NULL,
  agent = NULL
)

Arguments

Value

A ChatSession object.

Examples

if (interactive()) {
  # Create a chat session
  chat <- create_chat_session(
    model = "openai:gpt-4o",
    system_prompt = "You are a helpful R programming assistant."
  )

  # Create from an existing agent
  agent <- create_agent("MathAgent", "Does math", system_prompt = "You are a math wizard.")
  chat <- create_chat_session(model = "openai:gpt-4o", agent = agent)

  # Send messages
  response <- chat$send("How do I read a CSV file?")
  print(response$text)

  # Continue the conversation (history is maintained)
  response <- chat$send("What about Excel files?")

  # Check stats
  print(chat$stats())

  # Save session
  chat$save("my_session.rds")
}

Description

Creates an agent specialized in writing and executing R code. The agent can execute R code in the session environment, making results available to other agents. Enhanced version with better safety controls and debugging support.

Usage

create_coder_agent(
  name = "CoderAgent",
  safe_mode = TRUE,
  timeout_ms = 30000,
  max_output_lines = 200
)

Arguments

Value

An Agent object configured for R code execution.

Examples

if (interactive()) {
  coder <- create_coder_agent()
  session <- create_shared_session(model = "openai:gpt-4o")
  result <- coder$run(
    "Create a data frame with 3 rows and calculate the mean",
    session = session,
    model = "openai:gpt-4o"
  )
}

Description

Create atomic tools for computer abstraction layer. These tools provide a small set of primitives that agents can use to perform complex actions.

Usage

create_computer_tools(
  computer = NULL,
  working_dir = tempdir(),
  sandbox_mode = "permissive"
)

Arguments

Value

List of Tool objects

Description

Create the default intelligent terminal agent for console_chat(). This agent can execute commands, manage files, and run R code through natural language interaction.

Usage

create_console_agent(
  working_dir = tempdir(),
  sandbox_mode = "permissive",
  additional_tools = NULL,
  language = "auto",
  startup_dir = working_dir,
  skills = "auto",
  profile = c("minimal", "legacy"),
  extensions = "auto"
)

Arguments

Value

An Agent object configured for console interaction.

Examples

if (interactive()) {
    # Create default console agent
    agent <- create_console_agent()

    # Create with custom working directory
    agent <- create_console_agent(working_dir = "~/projects/myapp")

    # Use with console_chat
    console_chat("openai:gpt-4o", agent = agent)
}

Description

Create a set of tools optimized for console/terminal interaction. The default "minimal" profile exposes only bash, read_file, write_file, and edit_file. Use profile = "legacy" for the prior broad tool surface including R, image, Feishu, skill, and inspection tools.

Usage

create_console_tools(
  working_dir = tempdir(),
  sandbox_mode = "permissive",
  startup_dir = working_dir,
  profile = c("minimal", "legacy"),
  extensions = "auto"
)

Arguments

Value

A list of Tool objects.

Examples

if (interactive()) {
    tools <- create_console_tools()
    # Use with an agent or session
    session <- create_chat_session(model = "openai:gpt-4o", tools = tools)
}

Description

Build a normalized context-management configuration list.

Usage

create_context_management_config(
  mode = NULL,
  llm_synthesis = FALSE,
  synthesis_model = NULL,
  llm_synthesis_policy = NULL,
  context_window_override = NULL,
  max_output_tokens_override = NULL,
  project_memory_root = NULL,
  retrieval_providers = NULL,
  retrieval_provider_order = NULL,
  retrieval_provider_limits = NULL,
  retrieval_min_hits = NULL,
  retrieval_scoring_policy = NULL,
  retrieval_reranking = FALSE,
  retrieval_reranking_model = NULL,
  retrieval_reranking_policy = NULL
)

Arguments

Value

A normalized configuration list.

Description

Create ordinary Tool objects for searching handles, resolving handles, peeking live R objects, and launching bounded child sessions.

Usage

create_context_query_tools(session = NULL)

Arguments

Value

A list of Tool objects.

Description

Creates a dynamic wrapper around existing model classes (OpenAI, Anthropic) based on user-provided configuration. The returned provider can be registered in the global ProviderRegistry.

Usage

create_custom_provider(
  provider_name,
  base_url,
  api_key = NULL,
  api_format = c("chat_completions", "responses", "anthropic_messages"),
  use_max_completion_tokens = FALSE,
  disable_stream_options = TRUE,
  supports_native_tools = FALSE
)

Arguments

Value

A custom provider object with a language_model(model_id) method.

Description

Creates an agent specialized in data manipulation using dplyr and tidyr. The agent can filter, transform, summarize, and reshape data frames in the session environment.

Usage

create_data_agent(name = "DataAgent", safe_mode = TRUE)

Arguments

Value

An Agent object configured for data manipulation.

Examples

if (interactive()) {
  data_agent <- create_data_agent()
  session <- create_shared_session(model = "openai:gpt-4o")
  session$set_var("sales", data.frame(
    product = c("A", "B", "C"),
    revenue = c(100, 200, 150)
  ))
  result <- data_agent$run(
    "Calculate total revenue and find the top product",
    session = session,
    model = "openai:gpt-4o"
  )
}

Description

Build the package default semantic adapter registry used for semantic object inspection. The default registry includes built-in generic adapters and can optionally apply extension registrars.

Usage

create_default_semantic_adapter_registry(
  include_workflow_hints = TRUE,
  extension_registrars = NULL
)

Arguments

Details

This function is safe for extension packages that want the standard aisdk registry baseline before registering additional adapters.

Value

A SemanticAdapterRegistry object.

Description

Generate embeddings for text using an embedding model.

Usage

create_embeddings(model, value, registry = NULL)

Arguments

Value

A list with embeddings and usage information.

Examples

if (interactive()) {
  model <- create_openai()$embedding_model("text-embedding-3-small")
  result <- create_embeddings(model, "Hello, world!")
  print(length(result$embeddings[[1]]))
}

Description

Creates an agent specialized in R environment and package management. The agent can check, install, and manage R packages with safety controls.

Usage

create_env_agent(
  name = "EnvAgent",
  allow_install = FALSE,
  allowed_repos = "https://cloud.r-project.org"
)

Arguments

Value

An Agent object configured for environment management.

Examples

if (interactive()) {
  env_agent <- create_env_agent(allow_install = TRUE)
  result <- env_agent$run(
    "Check if tidyverse is installed and load it",
    session = session,
    model = "openai:gpt-4o"
  )
}

Description

Creates an agent specialized in file system operations using fs and readr. The agent can read, write, and manage files with safety guardrails.

Usage

create_file_agent(
  name = "FileAgent",
  allowed_dirs = ".",
  allowed_extensions = c("csv", "tsv", "txt", "json", "rds", "rda", "xlsx", "xls")
)

Arguments

Value

An Agent object configured for file operations.

Examples

if (interactive()) {
  file_agent <- create_file_agent(
    allowed_dirs = c("./data", "./output"),
    allowed_extensions = c("csv", "json", "txt", "rds")
  )
  result <- file_agent$run(
    "Read the sales.csv file and store it as 'sales_data'",
    session = session,
    model = "openai:gpt-4o"
  )
}

Description

Factory function to create a Gemini provider.

Usage

create_gemini(
  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

Value

A GeminiProvider object.

Supported Models

• gemini-3-pro-preview: Preview Gemini 3 Pro model for advanced reasoning, coding, multimodal understanding, and agentic workflows. (Reasoning, Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-3-pro-preview-customtools: Gemini 3 Pro Preview endpoint tuned for agentic workflows that combine bash-like and custom tools. (Reasoning, Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-3-flash-preview: Preview Gemini 3 Flash model for frontier-class performance at lower latency and cost. (Reasoning, Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-2.5-pro: Stable Gemini 2.5 Pro model for complex reasoning, coding, STEM, and long-context analysis. (Reasoning, Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-2.5-flash: Stable Gemini 2.5 Flash model for price-performance, low-latency, high-volume, and agentic tasks. (Reasoning, Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-2.5-flash-lite: Stable Gemini 2.5 Flash-Lite model for cost-efficient high-throughput multimodal tasks. (Reasoning, Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-2.0-flash: Deprecated Gemini 2.0 Flash model with 1M context; migrate to Gemini 3 Flash Preview or a newer model. (Vision, Tools, Audio, Structured, Search) | ctx: 1049k

• gemini-2.0-flash-lite: Deprecated Gemini 2.0 Flash-Lite model; migrate to Gemini 2.5 Flash-Lite or a newer model. (Vision, Tools, Audio, Structured) | ctx: 1049k

• gemini-3-pro-image-preview: Preview Gemini 3 Pro image generation and editing model for professional-grade visuals and accurate text rendering. (Reasoning, Vision, Image-Out, Image-Edit, Structured, Search) | ctx: 66k

• gemini-2.5-flash-image: Stable Gemini 2.5 Flash image generation and conversational editing model for high-volume creative workflows. (Vision, Image-Out, Image-Edit, Structured) | ctx: 66k

Examples

if (interactive()) {
    gemini <- create_gemini(api_key = "AIza...")
    model <- gemini$language_model("gemini-2.5-flash")
}

Description

Helper to create a HookHandler from a list of functions.

Usage

create_hooks(...)

Arguments

Value

A HookHandler object.

Description

Returns a Renderer that discards every event. Use it for headless or library contexts where agent output should not be displayed.

Usage

create_null_renderer()

Value

A Renderer.

Description

Factory function to create an OpenAI provider.

Usage

create_openai(
  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

Value

An OpenAIProvider object.

Supported Models

• gpt-5.5: Latest OpenAI frontier model for complex reasoning, coding, and professional workflows. (Reasoning, Vision, Tools, Structured) | ctx: 1050k

• gpt-5.5-pro: Higher-compute GPT-5.5 variant for the hardest professional and reasoning tasks. (Reasoning, Vision, Tools, Structured) | ctx: 1050k

• gpt-5.4: Frontier model for coding and professional work with 1.05M context. (Reasoning, Vision, Tools, Structured) | ctx: 1050k

• gpt-5.4-pro: Higher-compute GPT-5.4 variant for more precise responses on difficult tasks. (Reasoning, Vision, Tools, Structured) | ctx: 1050k

• gpt-5.4-mini: Strong mini model for coding, computer use, and subagents. (Reasoning, Vision, Tools, Structured) | ctx: 400k

• gpt-5.4-nano: Lowest-cost GPT-5.4-class model for high-volume classification, extraction, ranking, and subagents. (Reasoning, Vision, Tools, Structured) | ctx: 400k

• gpt-5.3-codex: Agentic coding model optimized for Codex-like environments. (Reasoning, Vision, Tools, Structured) | ctx: 400k

• gpt-5: Reasoning model for coding and agentic tasks across domains. (Reasoning, Vision, Tools, Structured) | ctx: 400k

• gpt-5-mini: Cost-sensitive, low-latency GPT-5 model for well-defined tasks and precise prompts. (Reasoning, Vision, Tools, Structured) | ctx: 400k

• gpt-5-nano: Fastest and lowest-cost GPT-5 model for summarization, classification, and routing. (Reasoning, Vision, Tools, Structured) | ctx: 400k

• gpt-4.1: Smart non-reasoning model with strong instruction following and tool calling. (Vision, Tools, Structured) | ctx: 1048k

• gpt-4.1-mini: Smaller, faster GPT-4.1 model with long-context support. (Vision, Tools, Structured) | ctx: 1048k

• gpt-4.1-nano: Fastest and lowest-cost GPT-4.1 model for simple tasks. (Vision, Tools, Structured) | ctx: 1048k

• gpt-4o: Legacy multimodal GPT model with broad ecosystem support. (Vision, Tools, Structured) | ctx: 128k

• gpt-4o-mini: Fast, affordable GPT-4o model for focused tasks. (Vision, Tools, Structured) | ctx: 128k

• ... and 6 more models. Use list_models("openai") to see all.

Token Limit Parameters

The SDK provides a unified max_tokens parameter that automatically maps to the correct API field based on the model and API type:

• Chat API (standard models): max_tokens -> max_tokens

• Chat API (o1/o3 models): max_tokens -> max_completion_tokens

• Responses API: max_tokens -> max_output_tokens (total: reasoning + answer)

For advanced users who need fine-grained control:

• max_completion_tokens: Explicitly set completion tokens (Chat API, o1/o3)

• max_output_tokens: Explicitly set total output limit (Responses API)

• max_answer_tokens: Limit answer only, excluding reasoning (Responses API, Volcengine-specific)

Examples

if (interactive()) {
  # Basic usage with Chat Completions API
  openai <- create_openai(api_key = "sk-...")
  model <- openai$language_model("gpt-4o")
  result <- generate_text(model, "Hello!")

  # Using Responses API for reasoning models
  openai <- create_openai()
  model <- openai$responses_model("o1")
  result <- generate_text(model, "Solve this math problem...")
  print(result$reasoning) # Access chain-of-thought

  # Smart model selection (auto-detects best API)
  model <- openai$smart_model("o3-mini") # Uses Responses API
  model <- openai$smart_model("gpt-4o") # Uses Chat Completions API

  # Token limits - unified interface
  # For standard models: limits generated content
  result <- model$generate(messages = msgs, max_tokens = 1000)

  # For o1/o3 models: automatically maps to max_completion_tokens
  model_o1 <- openai$language_model("o1")
  result <- model_o1$generate(messages = msgs, max_tokens = 2000)

  # For Responses API: automatically maps to max_output_tokens (total limit)
  model_resp <- openai$responses_model("o1")
  result <- model_resp$generate(messages = msgs, max_tokens = 2000)

  # Advanced: explicitly control answer-only limit (Volcengine Responses API)
  result <- model_resp$generate(messages = msgs, max_answer_tokens = 500)

  # Multi-turn conversation with Responses API
  model <- openai$responses_model("o1")
  result1 <- generate_text(model, "What is 2+2?")
  result2 <- generate_text(model, "Now multiply that by 3") # Remembers context
  model$reset() # Start fresh conversation
}

Description

Create a hook that enforces a permission mode for tool execution.

Usage

create_permission_hook(
  mode = c("implicit", "explicit", "escalate"),
  allowlist = c("search_web", "read_resource", "read_file")
)

Arguments

Value

A HookHandler object.

Description

Creates an agent specialized in breaking down complex tasks into steps using chain-of-thought reasoning. The planner helps decompose problems and create action plans.

Usage

create_planner_agent(name = "PlannerAgent")

Arguments

Value

An Agent object configured for planning and reasoning.

Examples

if (interactive()) {
  planner <- create_planner_agent()
  result <- planner$run(
    "How should I approach building a machine learning model for customer churn?",
    model = "openai:gpt-4o"
  )
}

Description

Creates a meta-tool (execute_r_code) backed by a SandboxManager. This single tool replaces all individual tools for the LLM, enabling batch execution, data filtering, and local computation.

Usage

create_r_code_tool(sandbox)

Arguments

Value

A Tool object named execute_r_code.

Description

Create built-in read-only tools for live R context inspection.

Usage

create_r_context_tools()

Value

A list of Tool objects.

Description

Build Tool objects that let an Agent enrich diagnostic context on its own.

Usage

create_r_introspect_tools()

Value

A list of two Tool objects: r_eval and r_session_state.

Examples

## Not run: 
tools <- create_r_introspect_tools()
agent <- create_agent(
  name = "Diagnostician",
  tools = tools,
  model = "openai:gpt-4o"
)

## End(Not run)

Description

Generates a system prompt section that instructs the LLM how to use the R code sandbox effectively.

Usage

create_sandbox_system_prompt(sandbox)

Arguments

Value

A character string to append to the system prompt.

Description

Inspects an R function and generates a z_object schema based on its arguments and default values.

Usage

create_schema_from_func(
  func,
  include_args = NULL,
  exclude_args = NULL,
  params = NULL,
  func_name = NULL,
  type_mode = c("infer", "any")
)

Arguments

Value

A z_object schema.

Examples

if (interactive()) {
my_func <- function(a = 1, b = "text", c = TRUE) {}
schema <- create_schema_from_func(my_func)
print(schema)

# Override defaults
schema_override <- create_schema_from_func(my_func, params = list(a = 99))
}

Description

Build a semantic adapter that can describe and inspect domain-specific R objects. Adapters are registered into a semantic adapter registry and selected by supports(obj) predicates at runtime.

Usage

create_semantic_adapter(
  name,
  supports,
  capabilities = character(0),
  priority = 0,
  describe_identity = NULL,
  describe_schema = NULL,
  describe_semantics = NULL,
  peek = NULL,
  slice = NULL,
  list_accessors = NULL,
  estimate_cost = NULL,
  provenance = NULL,
  validate_action = NULL,
  render_summary = NULL,
  render_inspection = NULL
)

Arguments

Details

This constructor is part of the public semantic adapter authoring API for extension packages.

Adapter callbacks are optional unless noted otherwise.

supports(obj) should return a single TRUE or FALSE value and must not error for unsupported objects.

The structured callbacks describe_identity(), describe_schema(), describe_semantics(), estimate_cost(), and provenance() should return named lists when supplied.

list_accessors() should return a character vector of recommended accessors.

validate_action() should return a named list with fields such as status, reason, category, and expensive.

render_summary() and render_inspection() should return single character strings suitable for user-facing output.

Value

A SemanticAdapter object.

Description

Create a registry for semantic adapters. The registry resolves the highest priority adapter whose supports(obj) predicate matches an object.

Usage

create_semantic_adapter_registry(adapters = list())

Arguments

Details

This constructor is part of the public semantic adapter authoring API for extension packages.

The returned registry exposes register(), unregister(), get_adapter(), list_adapters(), register_workflow_hint(), list_workflow_hints(), resolve_workflow_hint(), and resolve() methods.

Value

A SemanticAdapterRegistry object.

Description

Creates a session using either the new SharedSession or legacy ChatSession based on feature flags. This provides a migration path for existing code.

Usage

create_session(
  model = NULL,
  system_prompt = NULL,
  tools = NULL,
  hooks = NULL,
  max_steps = 10,
  ...
)

Arguments

Value

A SharedSession or ChatSession object.

Examples

if (interactive()) {
# Automatically uses SharedSession if feature enabled
session <- create_session(model = "openai:gpt-4o")

# Force legacy session
sdk_set_feature("use_shared_session", FALSE)
session <- create_session(model = "openai:gpt-4o")
}

Description

Factory function to create a new SharedSession object.

Usage

create_shared_session(
  model = NULL,
  system_prompt = NULL,
  tools = NULL,
  hooks = NULL,
  max_steps = 10,
  sandbox_mode = "strict",
  trace_enabled = TRUE
)

Arguments

Value

A SharedSession object.

Examples

if (interactive()) {
# Create a shared session for multi-agent use
session <- create_shared_session(
  model = "openai:gpt-4o",
  sandbox_mode = "strict",
  trace_enabled = TRUE
)

# Execute code safely
result <- session$execute_code("x <- 1:10; mean(x)")

# Check trace
print(session$trace_summary())
}

Description

Creates an advanced agent specialized in creating, testing, and refining new skills. It follows a rigorous "Ingest -> Design -> Implement -> Verify" workflow.

Usage

create_skill_architect_agent(
  name = "SkillArchitect",
  registry = NULL,
  model = NULL
)

Arguments

Value

An Agent object configured for skill architecture.

Description

Convenience function to create and populate a SkillRegistry.

Usage

create_skill_registry(path, recursive = FALSE)

Arguments

Value

A populated SkillRegistry object.

Examples

if (interactive()) {
# Scan a skills directory
registry <- create_skill_registry(".aimd/skills")

# List available skills
registry$list_skills()

# Get a specific skill
skill <- registry$get_skill("seurat_analysis")
}

Description

Create the built-in tools for interacting with skills.

Usage

create_skill_tools(registry)

Arguments

Value

A list of Tool objects.

Description

Creates an AgentRegistry pre-populated with standard library agents based on feature flags.

Usage

create_standard_registry(
  include_data = TRUE,
  include_file = TRUE,
  include_env = TRUE,
  include_coder = TRUE,
  include_visualizer = TRUE,
  include_planner = TRUE,
  file_allowed_dirs = ".",
  env_allow_install = FALSE
)

Arguments

Value

An AgentRegistry object.

Examples

if (interactive()) {
# Create registry with all standard agents
registry <- create_standard_registry()

# Create registry with only data and visualization agents
registry <- create_standard_registry(
  include_file = FALSE,
  include_env = FALSE,
  include_planner = FALSE
)
}

Description

Create Telemetry

Usage

create_telemetry(trace_id = NULL, emit = TRUE)

Arguments

Value

A Telemetry object.

Description

Creates an agent specialized in creating data visualizations using ggplot2. Enhanced version with plot type recommendations, theme support, and automatic data inspection.

Usage

create_visualizer_agent(
  name = "VisualizerAgent",
  output_dir = NULL,
  default_theme = "theme_minimal",
  default_width = 8,
  default_height = 6
)

Arguments

Value

An Agent object configured for data visualization.

Examples

if (interactive()) {
  visualizer <- create_visualizer_agent()
  session <- create_shared_session(model = "openai:gpt-4o")
  session$set_var("df", data.frame(x = 1:10, y = (1:10)^2))
  result <- visualizer$run(
    "Create a scatter plot of df showing the relationship between x and y",
    session = session,
    model = "openai:gpt-4o"
  )
}

Description

Specialized wrapper around create_schema_from_func for ggtree/ggplot2 functions. Handles common mapping and data arguments specifically.

Usage

create_z_ggtree(func, layer = NULL)

Arguments

Value

A z_object schema.

Description

Return the standard skill search roots in increasing priority order: bundled package skills, installed user skills, project skills, then explicitly configured roots.

Usage

default_skill_roots(project_dir = getwd(), include_missing = FALSE)

Arguments

Value

Character vector of skill root directories.

Description

Edit images using an image editing model.

Usage

edit_image(
  model,
  image,
  prompt = NULL,
  mask = NULL,
  output_dir = tempdir(),
  registry = NULL,
  ...
)

Arguments

Value

A GenerateImageResult.

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

Description

Check if API tests should be enabled

Usage

enable_api_tests()

Value

TRUE if API tests are enabled and keys are available, FALSE otherwise

Description

Execute a list of tool calls returned by an LLM. This function safely executes each tool, handling errors gracefully and returning a standardized result format.

Implements multi-layer defense strategy:

1. Tool name repair (case fixing, snake_case conversion, fuzzy matching)

2. Invalid tool routing for graceful degradation

3. Argument parsing with JSON repair

4. Error capture and structured error responses

Usage

execute_tool_calls(
  tool_calls,
  tools,
  hooks = NULL,
  envir = NULL,
  repair_enabled = TRUE
)

Arguments

Value

A list of execution results, each containing:

• id: The tool call ID

• name: The tool name

• result: The execution result (or error message)

• is_error: TRUE if an error occurred during execution

Description

Custom testthat expectation that evaluates whether an LLM response meets specified criteria. Uses an LLM judge to assess the response.

Usage

expect_llm_pass(response, criteria, model = NULL, threshold = 0.7, info = NULL)

Arguments

Value

Invisibly returns the evaluation result.

Examples

if (interactive()) {
  test_that("agent answers math questions correctly", {
    result <- generate_text(
      model = "openai:gpt-4o",
      prompt = "What is 2 + 2?"
    )
    expect_llm_pass(result, "The response should contain the number 4")
  })
}

Description

Test that an LLM response does not contain hallucinated information when compared against ground truth.

Usage

expect_no_hallucination(
  response,
  ground_truth,
  model = NULL,
  tolerance = 0.1,
  info = NULL
)

Arguments

Description

Test that an agent selects the correct tool(s) for a given task.

Usage

expect_tool_selection(result, expected_tools, exact = FALSE, info = NULL)

Arguments

Description

Lightweight extension registry for console slash commands and optional tools.

Description

Extract schema-constrained structured data from an image using a multimodal language model.

Usage

extract_from_image(
  model,
  image,
  schema,
  prompt = "Extract the requested structured information from this image.",
  system = NULL,
  registry = NULL,
  ...
)

Arguments

Value

A GenerateResult.

Description

Fetch available models from API provider

Usage

fetch_api_models(provider, api_key = NULL, base_url = NULL)

Arguments

Value

A data frame with 'id' column and capability flag columns

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

Description

Generate images using an image generation model.

Usage

generate_image(model, prompt, output_dir = tempdir(), registry = NULL, ...)

Arguments