aidputils.agents.toolkit.supervisor

aidputils.agents.toolkit.supervisor.OutputMode

Mode for adding agent outputs to the message history in the multi-agent workflow

  • full_history: add the entire agent message history

  • last_message: add only the last message

alias of Literal[‘full_history’, ‘last_message’]

async aidputils.agents.toolkit.supervisor.read_async_dict_from_stream(stream: AsyncIterator[dict[str, Any] | Any]) → dict[str, Any][source]

Reads all chunks from an async stream and aggregates them into a single dictionary.

This assumes that each chunk can be safely merged into the final dictionary using dict.update().

aidputils.agents.toolkit.supervisor.read_dict_from_stream(stream: Iterator[dict[str, Any] | Any]) → dict[str, Any][source]

Reads all chunks from an async stream and aggregates them into a single dictionary.

This assumes that each chunk can be safely merged into the final dictionary using dict.update().

aidputils.agents.toolkit.supervisor.create_supervisor(agents: list[Pregel], *, model: BaseChatModel, tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None, system_prompt: str | SystemMessage | None = None, middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (), response_format: ResponseFormat[ResponseT] | type[ResponseT] | None = None, state_schema: Type[AgentState] | None = None, context_schema: Type[Any] | None = None, supervisor_name: str = 'supervisor', output_mode: OutputMode = 'last_message', add_handoff_messages: bool = True, handoff_tool_prefix: str | None = None, include_agent_name: AgentNameMode | None = None, add_handoff_back_messages: bool | None = None) → StateGraph[source]

Create a multi-agent supervisor workflow.

The generated graph places a supervisor agent in front of a set of worker agents. The supervisor decides when to answer directly, when to call tools, and when to hand work off to one of the managed agents.

Parameters:

  • agents – List of agents to manage. An agent can be a LangGraph [CompiledStateGraph](https://reference.langchain.com/python/langgraph/graphs/#langgraph.graph.state.CompiledStateGraph), a functional API workflow, or any other [Pregel](https://reference.langchain.com/python/langgraph/pregel/#langgraph.pregel.Pregel) object.

  • model – Language model to use for the supervisor

  • tools – Tools to use for the supervisor

  • system_prompt –

    Optional prompt to use for the supervisor. Can be one of:

    • str: This is converted to a SystemMessage and added to the beginning of the list of messages in state[“messages”].

    • SystemMessage: this is added to the beginning of the list of messages in state[“messages”].

    • Callable: This function should take in full graph state and the output is then passed to the language model.

    • Runnable: This runnable should take in full graph state and the output is then passed to the language model.

  • response_format –

    An optional schema for the final supervisor output.

    If provided, output will be formatted to match the given schema and returned in the ‘structured_response’ state key.

    If not provided, structured_response will not be present in the output state.

    Can be passed in as:

    • An OpenAI function/tool schema,

    • A JSON Schema,

    • A TypedDict class,

    • A Pydantic class.

    • A tuple (prompt, schema), where schema is one of the above.

      The prompt will be used together with the model that is being used to generate the structured response.

    !!! Important

    response_format requires the model to support .with_structured_output

    !!! Note

    response_format requires structured_response key in your state schema. You can use the prebuilt langgraph.prebuilt.chat_agent_executor.AgentStateWithStructuredResponse.

  • middleware –

    A sequence of middleware instances to apply to the agent.

    Middleware can intercept and modify agent behavior at various stages.

    !!! tip “”

    See the [Middleware](https://docs.langchain.com/oss/python/langchain/middleware) docs for more information.

  • parallel_tool_calls –

    Whether to allow the supervisor LLM to call tools in parallel (only OpenAI and Anthropic). Use this to control whether the supervisor can hand off to multiple agents at once.

    If True, will enable parallel tool calls.

    If False, will disable parallel tool calls.

    !!! Important

    This is currently supported only by OpenAI and Anthropic models. To control parallel tool calling for other providers, add explicit instructions for tool use to the system prompt.

  • state_schema – State schema to use for the supervisor graph.

  • context_schema – Specifies the schema for the context object that will be passed to the workflow.

  • output_mode –

    Mode for adding managed agents’ outputs to the message history in the multi-agent workflow. Can be one of:

    • full_history: Add the entire agent message history

    • last_message: Add only the last message

  • add_handoff_messages – Whether to add a pair of (AIMessage, ToolMessage) to the message history when a handoff occurs.

  • handoff_tool_prefix –

    Optional prefix for the handoff tools (e.g., ‘delegate_to_’ or ‘transfer_to_’)

    If provided, the handoff tools will be named handoff_tool_prefix_agent_name.

    If not provided, the handoff tools will be named transfer_to_agent_name.

  • add_handoff_back_messages – Whether to add a pair of (AIMessage, ToolMessage) to the message history when returning control to the supervisor to indicate that a handoff has occurred.

  • supervisor_name – Name of the supervisor node.

  • include_agent_name –

    Use to specify how to expose the agent name to the underlying supervisor LLM.

    • None: Relies on the LLM provider using the name attribute on the AI message. Currently, only OpenAI supports this.

    • ’inline’: Add the agent name directly into the content field of the AI message using XML-style tags.

      Example: “How can I help you” -> “<name>agent_name</name><content>How can I help you?</content>”

Example

```python from langchain_openai import ChatOpenAI

from langgraph_supervisor import create_supervisor from langgraph.prebuilt import create_react_agent

# Create specialized agents

def add(a: float, b: float) -> float:

‘’’Add two numbers.’’’ return a + b

def web_search(query: str) -> str:

‘’’Search the web for information.’’’ return ‘Here are the headcounts for each of the FAANG companies in 2024…’

math_agent = create_react_agent(

model=”openai:gpt-4o”, tools=[add], name=”math_expert”,

)

research_agent = create_react_agent(

model=”openai:gpt-4o”, tools=[web_search], name=”research_expert”,

)

# Create supervisor workflow workflow = create_supervisor(

[research_agent, math_agent], model=ChatOpenAI(model=”gpt-4o”),

)

# Compile and run app = workflow.compile() result = app.invoke({

“messages”: [
{

“role”: “user”, “content”: “what’s the combined headcount of the FAANG companies in 2024?”

}

]

})