Agents

This page presents all APIs and classes related to WayFlow agents.

Visit the Agent Spec API Documentation to learn more about Agent Components.

Agent Spec - Agents API Reference

Tip

Click the button above ↑ to visit the Agent Spec Documentation

Agent related classes

Agent class

class wayflowcore.agent.Agent(llm: 'LlmModel', tools: Optional[Sequence[Union[wayflowcore.tools.tools.Tool, wayflowcore.tools.toolbox.ToolBox]]] = None, flows: Optional[List[ForwardRef('Flow')]] = None, agents: Optional[List[Union[ForwardRef('Agent'), ForwardRef('OciAgent')]]] = None, custom_instruction: Optional[str] = None, agent_id: Optional[str] = None, id: Optional[str] = None, max_iterations: int = 10, context_providers: Optional[List[ForwardRef('ContextProvider')]] = None, can_finish_conversation: bool = False, initial_message: Optional[str] = 'N/A', caller_input_mode: wayflowcore.agent.CallerInputMode = <CallerInputMode.ALWAYS: 'always'>, input_descriptors: Optional[List[ForwardRef('Property')]] = None, output_descriptors: Optional[List[ForwardRef('Property')]] = None, name: Optional[str] = None, description: str = '', agent_template: Optional[wayflowcore.templates.template.PromptTemplate] = None, _add_talk_to_user_tool: bool = True, __metadata_info__: Optional[Dict[str, Any]] = None, _filter_messages_by_recipient: bool = True)

Agent that can handle a conversation with a user, interact with external tools and follow interaction flows.

Note

An Agent has input and output descriptors, describing what values the agent requires to run and what values it produces.

Input descriptors

By default, when input_descriptors is set to None, the input_descriptors will be automatically inferred from the custom_instruction template of the Agent, with one input descriptor per variable in the template, trying to detect the type of the variable based on how it is used in the template. See TemplateRenderingStep for concrete examples on how descriptors are extracted from text prompts.

If you provide a list of input descriptors, each provided descriptor will automatically override the detected one, in particular using the new type instead of the detected one. If some of them are missing, the Agent’s execution is not guaranteed to succeed.

If you provide input descriptors for non-autodetected variables, a warning will be emitted, and they won’t be used during the execution of the step.

Output descriptors

By default, when output_descriptors is set to None, the Agent won’t have any output descriptors, which means that it can only ask question to the user by yielding.

If you provide a list of output descriptors, the Agent will be prompted to gather and output values that will match the expected output descriptors, which means it can either yield to the user or finish the conversation by outputting the output values. If the Agent is not able to generate them, the values will be filled with their default values if they are specified, or the default values of their respective types, after the maximum amount of iterations of the Agent is reached.

Parameters:

• llm (wayflowcore.models.llmmodel.LlmModel) – Model to use for the agent executor (which chooses the next action to do).

• tools (Sequence[wayflowcore.tools.tools.Tool | wayflowcore.tools.toolbox.ToolBox]) – List of tools available for the agent.

• flows (List[Flow]) – List of flows available for the agent.

• agents (List[Agent | OciAgent]) –

  Other agents that the agent can call (expert agents).

  Warning

  The use of expert agents is currently in beta and may undergo significant changes. The API and behaviour are not guaranteed to be stable and may change in future versions.

• custom_instruction (str | None) – Custom instruction for the agent that will be passed in the system prompt. You need to include the context and what the agent is supposed to help the user with. This can contain variables in the jinja syntax, and their context providers need to be passed in the context_providers parameter.

• max_iterations (int) – Maximum number of calls to the agent executor before yielding back to the user.

• context_providers (List[ContextProvider]) – Context providers for jinja variables in the custom_instruction.

• can_finish_conversation (bool) – Whether the agent can decide to end the conversation or not.

• initial_message (str | None) – Initial message the agent will post if no previous user message. It must be None for CallerInputMode.NEVER If None for CallerInputMode.ALWAYS, the LLM will generate it given the custom_instruction. Default to Agent.DEFAULT_INITIAL_MESSAGE for CallerInputMode.ALWAYS and None for CallerInputMode.NEVER.

