Agent that delegates to subagents

An Agent that can hand tasks to subagents. Its model gets a delegate_to_agent tool for picking a registered agent_definition(); each delegation runs a new subagent in its own conversation and returns its answer. See vignette("multi-agent").

Super class

Agent -> LeadAgent

Active bindings

sub_agent_defs

A copy of the registered definitions. Use $register_sub_agent() to add one.

Methods

Public methods

• LeadAgent$new()

• LeadAgent$set_delegation_sources()

• LeadAgent$register_sub_agent()

• LeadAgent$available_sub_agents()

• LeadAgent$parallel_delegate()

• LeadAgent$parallel_delegate_async()

• LeadAgent$interrupt()

• LeadAgent$print()

• LeadAgent$clone()

Inherited methods

• Agent$add_hook()
• Agent$add_turn()
• Agent$cancel_agent()
• Agent$chat()
• Agent$chat_async()
• Agent$chat_structured()
• Agent$chat_structured_async()
• Agent$checkpoint()
• Agent$compact()
• Agent$continue_agent()
• Agent$continue_agent_async()
• Agent$cost()
• Agent$delegation_graph_usage()
• Agent$export_subagents()
• Agent$get_context_turns()
• Agent$get_cost()
• Agent$get_model()
• Agent$get_model_object()
• Agent$get_permission_mode()
• Agent$get_provider()
• Agent$get_subagent_contexts()
• Agent$get_subagent_messages()
• Agent$get_subagent_results()
• Agent$get_system_prompt()
• Agent$get_tokens()
• Agent$get_tools()
• Agent$get_turns()
• Agent$inspect_subagents()
• Agent$interrupt_subagent()
• Agent$last_compaction()
• Agent$last_run()
• Agent$last_turn()
• Agent$list_checkpoints()
• Agent$list_subagents()
• Agent$load_mcp()
• Agent$load_session()
• Agent$load_skill()
• Agent$mcp_status()
• Agent$mcp_tools()
• Agent$microcompact()
• Agent$observe_subagents()
• Agent$on_tool_request()
• Agent$on_tool_result()
• Agent$pending_approval()
• Agent$provider()
• Agent$read_subagent_result()
• Agent$register_tool()
• Agent$register_tools()
• Agent$release_agent()
• Agent$release_agent_graph()
• Agent$resolve_tool_result()
• Agent$resume_approval()
• Agent$retain_agent()
• Agent$retain_agent_graph()
• Agent$rewind_files()
• Agent$run()
• Agent$run_async()
• Agent$run_sync()
• Agent$save_session()
• Agent$session_id()
• Agent$set_chat()
• Agent$set_context_policy()
• 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(),
  delegation_sources = list(),
  delegation_scope = list(),
  delegation_max_bytes = 65536L,
  delegation_policy = DelegationPolicy(),
  delegation_disclosure = DelegationDisclosure(),
  delegation_observation = DelegationObservation(),
  approval_dir = NULL,
  trusted_results = NULL
)

Arguments

chat

An ellmer Chat for the lead.

sub_agents

A list of agent_definition() objects.

tools

Tools for the lead, in addition to delegate_to_agent.

system_prompt

System prompt for the lead; a list of the subagents is appended.

permissions

Permissions for the lead and, by default, its subagents. A definition can only narrow them.

usage_limits

UsageLimits for each lead run, shared with the subagents it starts.

context_policy

A ContextPolicy for compaction and large tool results, used by the lead and its subagents.

enable_file_checkpointing

Whether to checkpoint files before Deputy's file tools change them, so changes can be rewound. The lead and its subagents share the checkpoints.

file_checkpoint_max_file_bytes

Maximum size, in bytes, of one file saved in a checkpoint. Defaults to 50 MiB.

file_checkpoint_max_journal_bytes

Maximum total size, in bytes, of all checkpoint data. Defaults to 250 MiB.

working_dir

Working directory, shared with subagents.

session_id

Optional session ID, generated by default.

run_context

Named list of JSON-compatible values, such as a user ID, attached to every run of the lead and its subagents.

agent_id

Optional ID for the lead, generated by default.

agent_name

Optional display name for the lead.

fallback_chats

Chats to switch to, in order, if the lead's provider fails; see Agent. Subagents have no fallbacks; those that inherit the lead's model use its current chat.

delegation_sources

