agentx-kit 0.6.0__tar.gz → 0.7.0__tar.gz

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: agentx-kit
-Version: 0.6.0
+Version: 0.7.0
 Summary: An open-source, provider-agnostic agentic framework + interactive project scaffolder for LangChain and CrewAI. Pick your LLM provider, agents, RAG, memory, MCP tools and skills — generate a ready-to-run uv project.
 Project-URL: Homepage, https://github.com/muhammadyahiya/agentx-kit
 Project-URL: Repository, https://github.com/muhammadyahiya/agentx-kit
 Project-URL: Issues, https://github.com/muhammadyahiya/agentx-kit/issues
-Author: AgentX
+Author: OptimumAI
 License: MIT
 License-File: LICENSE
 Keywords: agents,azure,bedrock,crewai,gemini,langchain,llm,mcp,openrouter,rag,scaffold,vertex

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 # PyPI distribution name (import name + CLI stay `agentx`; `agentx` was taken).
 name = "agentx-kit"
-version = "0.6.0"
+version = "0.7.0"
 description = "An open-source, provider-agnostic agentic framework + interactive project scaffolder for LangChain and CrewAI. Pick your LLM provider, agents, RAG, memory, MCP tools and skills — generate a ready-to-run uv project."
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 license = { text = "MIT" }
-authors = [{ name = "AgentX" }]
+authors = [{ name = "OptimumAI" }]
 keywords = ["agents", "llm", "langchain", "crewai", "rag", "mcp", "scaffold", "openrouter", "bedrock", "vertex", "azure", "gemini"]
 classifiers = [
     "Development Status :: 4 - Beta",

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/__init__.py

@@ -16,7 +16,7 @@ is enough to get started.
 """
 from __future__ import annotations
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 from .providers import (  # noqa: E402
     ProviderSpec,

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/cache.py

@@ -23,6 +23,8 @@ import time
 from pathlib import Path
 from typing import Any
 
+from langchain_core.caches import BaseCache
+
 _DEFAULT_PATH = ".agentx/llm_cache.sqlite"
 _lock = threading.Lock()
 
@@ -39,11 +41,12 @@ def _model_from_llm_string(llm_string: str) -> str:
     return "gpt-4o-mini"
 
 
-class AgentXCache:
+class AgentXCache(BaseCache):
     """A LangChain ``BaseCache`` backed by SQLite, with TTL + savings stats.
 
-    Implements ``lookup``/``update`` (and ``aclear``) so it can be passed to
-    ``langchain_core.globals.set_llm_cache``.
+    Implements ``lookup``/``update``/``clear``; the async ``alookup``/``aupdate``
+    paths are inherited from ``BaseCache`` (which runs the sync methods in an
+    executor), so it works under both ``invoke`` and ``ainvoke``.
     """
 
     def __init__(self, path: str | Path = _DEFAULT_PATH, ttl: int | None = None):

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/cli.py

@@ -153,6 +153,7 @@ def new(
     provider: str = typer.Option("openai", help="Provider id (with --yes)."),
     model: str = typer.Option("", help="Model id (with --yes; blank = provider default)."),
     agents: int = typer.Option(1, help="Number of agents (with --yes)."),
+    orchestration: str = typer.Option("supervisor", help="supervisor|sequential|parallel — how agents connect (with --yes, only for LangGraph with >1 agents)."),
     prompt: str = typer.Option("", "--prompt", "-p", help="System prompt for the first agent (with --yes)."),
     role: str = typer.Option("Helpful Assistant", help="Role for the first agent (with --yes)."),
     goal: str = typer.Option("Help the user accomplish their task accurately.", help="Goal for the first agent (with --yes)."),
@@ -187,7 +188,8 @@ def new(
                 agent_specs.append(AgentSpec(name=a_name))
         spec = ProjectSpec(
             name=name or "my-agent", framework=framework, provider=provider, model=model,
-            agents=agent_specs, use_rag=rag, memory=memory, use_mcp=mcp, use_skills=skills,
+            agents=agent_specs, orchestration=orchestration,
+            use_rag=rag, memory=memory, use_mcp=mcp, use_skills=skills,
             prompt_style="custom" if prompt else "default",
             observability=observability, guardrails=guardrails, serve=serve,
             docker=docker, ci=ci, evals=evals,

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/scaffold/generator.py

@@ -85,6 +85,7 @@ def _context(spec: ProjectSpec) -> dict:
         "extras": _extras(spec),
         "extras_str": ",".join(_extras(spec)),
         "multi_agent": len(spec.agents) > 1,
+        "orchestration": spec.orchestration,
     }
 
 
@@ -139,6 +140,7 @@ def _write_manifest(target: Path, spec: ProjectSpec) -> Path:
         "model": spec.model or get_spec(spec.provider).default_model,
         "python_version": ">=3.10,<3.14",
         "agents": [a.name for a in spec.agents],
+        "orchestration": spec.orchestration,
         "features": {
             "rag": spec.use_rag,
             "memory": spec.memory,
@@ -179,6 +181,21 @@ def generate_project(spec: ProjectSpec, target_dir: str | Path, overwrite: bool
         out_path.write_text(rendered, encoding="utf-8")
         written.append(out_path)
 
+    # Seed a knowledge/ directory when RAG or the MCP filesystem server needs one
+    # (the restricted MCP server points at ./knowledge and RAG indexes it).
+    if spec.use_rag or spec.use_mcp:
+        knowledge_dir = target / "knowledge"
+        knowledge_dir.mkdir(parents=True, exist_ok=True)
+        seed = knowledge_dir / "README.md"
+        if not seed.exists():
+            seed.write_text(
+                f"# {spec.slug} knowledge base\n\n"
+                "Drop `.txt` / `.md` files here. They are indexed for RAG"
+                " and exposed (read-only) to the MCP filesystem tool.\n",
+                encoding="utf-8",
+            )
+        written.append(seed)
+
     # The prompt source of truth — edited by hand or via `agentx prompt`.
     written.append(prompts_store.write_prompts(target, spec))
     # A single declarative manifest of the project (à la langgraph.json).

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/scaffold/spec.py

@@ -15,6 +15,12 @@ Framework = Literal["langgraph", "crewai"]
 MemoryMode = Literal["none", "short", "long", "both"]
 PromptStyle = Literal["default", "custom"]
 
+# How multiple agents are wired together (LangGraph only; CrewAI always uses sequential crew).
+#   supervisor  — an LLM router decides which worker acts next (dynamic, context-aware)
+#   sequential  — agents run in order: agent_1 → agent_2 → … (pipeline / chain-of-thought)
+#   parallel    — all agents handle the same input simultaneously; results are merged
+OrchestrationMode = Literal["supervisor", "sequential", "parallel"]
+
 
 def to_snake(name: str) -> str:
     s = re.sub(r"[^0-9a-zA-Z]+", "_", name.strip().lower()).strip("_")
@@ -40,6 +46,8 @@ class ProjectSpec(BaseModel):
     provider: str = "openai"
     model: str = ""                       # blank → provider default
     agents: list[AgentSpec] = Field(default_factory=lambda: [AgentSpec()])
+    # How agents are connected (only meaningful when len(agents) > 1 and framework == langgraph).
+    orchestration: OrchestrationMode = "supervisor"
     use_rag: bool = False
     memory: MemoryMode = "none"
     use_mcp: bool = False
@@ -84,3 +92,7 @@ class ProjectSpec(BaseModel):
     @property
     def use_long_memory(self) -> bool:
         return self.memory in ("long", "both")
+
+    @property
+    def multi_agent(self) -> bool:
+        return len(self.agents) > 1

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/scaffold/templates/ci.yml.j2

@@ -33,9 +33,15 @@ jobs:
       - name: Install
         run: uv pip install --system -e .
       - name: Run eval gate
+        # Non-blocking: the eval harness needs a reachable model (an API key or a
+        # local model server). Add your provider secret(s) below and drop
+        # `continue-on-error` to make this a hard CI gate.
+        continue-on-error: true
         env:
-          # Add your provider key as a repo secret to enable the gate.
-          OPENAI_API_KEY: {% raw %}${{ secrets.OPENAI_API_KEY }}{% endraw %}
-
+          AGENTX_PROVIDER: {{ spec.provider }}
+          AGENTX_MODEL: {{ model }}
+{% for v in provider_env %}
+          {{ v }}: {% raw %}${{ secrets.{% endraw %}{{ v }}{% raw %} }}{% endraw %}
+{% endfor %}
         run: python evals/run_evals.py
 {% endif %}

agentx_kit-0.7.0/src/agentx/scaffold/templates/env.example.j2

@@ -0,0 +1,25 @@
+# --- Provider selection (read by agentx) ---
+AGENTX_PROVIDER={{ spec.provider }}
+AGENTX_MODEL={{ model }}
+AGENTX_TEMPERATURE=0.3
+
+# --- Credentials for {{ provider_label }} ---
+{% for v in provider_env %}
+{{ v }}=
+{% endfor %}
+{% if not provider_env %}
+# {{ provider_label }} is local — no API key required.
+{% if spec.provider == 'ollama' %}
+# Start it first:  ollama serve   &&   ollama pull {{ model }}
+# OLLAMA_BASE_URL=http://localhost:11434
+{% endif %}
+{% endif %}
+{% if spec.observability %}
+
+# --- Observability (optional) ---
+AGENTX_TELEMETRY=true
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# LANGFUSE_PUBLIC_KEY=
+# LANGFUSE_SECRET_KEY=
+# LANGFUSE_HOST=https://cloud.langfuse.com
+{% endif %}

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/scaffold/templates/mcp_servers.json.j2

@@ -1,7 +1,7 @@
 {
   "filesystem": {
     "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "./knowledge"],
     "transport": "stdio"
   }
 }

{agentx_kit-0.6.0 → agentx_kit-0.7.0}/src/agentx/scaffold/templates/pkg/crew.py.j2

@@ -13,6 +13,11 @@ def build_project_crew(user_input: str):
     return build_crew(list(agents.values()), tasks)
 
 
-def run_text(message: str) -> str:
-    """Run the crew on a message and return the final text (used by main/server)."""
+def run_text(message: str, thread_id: str = "default") -> str:
+    """Run the crew on a message and return the final text (used by main/server).
+
+    ``thread_id`` is accepted for API-compatibility with the server; a CrewAI
+    kickoff is stateless per call, so it is not used to partition memory here.
+    """
+    del thread_id
     return str(build_project_crew(message).kickoff())

agentx_kit-0.7.0/src/agentx/scaffold/templates/pkg/graph.py.j2

@@ -0,0 +1,172 @@
+"""LangGraph workflow for {{ spec.slug }}.
+
+Exposes a module-level compiled ``graph`` (the LangGraph convention, also picked
+up by ``langgraph dev``) and ``run_text`` / ``stream_text`` helpers.
+
+{% if multi_agent %}
+Orchestration: {{ orchestration }}
+{% if orchestration == "supervisor" %}  An LLM router decides which specialist to call next.{% endif %}
+{% if orchestration == "sequential" %}  Agents run in order: {% for a in spec.agents %}{{ a.name }}{% if not loop.last %} → {% endif %}{% endfor %}.{% endif %}
+{% if orchestration == "parallel" %}  All agents answer simultaneously; results are merged.{% endif %}
+{% endif %}
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, START, StateGraph
+
+from .state import AgentState
+
+logger = logging.getLogger(__name__)
+
+RECURSION_LIMIT = 25
+{% if not multi_agent %}
+from langgraph.prebuilt import ToolNode, tools_condition
+
+from .nodes import call_model
+from .tools import get_tools
+
+
+def build_graph():
+    """Build a ReAct agent graph: agent ⇄ tools loop, with checkpointed memory."""
+    builder = StateGraph(AgentState)
+    builder.add_node("agent", call_model)
+    builder.add_node("tools", ToolNode(get_tools()))
+
+    builder.add_edge(START, "agent")
+    builder.add_conditional_edges("agent", tools_condition)
+    builder.add_edge("tools", "agent")
+
+    return builder.compile(checkpointer=MemorySaver())
+{% elif orchestration == "supervisor" %}
+from .nodes import WORKERS, make_worker, supervisor
+from .prompts import resolved_system_prompts
+
+
+def build_graph():
+    """Supervisor graph: an LLM router picks the next specialist each turn."""
+    builder = StateGraph(AgentState)
+    builder.add_node("supervisor", supervisor)
+    for name, system_prompt in resolved_system_prompts().items():
+        builder.add_node(name, make_worker(name, system_prompt))
+
+    builder.add_edge(START, "supervisor")
+    builder.add_conditional_edges(
+        "supervisor",
+        lambda state: state.get("next", "FINISH"),
+        {**{name: name for name in WORKERS}, "FINISH": END},
+    )
+    for name in WORKERS:
+        builder.add_edge(name, "supervisor")
+
+    return builder.compile(checkpointer=MemorySaver())
+{% elif orchestration == "sequential" %}
+from .nodes import WORKERS, make_worker
+from .prompts import resolved_system_prompts
+
+
+def build_graph():
+    """Sequential pipeline: agents run in order, each seeing the previous output."""
+    builder = StateGraph(AgentState)
+    prompts = resolved_system_prompts()
+    names = list(prompts)
+
+    for name in names:
+        builder.add_node(name, make_worker(name, prompts[name]))
+
+    builder.add_edge(START, names[0])
+    for i in range(len(names) - 1):
+        builder.add_edge(names[i], names[i + 1])
+    builder.add_edge(names[-1], END)
+
+    return builder.compile(checkpointer=MemorySaver())
+{% elif orchestration == "parallel" %}
+from langgraph.types import Send
+
+from .nodes import WORKERS, make_worker, merge_results
+from .prompts import resolved_system_prompts
+
+
+def _fan_out(state: AgentState) -> list[Send]:
+    """Send the same user message to every worker simultaneously."""
+    return [Send(name, state) for name in WORKERS]
+
+
+def build_graph():
+    """Parallel graph: all agents answer simultaneously, then results are merged."""
+    builder = StateGraph(AgentState)
+    for name, system_prompt in resolved_system_prompts().items():
+        builder.add_node(name, make_worker(name, system_prompt))
+    builder.add_node("merge", merge_results)
+
+    builder.add_conditional_edges(START, _fan_out, WORKERS)
+    for name in WORKERS:
+        builder.add_edge(name, "merge")
+    builder.add_edge("merge", END)
+
+    return builder.compile(checkpointer=MemorySaver())
+{% endif %}
+
+
+graph = build_graph()
+
+
+def _config(thread_id: str) -> dict:
+    return {"configurable": {"thread_id": thread_id}, "recursion_limit": RECURSION_LIMIT}
+
+
+async def arun_text(message: str, thread_id: str = "default") -> str:
+    """Async invoke; runs async-only tools (MCP) correctly.
+
+    Pass a unique ``thread_id`` per user/session — callers that omit it share
+    one conversation history (fine for a single CLI session, wrong for a server).
+    """
+    try:
+        result = await graph.ainvoke(
+            {"messages": [{"role": "user", "content": message}]}, config=_config(thread_id)
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("graph invocation failed")
+        return f"Sorry, something went wrong: {exc}"
+    messages = result.get("messages", [])
+    return getattr(messages[-1], "content", "") if messages else ""
+
+
+_loop: asyncio.AbstractEventLoop | None = None
+
+
+def _sync_loop() -> asyncio.AbstractEventLoop:
+    """Reuse one loop across calls so MCP stdio sessions don't break on turn 2."""
+    global _loop
+    if _loop is None or _loop.is_closed():
+        _loop = asyncio.new_event_loop()
+    return _loop
+
+
+def run_text(message: str, thread_id: str = "default") -> str:
+    """Sync wrapper for CLI / REPL use. Do NOT call from an async context."""
+    return _sync_loop().run_until_complete(arun_text(message, thread_id))
+
+
+async def stream_text(message: str, thread_id: str = "default"):
+    """Yield reply tokens as the model produces them."""
+    try:
+        async for _ns, (chunk, meta) in graph.astream(
+            {"messages": [{"role": "user", "content": message}]},
+            config=_config(thread_id),
+            stream_mode="messages",
+            subgraphs=True,
+        ):
+{% if multi_agent and orchestration == "supervisor" %}
+            if meta.get("langgraph_node") == "supervisor":
+                continue
+{% endif %}
+            text = getattr(chunk, "content", "")
+            if text:
+                yield text
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("graph streaming failed")
+        yield f"Sorry, something went wrong: {exc}"

agentx_kit-0.7.0/src/agentx/scaffold/templates/pkg/memory.py.j2

@@ -0,0 +1,25 @@
+"""Memory helpers for {{ spec.slug }} (mode: {{ spec.memory }}).
+
+NOTE: the LangGraph graph already keeps short-term conversation memory per
+``thread_id`` via its checkpointer (see graph.py). These helpers are optional
+extras for when you want an explicit rolling window or durable cross-session
+storage outside the graph — import them where you need them.
+"""
+from __future__ import annotations
+
+{% if spec.use_short_memory %}
+from agentx.memory import ConversationMemory
+
+
+def new_session_memory(max_turns: int = 12) -> ConversationMemory:
+    """A short-term, in-process rolling window of recent turns."""
+    return ConversationMemory(max_turns=max_turns)
+{% endif %}
+{% if spec.use_long_memory %}
+from agentx.memory import LongTermMemory
+
+
+def long_term(session_id: str = "default") -> LongTermMemory:
+    """Persistent per-session memory (JSONL under data/memory/)."""
+    return LongTermMemory(f"data/memory/{session_id}.jsonl")
+{% endif %}

agentx_kit-0.7.0/src/agentx/scaffold/templates/pkg/nodes.py.j2

@@ -0,0 +1,219 @@
+"""Graph nodes for {{ spec.slug }}.
+
+A node is a function ``state -> partial state``. The model is built through
+AgentX's provider-agnostic factory but everything else is plain LangChain /
+LangGraph, so you fully own the graph.
+"""
+from __future__ import annotations
+
+import json
+import logging
+
+from langchain_core.messages import AIMessage, SystemMessage
+
+from agentx import get_chat_model
+from .config import MODEL, PROVIDER
+from .prompts import resolved_system_prompts
+from .tools import get_tools
+{% if spec.use_skills %}from agentx.skills import get_skill_registry
+{% endif %}
+
+logger = logging.getLogger(__name__)
+
+_TOOLS = get_tools()
+_TOOL_MAP = {t.name: t for t in _TOOLS}
+
+
+def _model(bind_tools: bool = True):
+    llm = get_chat_model(PROVIDER, MODEL)
+    return llm.bind_tools(_TOOLS) if bind_tools and _TOOLS else llm
+
+
+{% if spec.use_skills %}
+def _skills_suffix() -> str:
+    skills = get_skill_registry("data/skills").combined_instructions()
+    return ("\nApply these skills:\n" + skills) if skills else ""
+{% endif %}
+
+async def _exec_json_tool_call(content: str) -> str | None:
+    """Fallback for models (e.g. llama3.2/Ollama) that emit tool calls as JSON
+    text instead of populating the structured ``tool_calls`` field.
+
+    Returns the tool result string, or None if the content isn't a tool call.
+    """
+    try:
+        data = json.loads(content.strip())
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(data, dict) or "name" not in data:
+        return None
+
+    name: str = data["name"]
+    args = data.get("parameters", data.get("args", data.get("arguments", {})))
+    if not isinstance(args, dict):
+        return None
+
+    # Match by exact name, then by description prefix (models sometimes use the
+    # description instead of the function name).
+    tool = _TOOL_MAP.get(name)
+    if tool is None:
+        for t in _TOOLS:
+            if t.description.lower().startswith(name.lower()[:30]):
+                tool = t
+                break
+    if tool is None:
+        logger.debug("json_tool_call: no tool matched name=%r", name)
+        return None
+
+    try:
+        return str(await tool.ainvoke(args))
+    except NotImplementedError:
+        try:
+            return str(tool.invoke(args))
+        except Exception as exc:
+            logger.warning("json_tool_call execution failed: %s", exc)
+            return None
+    except Exception as exc:
+        logger.warning("json_tool_call execution failed: %s", exc)
+        return None
+
+
+{% if not multi_agent %}
+# ---- Single agent ----
+_PROMPTS = resolved_system_prompts()
+_SYSTEM = next(iter(_PROMPTS.values()), "You are a helpful assistant.")
+{% if spec.use_skills %}_SYSTEM = _SYSTEM + _skills_suffix()
+{% endif %}
+
+
+async def call_model(state) -> dict:
+    """Agent node: call the LLM, execute tools, and return a final answer.
+
+    Handles two tool-calling patterns:
+    - Structured ``tool_calls`` field (OpenAI, Anthropic, newer Ollama models):
+      the built-in ``ToolNode`` / ``tools_condition`` picks these up normally.
+    - JSON text in ``content`` (llama3.2 and other small Ollama models):
+      detected here, executed directly, and folded back into the final reply.
+    """
+    messages = [SystemMessage(_SYSTEM)] + state["messages"]
+    try:
+        response = await _model().ainvoke(messages)
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("call_model failed")
+        return {"messages": [AIMessage(content=f"Sorry, I hit an error contacting the model: {exc}")]}
+
+    # If the model supports structured tool calling, return the response as-is
+    # and let the graph's ToolNode / tools_condition handle the rest.
+    if response.tool_calls:
+        return {"messages": [response]}
+
+    # Fallback: detect JSON tool calls emitted as plain text (llama3.2 style).
+    if _TOOLS and response.content:
+        tool_result = await _exec_json_tool_call(str(response.content))
+        if tool_result is not None:
+            logger.debug("json_tool_call executed; re-invoking with result")
+            augmented = messages + [
+                response,
+                {"role": "user", "content": (
+                    f"[Tool result]\n{tool_result}\n\n"
+                    "Use the above result to answer the original question directly and concisely."
+                )},
+            ]
+            try:
+                response = await _model(bind_tools=False).ainvoke(augmented)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("re-invoke after tool result failed: %s", exc)
+
+    return {"messages": [response]}
+{% else %}
+# ---- Multi-agent ({{ orchestration }}) ----
+from langgraph.prebuilt import create_react_agent
+
+WORKERS = list(resolved_system_prompts().keys())
+
+
+def make_worker(name: str, system_prompt: str):
+    """Build a worker as a full ReAct sub-agent (tools actually execute)."""
+{% if spec.use_skills %}    system_prompt = system_prompt + _skills_suffix()
+{% endif %}
+    agent = create_react_agent(_model(bind_tools=False), _TOOLS, prompt=system_prompt)
+
+    async def worker(state) -> dict:
+        try:
+            result = await agent.ainvoke(
+                {"messages": state["messages"]},
+                config={"recursion_limit": 12},
+            )
+            # get last non-empty AIMessage
+            content = ""
+            for m in reversed(result["messages"]):
+                c = getattr(m, "content", "")
+                if c and isinstance(c, str):
+                    content = c
+                    break
+            # Fallback: execute JSON tool call emitted by the sub-agent's model
+            if not content or (content.startswith("{") and '"name"' in content):
+                tool_result = await _exec_json_tool_call(content or "")
+                if tool_result:
+                    try:
+                        follow_up = result["messages"] + [
+                            {"role": "user", "content": (
+                                f"[Tool result]\n{tool_result}\n\n"
+                                "Now answer the user's original question using this result."
+                            )}
+                        ]
+                        fr = await _model(bind_tools=False).ainvoke(
+                            [SystemMessage(system_prompt)] + follow_up
+                        )
+                        content = fr.content or content
+                    except Exception as exc:
+                        logger.warning("worker '%s' follow-up failed: %s", name, exc)
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("worker '%s' failed", name)
+            content = f"Sorry, I ({name}) hit an error: {exc}"
+        return {"messages": [AIMessage(content=content, name=name)]}
+
+    return worker
+
+{% if orchestration == "supervisor" %}
+_SUPERVISOR_SYSTEM = (
+    "You are a supervisor routing work between these specialists: {workers}. "
+    "Read the conversation and decide who should act NEXT to make progress.\n"
+    "Rules:\n"
+    "- Reply with ONLY one token and nothing else.\n"
+    "- The token must be exactly one of: {choices}.\n"
+    "- Pick the single most relevant specialist for an unanswered request.\n"
+    "- Reply FINISH if the latest assistant message already answers the user, "
+    "or if no specialist can help further."
+)
+
+
+def supervisor(state) -> dict:
+    """Router node: pick the next worker (or FINISH)."""
+    choices = WORKERS + ["FINISH"]
+    sys = _SUPERVISOR_SYSTEM.format(workers=", ".join(WORKERS), choices=", ".join(choices))
+    try:
+        response = _model(bind_tools=False).invoke([SystemMessage(sys)] + state["messages"])
+        raw = (response.content or "").strip()
+    except Exception:  # noqa: BLE001
+        logger.exception("supervisor routing failed; finishing")
+        return {"next": "FINISH"}
+
+    lowered = raw.lower()
+    choice = "FINISH"
+    for name in WORKERS:
+        if name.lower() in lowered:
+            choice = name
+            break
+    logger.debug("supervisor routed to %s (raw=%r)", choice, raw[:80])
+    return {"next": choice}
+{% elif orchestration == "parallel" %}
+def merge_results(state) -> dict:
+    """Collect all worker outputs and present them together."""
+    worker_msgs = [m for m in state["messages"] if getattr(m, "name", None) in set(WORKERS)]
+    if not worker_msgs:
+        return {}
+    combined = "\n\n".join(f"**{m.name}**:\n{m.content}" for m in worker_msgs)
+    return {"messages": [AIMessage(content=combined)]}
+{% endif %}
+{% endif %}