Learn R Programming

mini007 (version 0.2.2)

LeadAgent: LeadAgent: A Multi-Agent Orchestration Coordinator

Description

`LeadAgent` extends `Agent` to coordinate a group of specialized agents. It decomposes complex prompts into subtasks using LLMs and assigns each subtask to the most suitable registered agent. The lead agent handles response chaining, where each agent can consider prior results.

Arguments

Super class

mini007::Agent -> LeadAgent

Public fields

agents

A named list of registered sub-agents (by UUID).

agents_interaction

A list of delegated task history with agent IDs, prompts, and responses.

plan

A list containing the most recently generated task plan.

hitl_steps

The steps where the workflow should be stopped in order to allow for a human interaction

prompt_for_plan

The prompt used to generate the plan.

agents_for_plan

The agents used for the plan

Methods

Inherited methods


Method new()

Initializes the LeadAgent with a built-in task-decomposition prompt.

Usage

LeadAgent$new(name, llm_object)

Arguments

name

A short name for the coordinator (e.g. `"lead"`).

llm_object

The LLM object generate by ellmer (eg. output of ellmer::chat_openai)

Examples


  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )


Method clear_agents()

Clear out the registered Agents

Usage

LeadAgent$clear_agents()

Examples

  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed and accurate information. ",
   "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

summarizer <- Agent$new( name = "summarizer", instruction = paste0( "You are an agent designed to summarise ", "a given text into 3 distinct bullet points." ), llm_object = openai_4_1_mini )

translator <- Agent$new( name = "translator", instruction = "Your role is to translate a text from English to German", llm_object = openai_4_1_mini ) lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(researcher, summarizer, translator))

lead_agent$agents

lead_agent$clear_agents()

lead_agent$agents


Method remove_agents()

Remove registered agents by IDs

Usage

LeadAgent$remove_agents(agent_ids)

Arguments

agent_ids

The Agent ID to remove from the registered Agents

Examples

  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed and accurate information. ",
   "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

summarizer <- Agent$new( name = "summarizer", instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.", llm_object = openai_4_1_mini )

translator <- Agent$new( name = "translator", instruction = "Your role is to translate a text from English to German", llm_object = openai_4_1_mini )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(researcher, summarizer, translator))

lead_agent$agents

# deleting the translator agent

id_translator_agent <- translator$agent_id

lead_agent$remove_agents(id_translator_agent)

lead_agent$agents


Method register_agents()

Register one or more agents for delegation.

Usage

LeadAgent$register_agents(agents)

Arguments

agents

A vector of `Agent` objects to register.

Examples

  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed and accurate information. ",
   "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

summarizer <- Agent$new( name = "summarizer", instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.", llm_object = openai_4_1_mini )

translator <- Agent$new( name = "translator", instruction = "Your role is to translate a text from English to German", llm_object = openai_4_1_mini )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(researcher, summarizer, translator))

lead_agent$agents


Method visualize_plan()

Visualizes the orchestration plan Each agent node is shown in sequence (left → right), with tooltips showing the actual prompt delegated to that agent.

Usage

LeadAgent$visualize_plan()


Method invoke()

Executes the full prompt pipeline: decomposition → delegation → invocation.

Usage

LeadAgent$invoke(prompt, force_regenerate_plan = FALSE)

Arguments

prompt

The complex user instruction to process.

force_regenerate_plan

If TRUE, regenerate a plan even if one exists, defaults to FALSE.

Returns

The final response (from the last agent in the sequence).

Examples

\dontrun{
 # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed ",
   "and accurate information. Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

summarizer <- Agent$new( name = "summarizer", instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.", llm_object = openai_4_1_mini )

translator <- Agent$new( name = "translator", instruction = "Your role is to translate a text from English to German", llm_object = openai_4_1_mini )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(researcher, summarizer, translator))

lead_agent$invoke( paste0( "Describe the economic situation in Algeria in 3 sentences. ", "Answer in German" ) ) }