Text sources that tasks can cite as evidence (see DelegationInput): an unnamed list of up to 128 records, 16 MiB in total, each with source_id, revision, owner_id, conversation_id and text, and optionally allowed_agents, the definitions that may receive it (NULL for all). Each source_id may have one revision per owner and conversation. Deputy checks the scope and revision, not whether the user may see a source, so include only sources they may see.

delegation_scope

A list with owner_id and conversation_id, required with delegation_sources. Only sources with the same owner and conversation can be used, and the model can't change it. It is also passed to the DelegationDisclosure authorize function.

delegation_max_bytes

Size limit, in bytes, checked separately for a delegation's task, evidence, starting prompt and message, and DelegationManifest. Defaults to 64 KiB. A delegation over this limit, or whose estimated tokens exceed the ContextPolicy max_tokens, fails before any model request.

delegation_policy

A DelegationPolicy for subagent tools, hooks and user questions.

delegation_disclosure

A DelegationDisclosure that decides who may inspect subagents and their history. The default denies everyone.

delegation_observation

A DelegationObservation setting the size of the event buffer read by $observe_subagents().

approval_dir

Optional directory for durable tool approvals; see Agent. A lead with approval_dir set can't delegate.

trusted_results

Optional TrustedResults policy that also covers every subagent and its tools. A designated tool may belong to the lead or a subagent, but must be the same tool everywhere. Subagents' trusted results are recorded in the lead's run and passed to its on_result.

Returns

A new LeadAgent object

---

LeadAgent$set_delegation_sources()

Replace the sources a subagent can be given as evidence, for example when a drawing is revised or a document is added during a conversation. The new list replaces the old one completely. Each delegation uses the sources as they were when it started, so a delegation already running is not affected.

Usage

LeadAgent$set_delegation_sources(
  sources = list(),
  scope = NULL,
  clear_records = FALSE
)

Arguments

sources

Unnamed list of source records, as for new()'s delegation_sources.

scope

A new delegation_scope (owner_id and conversation_id), or NULL to keep the current one. The scope can change only when no run or delegation is in progress and no retained agent is held. Earlier subagent records and activity belong to the old conversation, so the change is refused while they exist unless clear_records = TRUE.

clear_records

If TRUE, discard earlier subagent records and activity when the scope changes, instead of refusing the change. Use it when moving the lead to another conversation. Subscriptions from $observe_subagents() made before the change stop working.

Returns

The lead, invisibly.

---

LeadAgent$register_sub_agent()

Add a subagent definition, or replace one with the same name, for example to give a subagent a different set of tools. Delegations that are already running keep the definition they started with.

Usage

LeadAgent$register_sub_agent(definition, replace = FALSE)

Arguments

definition

An agent_definition() object

replace

If TRUE, replace a registered definition with the same name. If FALSE (the default), a name clash is an error.

Returns

The lead, invisibly.

---

LeadAgent$available_sub_agents()

List the names of the registered subagent definitions.

Usage

LeadAgent$available_sub_agents()

Returns

A character vector.

---

LeadAgent$parallel_delegate()

Ask several subagents for one reply each, in parallel.

Each named definition gets a fresh conversation, no tools and at most one model request, so definitions with tools, skills or mcp_servers are rejected. The lead's conversation is not changed.

Usage

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

Arguments

tasks

A named character vector, or a named list of strings and DelegationInput objects. Each name selects a different registered definition.

max_active

Maximum number of subagents running at once.

mode

Only "stateless" is supported.

usage_limits

Optional UsageLimits for the whole batch; unset fields use the lead's. Token and cost limits are split between the subagents running at once and checked after each reply, so the batch can overshoot by one reply per running subagent.

run_context

Named list added to the lead's run_context for this batch.

Returns

A list with mode, results (AgentResult objects, NULL where none was returned), outcomes (DelegationOutcome objects), errors, status, and run, an AgentResult for the whole batch that $last_run() also returns. Entries follow the order of tasks, including failed and unstarted ones; a failure doesn't discard the other results.

---

LeadAgent$parallel_delegate_async()

Version of $parallel_delegate() that doesn't block R.

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 that resolves to the same list as $parallel_delegate(). Calling $interrupt() cancels tasks that haven't started and asks running subagents to stop.

---

LeadAgent$interrupt()

Ask the lead and its running subagents to stop.

Usage

LeadAgent$interrupt(reason = "interrupted")

Arguments

reason

Reason recorded on the stopped runs.

Returns

Invisibly, whether the lead or a subagent was running.

---

LeadAgent$print()

Print the lead and the names of its subagent definitions.

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.