LeadAgent R6 Class

A LeadAgent is an agent that can delegate tasks to specialized sub-agents. It automatically has a delegate_to_agent tool that allows it to spawn sub-agents based on registered AgentDefinitions.

Super class

Agent -> LeadAgent

Active bindings

sub_agent_defs

Read-only snapshot of registered AgentDefinitions.

Methods

Public methods

• LeadAgent$new()

• LeadAgent$register_sub_agent()

• LeadAgent$available_sub_agents()

• LeadAgent$parallel_delegate()

• LeadAgent$parallel_delegate_async()

• LeadAgent$list_subagents()

• LeadAgent$get_subagent_results()

• LeadAgent$get_subagent_messages()

• LeadAgent$print()

• LeadAgent$clone()

Inherited methods

• Agent$add_hook()
• Agent$add_turn()
• Agent$chat()
• Agent$chat_async()
• Agent$chat_structured()
• Agent$chat_structured_async()
• Agent$checkpoint()
• Agent$compact()
• Agent$cost()
• Agent$get_context_turns()
• Agent$get_cost()
• Agent$get_model()
• Agent$get_model_object()
• Agent$get_permission_mode()
• Agent$get_provider()
• Agent$get_system_prompt()
• Agent$get_tokens()
• Agent$get_tools()
• Agent$get_turns()
• Agent$interrupt()
• Agent$last_compaction()
• Agent$last_run()
• Agent$last_turn()
• Agent$list_checkpoints()
• Agent$load_mcp()
• Agent$load_session()
• Agent$load_skill()
• Agent$mcp_status()
• Agent$mcp_tools()
• Agent$on_tool_request()
• Agent$on_tool_result()
• Agent$pending_approval()
• Agent$provider()
• Agent$register_tool()
• Agent$register_tools()
• Agent$resolve_tool_result()
• Agent$resume_approval()
• Agent$rewind_files()
• Agent$run()
• Agent$run_async()
• Agent$run_sync()
• Agent$save_session()
• Agent$session_id()
• Agent$set_model()
• Agent$set_permission_mode()
• Agent$set_system_prompt()
• Agent$set_tools()
• Agent$set_turns()
• Agent$skills()
• Agent$stream()
• Agent$stream_async()
• Agent$token_count()
• Agent$turns()
• Agent$usage()

---

LeadAgent$new()

Create a new LeadAgent.

Usage

LeadAgent$new(
  chat,
  sub_agents = list(),
  tools = list(),
  system_prompt = NULL,
  permissions = NULL,
  usage_limits = NULL,
  context_policy = ContextPolicy(),
  enable_file_checkpointing = FALSE,
  file_checkpoint_max_file_bytes = 50 * 1024^2,
  file_checkpoint_max_journal_bytes = 250 * 1024^2,
  working_dir = getwd(),
  session_id = NULL,
  run_context = list(),
  agent_id = NULL,
  agent_name = NULL,
  fallback_chats = list()
)

Arguments

chat

An ellmer Chat object

sub_agents

List of agent_definition() objects

tools

Additional tools for the lead agent

system_prompt

System prompt for the lead agent

permissions

Permissions for the lead agent (also applied to sub-agents)

usage_limits

Optional UsageLimits for each lead-agent run.

context_policy

A ContextPolicy controlling automatic compaction and durable offloading of large tool results for the lead agent and its delegated agents.

enable_file_checkpointing

Whether to journal reversible file preimages in one workspace journal shared by the lead agent and its delegated agents.

file_checkpoint_max_file_bytes

Maximum bytes captured for one file preimage. Defaults to 50 MiB.

file_checkpoint_max_journal_bytes

Maximum aggregate serialized bytes for workspace checkpoint records, markers, metadata, and pending captures. Defaults to 250 MiB.

working_dir

Working directory

session_id

Optional stable session identifier used for correlation. A unique identifier is generated by default.

run_context

Immutable canonical product context inherited by lead runs and delegated agents.

agent_id

Optional stable identifier for this LeadAgent instance.

agent_name

Optional human-readable LeadAgent name.

fallback_chats

Ordered configured fallback Chats for the lead. Child definitions inherit the selected provider, without an implicit fallback policy of their own. See Agent.

Returns

A new LeadAgent object

---

LeadAgent$register_sub_agent()

Register a new sub-agent definition.

Usage

LeadAgent$register_sub_agent(definition)

Arguments

definition

An agent_definition() object

Returns

Invisible self

---

LeadAgent$available_sub_agents()

Get available sub-agent names.

Usage

LeadAgent$available_sub_agents()

Returns

Character vector of sub-agent names

---

LeadAgent$parallel_delegate()

Run independent, stateless responders concurrently.

Each selected AgentDefinition gets a fresh conversation and at most one model request. Definitions with tools, skills, or MCP servers are rejected. This is tier-1 fan-out, not background tool-using agents. Results preserve input order, including failures and unstarted tasks.

Usage

LeadAgent$parallel_delegate(
  tasks,
  max_active = 2L,
  mode = "stateless",
  usage_limits = NULL,
  run_context = list()
)

Arguments

tasks

A named character vector of tasks. Names select unique registered AgentDefinitions.

max_active

Maximum simultaneous responders.

mode

Execution contract. Currently only "stateless" is supported.

usage_limits

Optional batch-wide UsageLimits. Unset fields inherit the lead's defaults. Requests are reserved before dispatch; token and cost ceilings are divided across each concurrent wave and checked after responses, with possible overage by one response per active responder.

run_context

Additional immutable context for the batch.

Returns

A list with mode, named results (AgentResult or NULL), named errors, named status, and an aggregate run (AgentResult). $last_run() retains the aggregate run. The lead's conversation is unchanged. Failed responders do not discard successful siblings.

---

LeadAgent$parallel_delegate_async()

Run stateless fan-out without blocking the R event loop.

Usage

LeadAgent$parallel_delegate_async(
  tasks,
  max_active = 2L,
  mode = "stateless",
  usage_limits = NULL,
  run_context = list()
)

Arguments

tasks, max_active, mode, usage_limits, run_context

See $parallel_delegate().

Returns

A promise resolving to the same batch result as $parallel_delegate(). $interrupt() cancels queued work and asks active responders to stop at their next supported provider boundary.

---

LeadAgent$list_subagents()

List delegated sub-agent runs, including failures.

Usage

LeadAgent$list_subagents()

Returns

Data frame with one row per sub-agent run

---

LeadAgent$get_subagent_results()

Get retained results from delegated sub-agent runs.

Usage

LeadAgent$get_subagent_results(agent_name = NULL, delegation_id = NULL)

Arguments

agent_name

Optional sub-agent name filter

delegation_id

Optional delegation identifier filter

Returns

List of AgentResult objects or NULL entries for failed runs

---

LeadAgent$get_subagent_messages()

Get stored turn history for delegated sub-agent runs.

Usage

LeadAgent$get_subagent_messages(agent_name = NULL, session_id = NULL)

Arguments

agent_name

Optional sub-agent name filter

session_id

Optional sub-agent session id filter

Returns

List of turn histories

---

LeadAgent$print()

Print the lead agent.

Usage

LeadAgent$print()

---

LeadAgent$clone()

The objects of this class are cloneable with this method.

Usage

LeadAgent$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.