Method generate_plan()

Generates a task execution plan without executing the subtasks. It returns a structured list containing the subtask, the selected agent, and metadata.

Usage

LeadAgent$generate_plan(prompt)

Arguments

prompt

A complex instruction to be broken into subtasks.

Returns

A list of lists containing agent_id, agent_name, model_name, model_provider, and the assigned prompt.

Examples

\dontrun{
 # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. Your job is to answer factual questions ",
   "with detailed and accurate information. Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

summarizer <- Agent$new( name = "summarizer", instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.", llm_object = openai_4_1_mini )

translator <- Agent$new( name = "translator", instruction = "Your role is to translate a text from English to German", llm_object = openai_4_1_mini )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(researcher, summarizer, translator))

lead_agent$generate_plan( paste0( "Describe the economic situation in Algeria in 3 sentences. ", "Answer in German" ) ) }


Method broadcast()

Broadcasts a prompt to all registered agents and collects their responses. This does not affect the main agent orchestration logic or history.

Usage

LeadAgent$broadcast(prompt)

Arguments

prompt

A user prompt to send to all agents.

Returns

A list of responses from all agents.

Examples

\dontrun{
 # An API KEY is required in order to invoke the agents
openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
openai_4_1 <- ellmer::chat(
  name = "openai/gpt-4.1",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)

openai_4_1_agent <- Agent$new( name = "openai_4_1_agent", instruction = "You are an AI assistant. Answer in 1 sentence max.", llm_object = openai_4_1 )

openai_4_1_nano <- ellmer::chat( name = "openai/gpt-4.1-nano", api_key = Sys.getenv("OPENAI_API_KEY"), echo = "none" )

openai_4_1_nano_agent <- Agent$new( name = "openai_4_1_nano_agent", instruction = "You are an AI assistant. Answer in 1 sentence max.", llm_object = openai_4_1_nano )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(openai_4_1_agent, openai_4_1_nano_agent)) lead_agent$broadcast( prompt = paste0( "If I were Algerian, which song would I like to sing ", "when running under the rain? how about a flower?" ) ) }


Method set_hitl()

Set Human In The Loop (HITL) interaction at determined steps within the workflow

Usage

LeadAgent$set_hitl(steps)

Arguments

steps

At which steps the Human In The Loop is required?

Returns

A list of responses from all agents.

Examples

\dontrun{
 # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
    "You are a research assistant. ",
    "Your job is to answer factual questions with detailed and accurate information. ",
    "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

summarizer <- Agent$new( name = "summarizer", instruction = paste0( "You are agent designed to summarise a give text ", "into 3 distinct bullet points." ), llm_object = openai_4_1_mini )

translator <- Agent$new( name = "translator", instruction = "Your role is to translate a text from English to German", llm_object = openai_4_1_mini )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(researcher, summarizer, translator))

# setting a human in the loop in step 2 lead_agent$set_hitl(1)

# The execution will stop at step 2 and a human will be able # to either accept the answer, modify it or stop the execution of # the workflow

lead_agent$invoke( paste0( "Describe the economic situation in Algeria in 3 sentences. ", "Answer in German" ) ) }


Method judge_and_choose_best_response()

The Lead Agent send a prompt to its registered agents and choose the best response from the agents' responses

Usage

LeadAgent$judge_and_choose_best_response(prompt)

Arguments

prompt

The prompt to send to the registered agents

Returns

A list of responses from all agents, including the chosen response

Examples

\dontrun{
openai_4_1_mini <- ellmer::chat(
  name = "openai/gpt-4.1-mini",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)
openai_4_1 <- ellmer::chat(
  name = "openai/gpt-4.1",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)

stylist <- Agent$new( name = "stylist", instruction = "You are an AI assistant. Answer in 1 sentence max.", llm_object = openai_4_1 )

openai_4_1_nano <- ellmer::chat( name = "openai/gpt-4.1-nano", api_key = Sys.getenv("OPENAI_API_KEY"), echo = "none" )

stylist2 <- Agent$new( name = "stylist2", instruction = "You are an AI assistant. Answer in 1 sentence max.", llm_object = openai_4_1_nano )

lead_agent <- LeadAgent$new( name = "Leader", llm_object = openai_4_1_mini )

lead_agent$register_agents(c(stylist, stylist2))

lead_agent$judge_and_choose_best_response("what's the best way to war a kalvin klein shirt?")

}


