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

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: agentx-kit
-Version: 0.5.1
+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.5.1 → 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.5.1"
+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.5.1 → agentx_kit-0.7.0}/src/agentx/__init__.py

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

{agentx_kit-0.5.1 → 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.5.1 → 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.5.1 → agentx_kit-0.7.0}/src/agentx/connector/build.py

@@ -74,10 +74,11 @@ def build_project_from_statement(
     # Collect a compact view for the calling LLM.
     tree = sorted(str(p.relative_to(root)) for p in root.glob("**/*") if p.is_file())
     pkg = spec.package
-    key_paths = [
-        "pyproject.toml", "prompts.json", "agentx.json",
-        f"src/{pkg}/main.py", f"src/{pkg}/agents.py", f"src/{pkg}/prompts.py",
-    ]
+    key_paths = ["pyproject.toml", "prompts.json", "agentx.json", f"src/{pkg}/main.py"]
+    if spec.framework == "langgraph":
+        key_paths += [f"src/{pkg}/graph.py", f"src/{pkg}/state.py", f"src/{pkg}/nodes.py"]
+    else:
+        key_paths += [f"src/{pkg}/crew.py", f"src/{pkg}/agents.py", f"src/{pkg}/tasks.py"]
     if spec.serve:
         key_paths.append(f"src/{pkg}/server.py")
     key_files = {}

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

@@ -18,8 +18,8 @@ from .spec import ProjectSpec
 
 TEMPLATES_DIR = Path(__file__).parent / "templates"
 
-# (template, output-relative-path, include?) — output paths use {pkg} placeholder.
-_FILE_PLAN: list[tuple[str, str]] = [
+# (template, output-relative-path) — output paths use {pkg} placeholder.
+_COMMON_FILES: list[tuple[str, str]] = [
     ("pyproject.toml.j2", "pyproject.toml"),
     ("README.md.j2", "README.md"),
     ("env.example.j2", ".env.example"),
@@ -27,10 +27,24 @@ _FILE_PLAN: list[tuple[str, str]] = [
     ("pkg/__init__.py.j2", "src/{pkg}/__init__.py"),
     ("pkg/config.py.j2", "src/{pkg}/config.py"),
     ("pkg/prompts.py.j2", "src/{pkg}/prompts.py"),
-    ("pkg/agents.py.j2", "src/{pkg}/agents.py"),
     ("pkg/main.py.j2", "src/{pkg}/main.py"),
 ]
 
+# A real LangGraph project: explicit state + nodes + graph + tool assembly.
+_LANGGRAPH_FILES: list[tuple[str, str]] = [
+    ("pkg/state.py.j2", "src/{pkg}/state.py"),
+    ("pkg/tools.py.j2", "src/{pkg}/tools.py"),
+    ("pkg/nodes.py.j2", "src/{pkg}/nodes.py"),
+    ("pkg/graph.py.j2", "src/{pkg}/graph.py"),
+]
+
+# A real CrewAI project: agents + tasks + crew.
+_CREWAI_FILES: list[tuple[str, str]] = [
+    ("pkg/agents.py.j2", "src/{pkg}/agents.py"),
+    ("pkg/tasks.py.j2", "src/{pkg}/tasks.py"),
+    ("pkg/crew.py.j2", "src/{pkg}/crew.py"),
+]
+
 
 @dataclass
 class GenerationResult:
@@ -70,6 +84,8 @@ def _context(spec: ProjectSpec) -> dict:
         "provider_env": list(provider_spec.env_vars),
         "extras": _extras(spec),
         "extras_str": ",".join(_extras(spec)),
+        "multi_agent": len(spec.agents) > 1,
+        "orchestration": spec.orchestration,
     }
 
 
@@ -85,12 +101,13 @@ def _env() -> Environment:
 
 def _conditional_files(spec: ProjectSpec) -> list[tuple[str, str]]:
     plan: list[tuple[str, str]] = []
+    # Framework-specific core (real project structure).
+    plan += _LANGGRAPH_FILES if spec.framework == "langgraph" else _CREWAI_FILES
     if spec.use_rag:
         plan.append(("pkg/rag.py.j2", "src/{pkg}/rag.py"))
     if spec.needs_memory:
         plan.append(("pkg/memory.py.j2", "src/{pkg}/memory.py"))
     if spec.use_mcp:
-        plan.append(("pkg/tools.py.j2", "src/{pkg}/tools.py"))
         plan.append(("mcp_servers.json.j2", "mcp_servers.json"))
     if spec.use_skills:
         plan.append(("skills_seed.json.j2", "data/skills/star-method.json"))
@@ -123,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,
@@ -156,13 +174,28 @@ def generate_project(spec: ProjectSpec, target_dir: str | Path, overwrite: bool
     written: list[Path] = []
     messages: list[str] = []
 
-    for template_name, out_rel in _FILE_PLAN + _conditional_files(spec):
+    for template_name, out_rel in _COMMON_FILES + _conditional_files(spec):
         out_path = target / out_rel.format(pkg=spec.package)
         out_path.parent.mkdir(parents=True, exist_ok=True)
         rendered = env.get_template(template_name).render(**ctx)
         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.5.1 → 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.7.0/src/agentx/scaffold/templates/README.md.j2

@@ -0,0 +1,69 @@
+# {{ spec.slug }}
+
+Agentic app generated by **AgentX**.
+
+- **Framework:** {{ spec.framework }}
+- **Provider:** {{ provider_label }} (`{{ model }}`)
+- **Agents:** {% for a in spec.agents %}`{{ a.name }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+- **RAG:** {{ "yes" if spec.use_rag else "no" }}
+- **Memory:** {{ spec.memory }}
+- **MCP tools:** {{ "yes" if spec.use_mcp else "no" }}
+- **Skills:** {{ "yes" if spec.use_skills else "no" }}
+
+## Setup
+```bash
+uv sync                 # install dependencies into .venv
+cp .env.example .env    # then fill in your credentials
+```
+
+## Run
+```bash
+uv run {{ spec.slug }}
+# or:
+uv run python -m {{ pkg }}.main
+{% if spec.serve %}# API server:
+uv run uvicorn {{ pkg }}.server:app --reload
+{% endif %}
+```
+{% if spec.framework == 'langgraph' %}
+Uses LangGraph's dev server too: `uvx langgraph dev` (the compiled graph is
+`{{ pkg }}.graph:graph`).
+
+## Layout (LangGraph)
+```
+src/{{ pkg }}/
+├── config.py     # provider/model selection (pydantic-settings)
+├── prompts.py    # loads prompts.json (edit prompts there or via `agentx prompt`)
+├── state.py      # AgentState — the typed graph state (messages + reducers)
+├── tools.py      # tool assembly (web search{% if spec.use_rag %} + knowledge base{% endif %}{% if spec.use_mcp %} + MCP{% endif %})
+├── nodes.py      # graph nodes ({% if multi_agent %}supervisor + workers{% else %}the agent model call{% endif %})
+├── graph.py      # StateGraph workflow + compiled `graph` + run_text()
+{% if spec.use_rag %}├── rag.py        # knowledge base / retriever tool
+{% endif %}
+{% if spec.needs_memory %}├── memory.py     # conversation / long-term memory helpers
+{% endif %}
+{% if spec.serve %}├── server.py     # FastAPI (REST + SSE)
+{% endif %}
+└── main.py       # interactive REPL
+```
+{% else %}
+## Layout (CrewAI)
+```
+src/{{ pkg }}/
+├── config.py     # provider/model selection (pydantic-settings)
+├── prompts.py    # loads prompts.json
+├── agents.py     # CrewAI Agent definitions
+├── tasks.py      # Task definitions
+├── crew.py       # Crew assembly + run_text()
+{% if spec.serve %}├── server.py     # FastAPI (REST + SSE)
+{% endif %}
+└── main.py       # interactive REPL
+```
+{% endif %}
+{% if spec.use_rag %}
+Add `.txt`/`.md` files under `knowledge/` to populate the RAG index.
+{% endif %}
+{% if spec.use_mcp %}
+Edit `mcp_servers.json` to configure your MCP servers.
+{% endif %}

{agentx_kit-0.5.1 → 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.5.1 → agentx_kit-0.7.0}/src/agentx/scaffold/templates/evals/run_evals.py.j2

@@ -17,10 +17,9 @@ from dotenv import load_dotenv
 
 from agentx import get_chat_model
 {% if spec.framework == 'langgraph' %}
-from agentx.frameworks import run_agent
-from {{ pkg }}.agents import build_agents
+from {{ pkg }}.graph import run_text
 {% else %}
-from {{ pkg }}.agents import build_project_crew
+from {{ pkg }}.crew import run_text
 {% endif %}
 
 THRESHOLD = 0.6
@@ -35,12 +34,7 @@ JUDGE_PROMPT = (
 
 
 def _agent_reply(message: str) -> str:
-{% if spec.framework == 'langgraph' %}
-    agent = next(iter(build_agents().values()))
-    return run_agent(agent, message)
-{% else %}
-    return str(build_project_crew(message).kickoff())
-{% endif %}
+    return run_text(message)
 
 
 def _score(judge, case: dict, output: str) -> float:

{agentx_kit-0.5.1 → 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.7.0/src/agentx/scaffold/templates/pkg/agents.py.j2

@@ -0,0 +1,21 @@
+"""Agent definitions (CrewAI) for {{ spec.slug }} — built from prompts.json."""
+from __future__ import annotations
+
+from agentx.frameworks import build_crewai_agent
+from .config import MODEL, PROVIDER
+from .prompts import agents_meta, resolved_system_prompts
+
+
+def build_agents() -> dict:
+    """Return {name: CrewAI Agent} — one per entry in prompts.json."""
+    prompts = resolved_system_prompts()
+    agents: dict = {}
+    for name, meta in agents_meta().items():
+        agents[name] = build_crewai_agent(
+            role=meta.get("role", name),
+            goal=meta.get("goal", "Help the user accomplish their task accurately."),
+            backstory=prompts.get(name, ""),
+            provider=PROVIDER,
+            model=MODEL,
+        )
+    return agents

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

@@ -0,0 +1,23 @@
+"""Crew assembly (CrewAI) for {{ spec.slug }}."""
+from __future__ import annotations
+
+from agentx.frameworks import build_crew
+from .agents import build_agents
+from .tasks import build_tasks
+
+
+def build_project_crew(user_input: str):
+    """Assemble a sequential crew of all agents for the user's request."""
+    agents = build_agents()
+    tasks = build_tasks(user_input, agents)
+    return build_crew(list(agents.values()), tasks)
+
+
+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/main.py.j2

@@ -0,0 +1,45 @@
+"""Entry point for {{ spec.slug }} — an interactive REPL over the agent graph."""
+from __future__ import annotations
+
+from dotenv import load_dotenv
+{% if spec.observability %}from .observability import init_observability
+{% endif %}
+{% if spec.guardrails %}from .guardrails import guard_input, guard_output
+{% endif %}
+{% if spec.use_cache %}from agentx.cache import enable_caching
+{% endif %}
+{% if spec.framework == 'langgraph' %}from .graph import run_text
+{% else %}from .crew import run_text
+{% endif %}
+
+
+def main() -> None:
+    load_dotenv()
+{% if spec.observability %}
+    init_observability()
+{% endif %}
+{% if spec.use_cache %}
+    enable_caching()   # cache LLM responses → lower cost & latency
+{% endif %}
+    print("🧬 {{ spec.slug }} ready. Type 'quit' to exit.\n")
+    while True:
+        try:
+            user = input("you > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if user.lower() in {"quit", "exit"}:
+            break
+        if not user:
+            continue
+{% if spec.guardrails %}
+        user = guard_input(user).text
+{% endif %}
+        reply = run_text(user)
+{% if spec.guardrails %}
+        reply = guard_output(reply).text
+{% endif %}
+        print(f"\nbot > {reply}\n")
+
+
+if __name__ == "__main__":
+    main()