• caller_input_mode (wayflowcore.agent.CallerInputMode) – whether the agent is allowed to ask the user questions (CallerInputMode.ALWAYS) or not (CallerInputMode.NEVER). If set to NEVER, the agent won’t be able to yield.

• input_descriptors (List[wayflowcore.property.Property]) –

  Input descriptors of the agent. None means the agent will resolve the input descriptors automatically in a best effort manner.

  Note

  In some cases, the static configuration might not be enough to infer them properly, so this argument allows to override them.

  If input_descriptors are specified, they will override the resolved descriptors but will be matched by name against them to check that types can be casted from one another, raising an error if they can’t. If some expected descriptors are missing from the input_descriptors (i.e. you forgot to specify one), a warning will be raised and the agent is not guaranteed to work properly.

• output_descriptors (List[wayflowcore.property.Property]) –

  Outputs that the agent is expected to generate.

  Warning

  If not None, it will change the agent’s behavior and the agent will be prompted to output values for all outputs. The Agent will be able to submit values when it sees fit to finish the conversation. The outputs are mandatory if no default value is provided (the agent will have to submit a value for it to finish the conversation, and will be re-prompted to do so if it does not provide a value for it) but optional if a default value is passed (it will use the default value if the LLM doesn’t generate a value for it.

• name (str) – name of the agent, used for composition

• description (str | None) – description of the agent, used for composition

• id (str) – ID of the agent

• agent_template (wayflowcore.templates.template.PromptTemplate) – Specific agent template for more advanced prompting techniques. It will be overloaded with the current agent tools, and can have placeholders: * custom_instruction placeholder for the custom_instruction parameter.

• agent_id (str | None) –

• _add_talk_to_user_tool (bool) –

• __metadata_info__ (Dict[str, Any] | None) –

• _filter_messages_by_recipient (bool) –

Examples

>>> from wayflowcore.agent import Agent
>>> agent = Agent(llm=llm)
>>> conversation = agent.start_conversation()
>>> conversation.append_user_message("I need help regarding my sql query")
>>> status = conversation.execute()
>>> agent_answer = conversation.get_last_message().content
>>> # I'd be happy to help with your SQL query

DEFAULT_INITIAL_MESSAGE: ClassVar[str] = 'Hi! How can I help you?'

Message the agent will post if no previous user message to welcome them.

Type:

str

NOT_SET_INITIAL_MESSAGE: ClassVar[str] = 'N/A'

Placeholder for non-explicitly set initial message.

Type:

str

property agent_id: str

agent_template: PromptTemplate

agents: List[Agent | OciAgent]

Sub-agents the agent has access to

caller_input_mode: CallerInputMode

Whether the agent can ask the user for additional information or needs to just deal with the task itself

can_finish_conversation: bool

Whether the agent can just exist the conversation when thinks it is done helping the user

clone(name, description)

Clones an agent with a different name and description

Parameters:

• name (str) –

• description (str) –

Return type:

Agent

static compute_agent_inputs(custom_instruction, context_providers, user_specified_input_descriptors, agent_template)

Parameters:

• custom_instruction (str | None) –

• context_providers (List[ContextProvider]) –

• user_specified_input_descriptors (List[Property]) –

• agent_template (PromptTemplate) –

Return type:

Tuple[List[Property], List[str]]

property config: Agent

context_providers: List[ContextProvider]

Context providers for variables present in the custom instructions of the agent

custom_instruction: str | None

Additional instructions to put in the agent system prompt

description: str | None

property executor: ConversationExecutor

flows: List[Flow]

Flows the agent has access to

id: str

Id of the agent, needed to deal with message visibility

initial_message: str | None

Initial hardcoded message the agent might post if it doesn’t have any user message in the conversation

input_descriptors: List[Property]

Input descriptors of the agent. Can be updated based on other agent attributes

llm: LlmModel

LLM used for the react agent

property llms: List[LlmModel]

max_iterations: int

Maximum number of iterations the agent can loop before returning to the user

property might_yield: bool

name: str

output_descriptors: List[Property]

Output descriptors of the agent

start_conversation(inputs=None, messages=None, conversation_id=None)

Initializes a conversation with the agent.

Parameters:

• inputs (Dict[str, Any] | None) – This argument is not used. It is included for compatibility with the Flow class.

• messages (MessageList | List[Message] | None) – Message list to which the agent will participate

• conversation_id (str | None) – Conversation id of the parent conversation.

Returns:

The conversation object of the agent.

Return type:

conversation

tools: Sequence[Tool | ToolBox]

Tools the agent has access to

OCI Agent class

class wayflowcore.ociagent.OciAgent(agent_endpoint_id, client_config, initial_message='Hi! How can I help you?', name=None, description='', agent_id=None, id=None, __metadata_info__=None)

An agent is a component that can do several rounds of conversation to solve a task.

The agent is defined on the OCI console and this is only a wrapper to connect to it. It can be executed by itself, or be executed in a flow using an AgentNode, or used as a sub-agent of another WayFlow Agent.

Warning

OciAgent is currently in beta and may undergo significant changes. The API and behaviour are not guaranteed to be stable and may change in future versions.

Connects to a remote OciAgent. The remote agent needs to be first created on the OCI console, this class only connects to existing remote agents.

Parameters:

• agent_endpoint_id (str) – A unique ID for the endpoint.

• client_config (wayflowcore.models.ociclientconfig.OCIClientConfig) – oci client config to authenticate the OCI service

• initial_message (str) – Initial message the agent will post if no previous user message. Default to OciGenAIAgent.DEFAULT_INITIAL_MESSAGE.

• name (str) – Name of the OCI agent.

• description (str) – Description of the OCI agent. Is needed when the agent is used as the sub-agent of another agent.

• agent_id (str | None) – Unique ID to define the agent

• id (str) –

• __metadata_info__ (Dict[str, Any]) –

DEFAULT_INITIAL_MESSAGE: ClassVar[str] = 'Hi! How can I help you?'

Message the agent will post if no previous user message to welcome them.

Type:

str

agent_endpoint_id: str

property agent_id: str

client_config: OCIClientConfig

description: str

id: str

initial_message: str

name: str

start_conversation(inputs=None, messages=None)

Initializes a conversation with the agent.

Parameters:

• inputs (Dict[str, Any] | None) – This argument is not used. It is included for compatibility with the Flow class.

• messages (MessageList | List[Message] | None) – Message list to which the agent will participate

Returns:

The conversation object of the agent.

Return type:

conversation

DescribedFlow

class wayflowcore.tools.DescribedFlow(flow, name, description, output=None)

DescribedFlow are used to store additional information about Flow to enable flow as tool support in the AgentExecutionStep.

The name and description of the flow should represent the purpose of the flow when used as a tool.

Parameters:

• flow (Flow) – Flow object.

• name (str) – Name of the flow.

• description (str) – Description of the purpose of the flow when used as a tool.

• output (str | None) – Description of the output of the flow.

description: str

flow: Flow

static from_config(config, deserialization_context=None)

Creates a DescribedFlow object from a configuration dictionary.

Parameters:

• config (Dict[str, Any]) – Dictionary representing the configuration of the described flow.

• serialization_context – Serialization context for the object.

• deserialization_context (DeserializationContext | None) –

Return type:

A DescribedFlow object created from the configuration.

name: str

output: str | None = None

to_config(serialization_context=None)

Converts the described flow to a configuration dictionary.

Parameters:

serialization_context (SerializationContext | None) – Serialization context for the object.

Returns:

A dictionary representing the configuration of the described flow.

Return type:

config

DescribedAgent

class wayflowcore.tools.DescribedAgent(agent, name, description)

DescribedAgent are used to store additional information about agents to enable their use as tool support in the AgentExecutionStep.

The name and description of the agent should represent the purpose of the agent when used as a tool.

Parameters:

• agent (Agent) – Agent object.

• name (str) – Name of the agent.

• description (str) – Description of the purpose of the agent when used as a tool.

agent: Agent

description: str

static from_config(config, deserialization_context)

Creates a DescribedAgent object from a configuration dictionary.

Parameters:

• config (Dict[str, Any]) – Dictionary representing the configuration of the described agent.

• deserialization_context (DeserializationContext | None) – Deserialization context for the object.

Returns:

A DescribedAgent object created from the configuration.

Return type:

described_agent

name: str

to_config(serialization_context)

Converts the described agent to a configuration dictionary.

Parameters:

serialization_context (SerializationContext | None) – Serialization context for the object.

Returns:

A dictionary representing the configuration of the described agent.

Return type:

config

Swarm class

class wayflowcore.swarm.Swarm(first_agent: wayflowcore.agent.Agent, relationships: List[Tuple[wayflowcore.agent.Agent, wayflowcore.agent.Agent]], handoff: bool = True, swarm_template: wayflowcore.templates.template.PromptTemplate | None = None, input_descriptors: Optional[List[ForwardRef('Property')]] = None, output_descriptors: Optional[List[ForwardRef('Property')]] = None, name: str | None = None, description: str | None = None, __metadata_info__: Dict[str, Any] | None = None, id: str | None = None)

Defines a Swarm conversational component.

A Swarm is a multi-agent conversational component in which each agent determines the next agent to be executed, based on a list of pre-defined relationships.

Parameters:

• first_agent (wayflowcore.agent.Agent) – The first Agent to interact with the human user.

• relationships (List[Tuple[wayflowcore.agent.Agent, wayflowcore.agent.Agent]]) –

  Determine the list of allowed interactions in the Swarm. Each element in the list is a tuple (caller_agent, recipient_agent) specifying that the caller_agent can query the recipient_agent.

  Currently, calling agents can perform two actions: * Send a message to a recipient agent (e.g. asking to complete a sub task). The recipient agent then answers back the caller once done. * Transfer the entire conversation with the user to another agent (also known as handoff, see handoff)

• handoff (bool) –

  • When False, agent can only talk to each other, the first_agent is fixed for the entire conversation;

  • When True, agents can handoff the conversation to each other, i.e. transferring the list of messages between an agent and the user to another agent in the Swarm. They can also talk to each other as when handoff=False

  Note

  A key benefit of using Handoff is the reduced response latency: While talking to other agents increases the “distance” between the human user and the current agent, transferring a conversation to another agent keeps this distance unchanged (i.e. the agent interacting with the user is different but the user is still the same).

• input_descriptors (List[wayflowcore.property.Property]) –

  Input descriptors of the swarm. None means the swarm will resolve the input descriptors automatically in a best effort manner.

  Note

  In some cases, the static configuration might not be enough to infer them properly, so this argument allows to override them.

  If input_descriptors are specified, they will override the resolved descriptors but will be matched by name against them to check that types can be casted from one another, raising an error if they can’t. If some expected descriptors are missing from the input_descriptors (i.e. you forgot to specify one), a warning will be raised and the swarm is not guaranteed to work properly.

• output_descriptors (List[wayflowcore.property.Property]) –

  Output descriptors of the swarm. None means the swarm will resolve them automatically in a best effort manner.

  Warning

  Setting output descriptors for the Swarm is currently not supported.

• name (str) – name of the swarm, used for composition

• description (str | None) – description of the swarm, used for composition

• id (str) – ID of the Swarm

• swarm_template (PromptTemplate) –

• __metadata_info__ (Dict[str, Any] | None) –

Example

>>> from wayflowcore.agent import Agent
>>> from wayflowcore.swarm import Swarm
>>> addition_agent = Agent(name="addition_agent", description="Agent that can do additions", llm=llm, custom_instruction="You can do additions.")
>>> multiplication_agent = Agent(name="multiplication_agent", description="Agent that can do multiplication", llm=llm, custom_instruction="You can do multiplication.")
>>> division_agent = Agent(name="division_agent", description="Agent that can do division", llm=llm, custom_instruction="You can do division.")
>>>
>>> swarm = Swarm(
...     first_agent=addition_agent,
...     relationships=[
...         (addition_agent, multiplication_agent),
...         (addition_agent, division_agent),
...         (multiplication_agent, division_agent),
...     ]
... )
>>> conversation = swarm.start_conversation()
>>> conversation.append_user_message("Please compute 2*2+1")
>>> status = conversation.execute()
>>> swarm_answer = conversation.get_last_message().content
>>> # The answer to 2*2+1 is 5.

description: str | None

first_agent: Agent

handoff: bool

id: str

input_descriptors: List[Property]

name: str

output_descriptors: List[Property]

relationships: List[Tuple[Agent, Agent]]

start_conversation(inputs=None, messages=None, conversation_id=None, conversation_name=None)

Parameters:

• inputs (Dict[str, Any] | None) –

• messages (MessageList | List[Message] | None) –

• conversation_id (str | None) –

• conversation_name (str | None) –

Return type:

Conversation

swarm_template: PromptTemplate

ManagerWorkers class

class wayflowcore.managerworkers.ManagerWorkers(group_manager: wayflowcore.models.llmmodel.LlmModel | wayflowcore.agent.Agent, workers: List[wayflowcore.agent.Agent], managerworkers_template: Optional[ForwardRef('PromptTemplate')] = None, input_descriptors: Optional[List[ForwardRef('Property')]] = None, output_descriptors: Optional[List[ForwardRef('Property')]] = None, name: str | None = None, description: str = '', __metadata_info__: Dict[str, Any] | None = None, id: str | None = None)

Defines a ManagerWorkers conversational component.

A ManagerWorkers is a multi-agent conversational component in which a group manager agent assigns tasks to worker agents.

Paramters

workers:

List of Agents that participate in the group. There should be at least one agent in the list.

group_manager:

Can either be an LLM or an agent that manages the group. If an LLM is passed, a manager agent will be created using that LLM.

input_descriptors:

Input descriptors of the ManagerWorkers. None means the ManagerWorks will resolve the input descriptors automatically in a best effort manner.

Note

In some cases, the static configuration might not be enough to infer them properly, so this argument allows to override them.

If input_descriptors are specified, they will override the resolved descriptors but will be matched by name against them to check that types can be casted from one another, raising an error if they can’t. If some expected descriptors are missing from the input_descriptors (i.e. you forgot to specify one), a warning will be raised and the ManagerWorkers is not guaranteed to work properly.

output_descriptors:

Output descriptors of the ManagerWorkers. None means the ManagerWorkers will resolve them automatically in a best effort manner. .. warning:

Setting output descriptors for the Swarm is currently not supported.

name:

name of the ManagerWorkers, used for composition

description:

description of the ManagerWorkers, used for composition

Example

>>> from wayflowcore.agent import Agent
>>> from wayflowcore.managerworkers import ManagerWorkers
>>> addition_agent = Agent(name="addition_agent", description="Agent that can do additions", llm=llm, custom_instruction="You can do additions.")
>>> multiplication_agent = Agent(name="multiplication_agent", description="Agent that can do multiplication", llm=llm, custom_instruction="You can do multiplication.")
>>> division_agent = Agent(name="division_agent", description="Agent that can do division", llm=llm, custom_instruction="You can do division.")
>>>
>>> group = ManagerWorkers(
...     workers=[addition_agent, multiplication_agent, division_agent],
...     group_manager=llm,
... )
>>> conversation = group.start_conversation()
>>> conversation.append_user_message("Please compute 2*2 + 1")
>>> status = conversation.execute()
>>> answer = conversation.get_last_message().content
>>> # The answer to 2*2 + 1 is 5.

description: str | None

group_manager: LlmModel | Agent

id: str

input_descriptors: List[Property]

managerworkers_template: PromptTemplate

name: str

output_descriptors: List[Property]

start_conversation(inputs=None, messages=None, conversation_id=None, conversation_name=None)

Initializes a conversation with the managerworkers.

Parameters:

• inputs (Dict[str, Any] | None) – Dictionary of inputs. Keys are the variable identifiers and values are the actual inputs to start the main conversation.

• messages (MessageList | List[Message] | None) – Message list of the manager agent and the end-user.

• conversation_id (str | None) – Conversation id of the main conversation.

• conversation_name (str | None) –

Returns:

The conversation object of the managerworkers.

Return type:

conversation

workers: List[Agent]

Parameters:

• group_manager (LlmModel | Agent) –

• workers (List[Agent]) –

• managerworkers_template (PromptTemplate) –

• input_descriptors (List[Property]) –

• output_descriptors (List[Property]) –

• name (str) –

• description (str | None) –

• __metadata_info__ (Dict[str, Any] | None) –

• id (str) –