Method clone()

The objects of this class are cloneable with this method.

Usage

LeadAgent$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Details

This class builds intelligent multi-agent workflows by delegating sub-tasks using `delegate_prompt()`, executing them with `invoke()`, and storing the results in the `agents_interaction` list.

Examples

Run this code

## ------------------------------------------------
## Method `LeadAgent$new`
## ------------------------------------------------


  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )

 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )



## ------------------------------------------------
## Method `LeadAgent$clear_agents`
## ------------------------------------------------

  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed and accurate information. ",
   "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

 summarizer <- Agent$new(
   name = "summarizer",
   instruction = paste0(
   "You are an agent designed to summarise ",
   "a given text into 3 distinct bullet points."
   ),
   llm_object = openai_4_1_mini
 )

 translator <- Agent$new(
   name = "translator",
   instruction = "Your role is to translate a text from English to German",
   llm_object = openai_4_1_mini
 )
 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

 lead_agent$register_agents(c(researcher, summarizer, translator))

 lead_agent$agents

 lead_agent$clear_agents()

 lead_agent$agents


## ------------------------------------------------
## Method `LeadAgent$remove_agents`
## ------------------------------------------------

  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed and accurate information. ",
   "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

 summarizer <- Agent$new(
   name = "summarizer",
   instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.",
   llm_object = openai_4_1_mini
 )

 translator <- Agent$new(
   name = "translator",
   instruction = "Your role is to translate a text from English to German",
   llm_object = openai_4_1_mini
 )


 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

 lead_agent$register_agents(c(researcher, summarizer, translator))

 lead_agent$agents

 # deleting the translator agent

 id_translator_agent <- translator$agent_id

 lead_agent$remove_agents(id_translator_agent)

 lead_agent$agents


## ------------------------------------------------
## Method `LeadAgent$register_agents`
## ------------------------------------------------

  # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed and accurate information. ",
   "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

 summarizer <- Agent$new(
   name = "summarizer",
   instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.",
   llm_object = openai_4_1_mini
 )

 translator <- Agent$new(
   name = "translator",
   instruction = "Your role is to translate a text from English to German",
   llm_object = openai_4_1_mini
 )

 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

 lead_agent$register_agents(c(researcher, summarizer, translator))

 lead_agent$agents

## ------------------------------------------------
## Method `LeadAgent$invoke`
## ------------------------------------------------

if (FALSE) {
 # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. ",
   "Your job is to answer factual questions with detailed ",
   "and accurate information. Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

 summarizer <- Agent$new(
   name = "summarizer",
   instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.",
   llm_object = openai_4_1_mini
 )

 translator <- Agent$new(
   name = "translator",
   instruction = "Your role is to translate a text from English to German",
   llm_object = openai_4_1_mini
 )

 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

 lead_agent$register_agents(c(researcher, summarizer, translator))

 lead_agent$invoke(
 paste0(
  "Describe the economic situation in Algeria in 3 sentences. ",
  "Answer in German"
  )
 )
}

## ------------------------------------------------
## Method `LeadAgent$generate_plan`
## ------------------------------------------------

if (FALSE) {
 # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
   "You are a research assistant. Your job is to answer factual questions ",
   "with detailed and accurate information. Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

 summarizer <- Agent$new(
   name = "summarizer",
   instruction = "You are agent designed to summarise a given text into 3 distinct bullet points.",
   llm_object = openai_4_1_mini
 )

 translator <- Agent$new(
   name = "translator",
   instruction = "Your role is to translate a text from English to German",
   llm_object = openai_4_1_mini
 )

 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

 lead_agent$register_agents(c(researcher, summarizer, translator))

 lead_agent$generate_plan(
 paste0(
  "Describe the economic situation in Algeria in 3 sentences. ",
  "Answer in German"
  )
 )
}

