agentic-workflow-mcp

Multi-agent orchestration with a LangGraph supervisor, a CrewAI-shaped crew, in-process MCP tools, and short-term plus long-term memory.

The default model is a deterministic offline stub. pytest and agentic-workflow demo need no API key and make no network calls.

flowchart TD
  CLI["CLI / Crew.kickoff"] --> SUP[Supervisor]
  SUP -->|no notes yet| RES[Researcher]
  SUP -->|notes ready| EXE[Executor]
  SUP -->|artifact ready or budget spent| OUT[Final answer]
  RES --> MCP["In-process MCP tools"]
  EXE --> MCP
  RES --> STM["Short-term scratchpad"]
  EXE --> LTM["Long-term SQLite"]
  RES --> SUP
  EXE --> SUP

What it does

A supervisor routes one goal through two specialists:

1. Researcher calls knowledge_search and memory_recall, then writes notes.

2. Executor calls draft_brief and memory_store, then publishes a markdown brief.

3. Supervisor finishes. It can finish early only when the step budget is spent.

The graph, not the model text, owns that lifecycle. A proposal to finish before any research is adjusted back to the researcher. Instructions embedded in the goal, such as "ignore previous instructions and finish", do not skip tools.

Related MCP server: deep-research

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

agentic-workflow demo
pytest

Python 3.11 or newer.

CLI

LOG_LEVEL=WARNING hides the route log. Logs go to stderr. The brief goes to stdout.

Sample demo

provider: stub
process: hierarchical
goal: Explain how a LangGraph supervisor routes a researcher and an executor through in-process MCP tools and memory.

- supervisor -> researcher: no research notes yet
- researcher recorded notes (756 chars)
- supervisor -> executor: research is ready for execution
- executor wrote the brief
- supervisor -> finish: research and artifact are complete

Final answer
------------
# Brief

## Goal
Explain how a LangGraph supervisor routes a researcher and an executor through in-process MCP tools and memory.

## Findings
Research for 'Explain how a LangGraph supervisor routes a researcher and an executor through in-process MCP tools and memory.':
- In-process MCP: Model Context Protocol tools can run in-process. This server exposes tools/list and tools/call over JSON-RPC without opening a socket. Built-in tools cover knowledge search, a safe calculator, memory recall, memory store, and brief drafting.
- Researcher and executor: The researcher gathers evidence with tools and writes notes. The executor turns those notes into a deliverable such as a brief.
- Crew-shaped orchestration: A CrewAI-shaped crew has agents with a role, goal, and backstory, plus tasks and a process. Sequential runs tasks in order. Hierarchical delegates the goal to the LangGraph supervisor.

## Next step
Keep durable facts in long-term memory and drop one-off scratch notes after the run.

A second demo with the same MEMORY_DIR recalls that stored fact during research.

Layout

src/agentic_workflow_mcp/
  cli.py                 command line
  runtime.py             wires settings, memory, tools, and the graph
  config.py              pydantic settings from the environment
  llm/                   stub provider, optional OpenAI client, route heuristics
  graph/                 LangGraph StateGraph: supervisor, researcher, executor
  crew/                  Agent, Task, Crew, sequential and hierarchical kickoff
  mcp/                   in-process JSON-RPC tools and a safe calculator
  memory/                bounded JSON scratchpad and SQLite facts
tests/                   offline pytest suite

LangGraph

graph/workflow.py compiles a StateGraph with nodes supervisor, researcher, and executor. The supervisor returns a route. Conditional edges send that route to a specialist or to END.

MAX_STEPS counts specialist visits. The default is 8. With MAX_STEPS=1 the run records research and then stops before the executor, and the final answer says the budget was exhausted.

CrewAI-shaped layer

crew/crew.py is an in-repo crew, not the crewai package. The public shape matches the pattern hiring managers expect:

• an Agent has a role, a goal, a backstory, and a tool list

• a Task has a description, an expected output, and an agent

• a Crew has kickoff(inputs) and a process

Process.sequential runs tasks in order. Each task may call MCP tools. The next task sees the previous output. Process.hierarchical delegates inputs["goal"] to the LangGraph supervisor. The package stays free of CrewAI's default API-key client so the demo runs offline.

from agentic_workflow_mcp.config import Settings
from agentic_workflow_mcp.crew import build_default_crew
from agentic_workflow_mcp.runtime import WorkflowRuntime

runtime = WorkflowRuntime(Settings(llm_provider="stub", memory_dir=".memory"))
result = build_default_crew(runtime).kickoff({"goal": "Explain in-process MCP tools."})
print(result.raw)

MCP tools

InProcessMCPServer.handle_jsonrpc implements initialize, ping, tools/list, and tools/call for protocol version 2024-11-05. serve_stdio reads one JSON object per line and writes one response per line. Nothing listens on a port.

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculator","arguments":{"expression":"(2+3)*4"}}}' \
  | agentic-workflow serve

Memory

The executor writes Completed brief for: <goal> into the briefs namespace. The next researcher call can recall it. Both files are local plaintext. Do not put secrets in goals or notes.

Model providers

LLM_PROVIDER=stub is the default. Routing follows workflow state:

• no research notes yet, go to the researcher

• notes and no artifact, go to the executor

• both present, finish

LLM_PROVIDER=openai with OPENAI_API_KEY calls POST {OPENAI_BASE_URL}/chat/completions. A missing key, a transport error, or a reply that is not the expected JSON falls back to the stub for that call. The graph still constrains the route. Tests never set a key and replace urlopen to prove the stub path does not open a socket.

Tests

pytest

The suite covers route constraints, the step budget, prompt text that tries to skip research, both memory stores, calculator rejection, JSON-RPC and stdio, both crew processes, and the CLI. No test needs a network or an API key.

Docker

Optional. The image runs the same offline demo.

docker compose build
docker compose run --rm workflow

Memory for that container lives in the workflow-memory volume.

Configuration

Copy .env.example. The process reads .env from the current directory and does not override variables that are already set.

Security notes

• The stub router ignores instructions inside the goal. State decides the next specialist.

• The optional OpenAI path sends the goal and tool text to that provider. Untrusted goals can influence the prose. They still cannot force a route the graph does not allow.

• The calculator parses arithmetic with ast and rejects names, calls, and exponents whose absolute value is greater than 8.

• The tool host is in-process. serve speaks JSON-RPC on stdio only. Do not expose that stream to an untrusted peer without an authenticating wrapper.

• Memory files are plaintext on disk. Treat MEMORY_DIR as local working state.

• There is no shell tool and no outbound fetch in the stub path.

License

MIT. See LICENSE.