Script for creating agents which can plug anywhere

A developer has released a bash script that scaffolds a portable, embeddable LangGraph agent codebase. The script, named create-agent.sh, generates a generic project structure with state, config, and graph modules, and runs the agent immediately to provide proof-of-life output. It is designed to work for any agent and supports injection of LLM clients, checkpointers, and tools.

| /usr/bin/env bash | | | create-agent.sh — scaffold a portable, embeddable LangGraph agent codebase. | | | Fully generic: no domain-specific nodes, works for ANY agent you build. | | | | | | Usage: | | | ./create-agent.sh my agent | | | | | | After scaffolding, it installs deps and RUNS the agent immediately so | | | you get proof-of-life output, not just a pile of files. | | | set -euo pipefail | | | if -z "${1:-}" ; then | | | echo "Usage: $0 <agent name snake case " | | | exit 1 | | | fi | | | NAME="$1" | | | PKG="src/${NAME}" | | | mkdir -p "${PKG}"/{nodes,tools,adapters} | | | mkdir -p examples tests | | | ---------- state.py ---------- | | | cat "${PKG}/state.py" << 'EOF' | | | """ | | | Public contract for this agent. Treat like a versioned API schema: | | | additive changes only, since hosts embedding this agent depend on these shapes. | | | """ | | | from typing import TypedDict, Optional | | | class InputState TypedDict : | | | """What a caller must provide. Add/rename fields for your agent.""" | | | query: str | | | context: Optional dict | | | class OutputState TypedDict : | | | """What a caller gets back. Nothing else leaks out of the graph.""" | | | result: str | | | metadata: dict | | | class InternalState InputState, OutputState : | | | """Full scratchpad state used only inside this graph's nodes. | | | Add whatever fields your nodes need to pass data between steps.""" | | | iterations: int | | | scratch: dict | | | EOF | | | ---------- config.py ---------- | | | cat "${PKG}/config.py" << 'EOF' | | | """ | | | Everything that varies by host LLM client, checkpointer, tools, callbacks | | | is injected here, never imported directly inside node files. | | | """ | | | from dataclasses import dataclass, field | | | from typing import Any, Callable, Optional | | | @dataclass | | | class AgentConfig: | | | llm: Any = None inject a real client for production use | | | checkpointer: Optional Any = None host may pass Postgres/Redis saver; None = in-memory | | | tools: list = field default factory=list | | | max iterations: int = 5 | | | on event: Optional Callable str, dict , None = None optional observability hook | | | class MockLLM: | | | """Zero-setup stand-in so the scaffold runs immediately with no API keys. | | | Swap AgentConfig.llm for a real client ChatAnthropic, ChatOpenAI, etc. .""" | | | def invoke self, prompt: str - str: | | | return f" mock output for: {str prompt :60 } " | | | def default config - AgentConfig: | | | """Sensible standalone defaults — used by examples/ and the self-test below.""" | | | return AgentConfig llm=MockLLM | | | EOF | | | ---------- graph.py ---------- | | | cat "${PKG}/graph.py" << EOF | | | """ | | | The single product of this package: build graph config - CompiledStateGraph. | | | Every adapter subgraph / tool / MCP / REST / CLI wraps THIS and only this. | | | The example flow below process - loop - finish is a placeholder. | | | Replace the nodes in nodes/ with your real logic; the graph wiring here | | | is deliberately generic so it fits any agent shape you build. | | | """ | | | from langgraph.graph import StateGraph, START, END | | | from langgraph.checkpoint.memory import MemorySaver | | | from .state import InternalState, InputState, OutputState | | | from .config import AgentConfig | | | from .nodes.process import make process node | | | from .nodes.finish import make finish node | | | def should continue state: InternalState - str: | | | if state.get "iterations", 0 = state.get " max iterations", 5 : | | | return "finish" | | | return "finish" if state.get "scratch", {} .get "done", True else "process" | | | def build graph config: AgentConfig : | | | builder = StateGraph InternalState, input schema=InputState, output schema=OutputState | | | builder.add node "process", make process node config | | | builder.add node "finish", make finish node config | | | builder.add edge START, "process" | | | builder.add conditional edges "process", should continue, { | | | "process": "process", | | | "finish": "finish", | | | } | | | builder.add edge "finish", END | | | checkpointer = config.checkpointer or MemorySaver | | | return builder.compile checkpointer=checkpointer | | | EOF | | | ---------- nodes/process.py generic — replace with your logic ---------- | | | cat "${PKG}/nodes/process.py" << 'EOF' | | | """Generic processing node. Factory pattern: takes AgentConfig, returns a | | | node function. Replace the body with your actual step logic — this is | | | just a working placeholder so the graph runs out of the box.""" | | | from ..config import AgentConfig | | | from ..state import InternalState | | | def make process node config: AgentConfig : | | | def node state: InternalState - dict: | | | iterations = state.get "iterations", 0 + 1 | | | if config.on event: | | | config.on event "process", {"iteration": iterations} | | | TODO: real logic here, e.g. call config.llm.invoke ... or config.tools | | | return { | | | "iterations": iterations, | | | "scratch": {"done": True}, flip logic here to loop more than once | | | } | | | return node | | | EOF | | | ---------- nodes/finish.py generic — replace with your logic ---------- | | | cat "${PKG}/nodes/finish.py" << 'EOF' | | | """Generic finishing node. Produces the OutputState. Replace with your | | | actual synthesis/response-formatting logic.""" | | | from ..config import AgentConfig | | | from ..state import InternalState | | | def make finish node config: AgentConfig : | | | def node state: InternalState - dict: | | | query = state.get "query", "" | | | output = config.llm.invoke query if config.llm else f"processed: {query}" | | | return { | | | "result": output, | | | "metadata": {"iterations": state.get "iterations", 0 }, | | | } | | | return node | | | EOF | | | ---------- tools/registry.py ---------- | | | cat "${PKG}/tools/registry.py" << 'EOF' | | | """Central place to define/collect tools. Hosts can override via | | | AgentConfig.tools instead of editing this file, so the agent stays embeddable.""" | | | from langchain core.tools import tool | | | @tool | | | def example tool query: str - str: | | | """Placeholder tool. Replace or extend, or inject alternatives via config.""" | | | return f"result for: {query}" | | | DEFAULT TOOLS = example tool | | | EOF | | | ---------- adapters/as subgraph.py ---------- | | | cat "${PKG}/adapters/as subgraph.py" << EOF | | | """ | | | Embed this agent as a single node inside a HOST LangGraph graph. | | | from ${NAME}.adapters.as subgraph import get subgraph node | | | parent builder.add node "my agent", get subgraph node config | | | """ | | | from ..graph import build graph | | | from ..config import AgentConfig, default config | | | def get subgraph node config: AgentConfig = None : | | | """Returns the compiled graph directly — LangGraph treats a compiled | | | StateGraph as a valid node. Map field names in the host graph if the | | | parent's state keys differ from InputState/OutputState.""" | | | return build graph config or default config | | | EOF | | | ---------- adapters/as tool.py ---------- | | | cat "${PKG}/adapters/as tool.py" << EOF | | | """ | | | Expose this agent as a single LangChain tool for a host ReAct-style agent | | | that wants to call it as a leaf action rather than embed it as a subgraph. | | | """ | | | from langchain core.tools import tool | | | from ..graph import build graph | | | from ..config import AgentConfig, default config | | | def get agent tool config: AgentConfig = None : | | | graph = build graph config or default config | | | @tool | | | def ${NAME} query: str - str: | | | """Run the ${NAME} agent on a query and return its result.""" | | | out = graph.invoke {"query": query, "context": None}, | | | config={"configurable": {"thread id": "1"}} | | | return out "result" | | | return ${NAME} | | | EOF | | | ---------- adapters/as mcp server.py ---------- | | | cat "${PKG}/adapters/as mcp server.py" << EOF | | | """ | | | Expose this agent as an MCP server so any MCP-capable host agentic IDE, | | | Claude Code, Cursor, etc. can call it as a single tool without custom | | | integration code. Run: python -m ${NAME}.adapters.as mcp server | | | """ | | | from mcp.server.fastmcp import FastMCP | | | from ..graph import build graph | | | from ..config import default config | | | mcp = FastMCP "${NAME}" | | | @mcp.tool | | | def run agent query: str, context: dict | None = None - dict: | | | """Run the agent and return its OutputState.""" | | | graph = build graph default config swap in real config/llm as needed | | | return graph.invoke {"query": query, "context": context}, | | | config={"configurable": {"thread id": "1"}} | | | if name == " main ": | | | mcp.run | | | EOF | | | ---------- adapters/as rest api.py ---------- | | | cat "${PKG}/adapters/as rest api.py" << EOF | | | """ | | | Expose this agent over HTTP for language-agnostic hosts. | | | Run: uvicorn ${NAME}.adapters.as rest api:app --reload | | | """ | | | from fastapi import FastAPI | | | from pydantic import BaseModel | | | from ..graph import build graph | | | from ..config import default config | | | app = FastAPI title="${NAME}" | | | graph = build graph default config wire real config at startup | | | class Request BaseModel : | | | query: str | | | context: dict | None = None | | | @app.post "/invoke" | | | def invoke req: Request : | | | return graph.invoke {"query": req.query, "context": req.context}, | | | config={"configurable": {"thread id": "1"}} | | | EOF | | | ---------- adapters/as cli.py ---------- | | | cat "${PKG}/adapters/as cli.py" << EOF | | | """Local dev/debug entrypoint. Run: python -m ${NAME}.adapters.as cli "your query" """ | | | import sys | | | from ..graph import build graph | | | from ..config import default config | | | def main : | | | query = " ".join sys.argv 1: or "example query" | | | graph = build graph default config | | | result = graph.invoke {"query": query, "context": None}, | | | config={"configurable": {"thread id": "1"}} | | | print result | | | if name == " main ": | | | main | | | EOF | | | ---------- init .py files ---------- | | | touch "${PKG}/ init .py" "${PKG}/nodes/ init .py" "${PKG}/tools/ init .py" "${PKG}/adapters/ init .py" | | | ---------- examples ---------- | | | cat "examples/standalone run.py" << EOF | | | from ${NAME}.graph import build graph | | | from ${NAME}.config import default config | | | if name == " main ": | | | graph = build graph default config | | | result = graph.invoke {"query": "example question", "context": None}, | | | config={"configurable": {"thread id": "1"}} | | | print result | | | EOF | | | cat "examples/embed in parent graph.py" << EOF | | | """Shows how a HOST system with its own LangGraph would embed this agent as one node.""" | | | from langgraph.graph import StateGraph, START, END | | | from typing import TypedDict | | | from ${NAME}.adapters.as subgraph import get subgraph node | | | class HostState TypedDict : | | | query: str | | | context: dict | None | | | result: str | | | metadata: dict | | | host builder = StateGraph HostState | | | host builder.add node "${NAME}", get subgraph node | | | host builder.add edge START, "${NAME}" | | | host builder.add edge "${NAME}", END | | | host graph = host builder.compile | | | if name == " main ": | | | print host graph.invoke {"query": "example question", "context": None}, | | | config={"configurable": {"thread id": "1"}} | | | EOF | | | ---------- tests ---------- | | | cat "tests/test graph.py" << EOF | | | from ${NAME}.graph import build graph | | | from ${NAME}.config import default config | | | def test graph compiles : | | | graph = build graph default config | | | assert graph is not None | | | def test graph runs end to end : | | | graph = build graph default config | | | out = graph.invoke {"query": "hello", "context": None}, | | | config={"configurable": {"thread id": "1"}} | | | assert "result" in out | | | EOF | | | ---------- pyproject.toml ---------- | | | cat "pyproject.toml" << EOF | | | project | | | name = "${NAME}" | | | version = "0.1.0" | | | requires-python = " =3.11" | | | dependencies = | | | "langgraph =0.2", | | | "langchain-core", | | | "fastapi", | | | "uvicorn", | | | "mcp", | | | | | | tool.setuptools.packages.find | | | where = "src" | | | EOF | | | ---------- README.md ---------- | | | cat "README.md" << EOF | | | ${NAME} | | | Single source of truth: \ src/${NAME}/graph.py\ — \ build graph config - CompiledStateGraph\ . | | | Everything else is an adapter around it. Replace the placeholder nodes in | | | \ nodes/\ with your real logic; do NOT add invocation-layer imports | | | FastAPI, MCP SDK, etc. inside \ nodes/\ , \ graph.py\ , or \ state.py\ — | | | that belongs only in \ adapters/\ . | | | Structure | | | - \ state.py\ — public contract InputState/OutputState + internal scratchpad. | | | - \ config.py\ — injected LLM/checkpointer/tools/callbacks. MockLLM by default so it runs with zero setup. | | | - \ nodes/\ — one file per graph node, factory pattern \ make x node config \ . Replace with real logic. | | | - \ tools/registry.py\ — default tools; hosts can override via \ AgentConfig.tools\ . | | | - \ adapters/\ — every way this agent can be consumed: | | | - \ as subgraph.py\ — embed as a node in another LangGraph graph | | | - \ as tool.py\ — expose as a single LangChain tool for a ReAct-style host | | | - \ as mcp server.py\ — expose via MCP for agentic IDEs / Claude Code-like hosts | | | - \ as rest api.py\ — expose over HTTP for non-Python hosts | | | - \ as cli.py\ — local dev/debug entrypoint | | | Quickstart | | | \ \ \ bash | | | pip install -e . | | | python examples/standalone run.py | | | python -m ${NAME}.adapters.as cli "your query" | | | \ \ \ | | | EOF | | | echo "✅ Scaffolded '${NAME}'." | | | echo "" | | | Only install what's missing — don't touch existing system packages. | | | echo "Checking dependencies..." | | | python3 -c "import langgraph, langchain core" 2 /dev/null || \ | | | pip install --break-system-packages -q langgraph langchain-core | | | echo "" | | | echo "=== Self-test: running the agent right now no install needed ===" | | | PYTHONPATH="src:${PYTHONPATH:-}" python3 examples/standalone run.py | | | echo "=== If you see a result dict above, the scaffold works. ===" | | | echo "" | | | echo "To use it as an installable package later: pip install -e . in a venv " |