## ------------------------------------------------
## Method `LeadAgent$broadcast`
## ------------------------------------------------

if (FALSE) {
 # An API KEY is required in order to invoke the agents
openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
openai_4_1 <- ellmer::chat(
  name = "openai/gpt-4.1",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)

openai_4_1_agent <- Agent$new(
  name = "openai_4_1_agent",
  instruction = "You are an AI assistant. Answer in 1 sentence max.",
  llm_object = openai_4_1
)

openai_4_1_nano <- ellmer::chat(
  name = "openai/gpt-4.1-nano",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)

openai_4_1_nano_agent <- Agent$new(
  name = "openai_4_1_nano_agent",
  instruction = "You are an AI assistant. Answer in 1 sentence max.",
  llm_object = openai_4_1_nano
  )

 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

lead_agent$register_agents(c(openai_4_1_agent, openai_4_1_nano_agent))
lead_agent$broadcast(
  prompt = paste0(
    "If I were Algerian, which song would I like to sing ",
    "when running under the rain? how about a flower?"
  )
  )
}

## ------------------------------------------------
## Method `LeadAgent$set_hitl`
## ------------------------------------------------

if (FALSE) {
 # An API KEY is required in order to invoke the agents
  openai_4_1_mini <- ellmer::chat(
    name = "openai/gpt-4.1-mini",
    api_key = Sys.getenv("OPENAI_API_KEY"),
    echo = "none"
  )
 researcher <- Agent$new(
   name = "researcher",
   instruction = paste0(
    "You are a research assistant. ",
    "Your job is to answer factual questions with detailed and accurate information. ",
    "Do not answer with more than 2 lines"
   ),
   llm_object = openai_4_1_mini
 )

 summarizer <- Agent$new(
   name = "summarizer",
   instruction = paste0(
   "You are agent designed to summarise a give text ",
   "into 3 distinct bullet points."
   ),
   llm_object = openai_4_1_mini
 )

 translator <- Agent$new(
   name = "translator",
   instruction = "Your role is to translate a text from English to German",
   llm_object = openai_4_1_mini
 )

 lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
 )

 lead_agent$register_agents(c(researcher, summarizer, translator))

 # setting a human in the loop in step 2
 lead_agent$set_hitl(1)

 # The execution will stop at step 2 and a human will be able
 # to either accept the answer, modify it or stop the execution of
 # the workflow

 lead_agent$invoke(
 paste0(
  "Describe the economic situation in Algeria in 3 sentences. ",
  "Answer in German"
  )
 )
}

## ------------------------------------------------
## Method `LeadAgent$judge_and_choose_best_response`
## ------------------------------------------------

if (FALSE) {
openai_4_1_mini <- ellmer::chat(
  name = "openai/gpt-4.1-mini",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)
openai_4_1 <- ellmer::chat(
  name = "openai/gpt-4.1",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)

stylist <- Agent$new(
  name = "stylist",
  instruction = "You are an AI assistant. Answer in 1 sentence max.",
  llm_object = openai_4_1
)

openai_4_1_nano <- ellmer::chat(
  name = "openai/gpt-4.1-nano",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  echo = "none"
)

stylist2 <- Agent$new(
  name = "stylist2",
  instruction = "You are an AI assistant. Answer in 1 sentence max.",
  llm_object = openai_4_1_nano
)

lead_agent <- LeadAgent$new(
  name = "Leader",
  llm_object = openai_4_1_mini
)

lead_agent$register_agents(c(stylist, stylist2))

lead_agent$judge_and_choose_best_response("what's the best way to war a kalvin klein shirt?")

}

Run the code above in your browser using DataLab