feat: enhance adapter functionality with LangGraph and DeepAgents support, update documentation, and improve example scripts

Author: krishvsoni

CONTRIBUTING.md

@@ -133,6 +133,12 @@ Add your adapter to the switch statement that dispatches on `-a <adapter>`.
 
 If your framework has a config file format, add an exporter in `commands/export.ts` or `src/adapters/`.
 
+If your example directory commits an `expected_output.py` (or similar) snapshot, regenerate it whenever you change the adapter so it does not drift:
+
+```bash
+gapman export --dir examples/<name> --format <name> --output examples/<name>/expected_output.py
+```
+
 ### 4. Document what's lossy
 
 Every adapter loses something — that's expected. Please document it clearly:

examples/deepagents/README.md

@@ -4,7 +4,7 @@ A research agent with a fact-checker sub-agent, demonstrating the DeepAgents ada
 
 - `agent.yaml` — manifest (model, skills, tools, sub-agent declaration)
 - `SOUL.md` — agent identity, embedded in the generated `system_prompt`
-- `skills/web-research/`, `skills/summarize/` — passed via `skills=["./skills"]`; DeepAgents loads each `SKILL.md` natively
+- `skills/web-research/`, `skills/summarize/` — passed via a `skills=` path resolved next to the generated module (`Path(__file__).parent / "skills"`), so discovery works from any working directory; DeepAgents loads each `SKILL.md` natively
 - `tools/web-search.yaml` — emitted as a `@tool` function bound into `tools=[...]`
 - `agents/fact-checker/` — emitted as a `SubAgent` dict in `subagents=[...]`
 - `expected_output.py` — the Python module the adapter produces
@@ -27,4 +27,10 @@ pip install deepagents langchain-anthropic
 python examples/deepagents/expected_output.py
 ```
 
+Or let gitagent generate and run it for you (pass an initial message with `-p`, read from `GITAGENT_PROMPT`):
+
+```bash
+gapman run --dir examples/deepagents --adapter deepagents -p "Who won the 2022 World Cup?"
+```
+
 The generated file leaves tool implementations as `NotImplementedError` stubs — replace them with your own logic before invoking.

examples/deepagents/expected_output.py

@@ -7,6 +7,7 @@
 
 from deepagents import create_deep_agent
 from langchain_core.tools import tool
+from pathlib import Path
 
 # Agent metadata
 AGENT_NAME = "research-assistant"
@@ -43,9 +44,8 @@ def web_search(query: str) -> str:
 TOOLS = [web_search]
 
 # Skills (skills/<name>/SKILL.md — DeepAgents loads these natively)
-# Pointing skills= at the directory lets DeepAgents discover every SKILL.md
-# without us having to inline the skill content into SYSTEM_PROMPT.
-SKILLS = ["./skills"]
+# Resolved relative to this file so discovery works from any working directory.
+SKILLS = [str(Path(__file__).resolve().parent / "skills")]
 
 # For reference, the skills available in this agent:
 #   - summarize: Condense the gathered sources into a faithful, cited summary
@@ -78,6 +78,8 @@ def web_search(query: str) -> str:
 )
 
 if __name__ == "__main__":
-    result = agent.invoke({"messages": [{"role": "user", "content": "Hello"}]})
+    import os
+    user_input = os.environ.get("GITAGENT_PROMPT", "Hello")
+    result = agent.invoke({"messages": [{"role": "user", "content": user_input}]})
     for message in result["messages"]:
         print(message)

examples/langgraph/README.md

@@ -23,4 +23,10 @@ pip install "langgraph>=0.2" "langchain>=0.3" "langchain-core>=0.3" langchain-an
 python examples/langgraph/expected_output.py
 ```
 
+Or let gitagent generate and run it for you (pass an initial message with `-p`, read from `GITAGENT_PROMPT`):
+
+```bash
+gapman run --dir examples/langgraph --adapter langgraph -p "Summarize the latest on RISC-V adoption"
+```
+
 The generated file leaves tool implementations as `NotImplementedError` stubs — replace them with your own logic before invoking.

examples/langgraph/expected_output.py

@@ -101,8 +101,10 @@ def skill_web_research(state: AgentState) -> dict:
 app = graph.compile()
 
 if __name__ == "__main__":
+    import os
+    user_input = os.environ.get("GITAGENT_PROMPT", "Hello")
     result = app.invoke(
-        {"messages": [HumanMessage(content="Hello")]},
+        {"messages": [HumanMessage(content=user_input)]},
         config={"recursion_limit": RECURSION_LIMIT},
     )
     for message in result["messages"]:

src/adapters/deepagents.test.ts

@@ -155,16 +155,16 @@ describe('exportToDeepAgents', () => {
     assert.match(code, /TOOLS = \[web_search\]/);
   });
 
-  test('skills/ becomes skills=SKILLS pointing at "./skills"', () => {
+  test('skills/ becomes skills=SKILLS resolved relative to the module', () => {
     const dir = makeAgentDir({
       skills: [
         { name: 'research', description: 'Research a topic', instructions: 'Cite sources.' },
       ],
     });
     const { code } = exportToDeepAgents(dir);
-    assert.match(code, /SKILLS = \["\.\/skills"\]/);
+    assert.match(code, /from pathlib import Path/);
+    assert.match(code, /SKILLS = \[str\(Path\(__file__\)\.resolve\(\)\.parent \/ "skills"\)\]/);
     assert.match(code, /skills=SKILLS,/);
-    // The skill metadata is enumerated as a reference comment.
     assert.match(code, /#\s+- research:/);
   });
 

src/adapters/deepagents.ts

@@ -178,6 +178,7 @@ function renderPython(ctx: RenderContext): string {
   const { manifest, systemPrompt, skills, tools, preToolUseScripts, subAgents } = ctx;
   const lines: string[] = [];
   const model = manifest.model?.preferred ?? 'anthropic:claude-sonnet-4-5';
+  const needsPath = skills.length > 0 || subAgents.some(s => s.hasSkills);
 
   // Header
   lines.push('"""');
@@ -191,6 +192,7 @@ function renderPython(ctx: RenderContext): string {
   lines.push('');
   lines.push('from deepagents import create_deep_agent');
   lines.push('from langchain_core.tools import tool');
+  if (needsPath) lines.push('from pathlib import Path');
   lines.push('');
 
   // Agent metadata
@@ -247,9 +249,8 @@ function renderPython(ctx: RenderContext): string {
   // Skills — DeepAgents loads SKILL.md natively from directory paths
   lines.push('# Skills (skills/<name>/SKILL.md — DeepAgents loads these natively)');
   if (skills.length > 0) {
-    lines.push('# Pointing skills= at the directory lets DeepAgents discover every SKILL.md');
-    lines.push('# without us having to inline the skill content into SYSTEM_PROMPT.');
-    lines.push('SKILLS = ["./skills"]');
+    lines.push('# Resolved relative to this file so discovery works from any working directory.');
+    lines.push('SKILLS = [str(Path(__file__).resolve().parent / "skills")]');
     lines.push('');
     lines.push('# For reference, the skills available in this agent:');
     for (const skill of skills) {
@@ -271,7 +272,7 @@ function renderPython(ctx: RenderContext): string {
       lines.push(`    "system_prompt": ${pyTripleStr(sub.systemPrompt)},`);
       lines.push('    "tools": TOOLS,');
       if (sub.hasSkills) {
-        lines.push(`    "skills": [${pyStr(`./agents/${sub.name}/skills`)}],`);
+        lines.push(`    "skills": [str(Path(__file__).resolve().parent / "agents" / ${pyStr(sub.name)} / "skills")],`);
       }
       lines.push('}');
       lines.push('');
@@ -299,7 +300,9 @@ function renderPython(ctx: RenderContext): string {
 
   // CLI entry point
   lines.push('if __name__ == "__main__":');
-  lines.push('    result = agent.invoke({"messages": [{"role": "user", "content": "Hello"}]})');
+  lines.push('    import os');
+  lines.push('    user_input = os.environ.get("GITAGENT_PROMPT", "Hello")');
+  lines.push('    result = agent.invoke({"messages": [{"role": "user", "content": user_input}]})');
   lines.push('    for message in result["messages"]:');
   lines.push('        print(message)');
   lines.push('');

src/adapters/langgraph.ts

@@ -56,6 +56,13 @@ export function exportToLangGraph(dir: string): LangGraphExport {
   const preToolUseScripts = collectPreToolUseHooks(agentDir);
   const subAgents = collectSubAgents(agentDir);
 
+  const unreferencedSkills = findUnreferencedSkills(skills, flows);
+  for (const name of unreferencedSkills) {
+    console.warn(
+      `gitagent: skill "${name}" is declared but no skillflow step references it; it will not be reachable in the compiled graph.`,
+    );
+  }
+
   const code = renderPython({
     manifest,
     systemPrompt,
@@ -64,11 +71,23 @@ export function exportToLangGraph(dir: string): LangGraphExport {
     flows,
     preToolUseScripts,
     subAgents,
+    unreferencedSkills,
   });
 
   return { code };
 }
 
+function findUnreferencedSkills(skills: ParsedSkill[], flows: Skillflow[]): string[] {
+  if (flows.length === 0) return [];
+  const referenced = new Set<string>();
+  for (const flow of flows) {
+    for (const step of flow.steps) {
+      if (step.skill) referenced.add(step.skill);
+    }
+  }
+  return skills.map(s => s.frontmatter.name).filter(name => !referenced.has(name));
+}
+
 export function exportToLangGraphString(dir: string): string {
   return exportToLangGraph(dir).code;
 }
@@ -212,10 +231,11 @@ interface RenderContext {
   flows: Skillflow[];
   preToolUseScripts: string[];
   subAgents: string[];
+  unreferencedSkills: string[];
 }
 
 function renderPython(ctx: RenderContext): string {
-  const { manifest, systemPrompt, skills, tools, flows, preToolUseScripts, subAgents } = ctx;
+  const { manifest, systemPrompt, skills, tools, flows, preToolUseScripts, subAgents, unreferencedSkills } = ctx;
 
   const lines: string[] = [];
   const recursionLimit = manifest.runtime?.max_turns ?? 25;
@@ -345,6 +365,14 @@ function renderPython(ctx: RenderContext): string {
     }
   }
 
+  if (unreferencedSkills.length > 0) {
+    lines.push('# Declared but unreferenced by any skillflow — defined above, never wired below:');
+    for (const name of unreferencedSkills) {
+      lines.push(`#   - ${escapeForComment(name)}`);
+    }
+    lines.push('');
+  }
+
   // Sub-agent stubs (nested compiled StateGraphs)
   if (subAgents.length > 0) {
     lines.push('# Sub-agents (agents/<name>/) — nested compiled StateGraphs');
@@ -474,8 +502,10 @@ function renderPython(ctx: RenderContext): string {
   lines.push('app = graph.compile()');
   lines.push('');
   lines.push('if __name__ == "__main__":');
+  lines.push('    import os');
+  lines.push('    user_input = os.environ.get("GITAGENT_PROMPT", "Hello")');
   lines.push('    result = app.invoke(');
-  lines.push('        {"messages": [HumanMessage(content="Hello")]},');
+  lines.push('        {"messages": [HumanMessage(content=user_input)]},');
   lines.push('        config={"recursion_limit": RECURSION_LIMIT},');
   lines.push('    )');
   lines.push('    for message in result["messages"]:');

src/commands/run.ts

@@ -15,6 +15,8 @@ import { runWithGit } from '../runners/git.js';
 import { runWithOpenCode } from '../runners/opencode.js';
 import { runWithGemini } from '../runners/gemini.js';
 import { runWithGitclaw } from '../runners/gitclaw.js';
+import { runWithLangGraph } from '../runners/langgraph.js';
+import { runWithDeepAgents } from '../runners/deepagents.js';
 
 interface RunOptions {
   repo?: string;
@@ -30,7 +32,7 @@ interface RunOptions {
 export const runCommand = new Command('run')
   .description('Run an agent from a git repository or local directory')
   .option('-r, --repo <url>', 'Git repository URL')
-  .option('-a, --adapter <name>', 'Adapter: claude, openai, crewai, openclaw, nanobot, lyzr, github, opencode, gemini, gitclaw, git, prompt', 'claude')
+  .option('-a, --adapter <name>', 'Adapter: claude, openai, crewai, openclaw, nanobot, lyzr, github, opencode, gemini, gitclaw, langgraph, deepagents, git, prompt', 'claude')
   .option('-b, --branch <branch>', 'Git branch/tag to clone', 'main')
   .option('--refresh', 'Force re-clone (pull latest)', false)
   .option('--no-cache', 'Clone to temp dir, delete on exit')
@@ -129,6 +131,12 @@ export const runCommand = new Command('run')
         case 'gitclaw':
           runWithGitclaw(agentDir, manifest, { prompt: options.prompt, workspace: options.workspace });
           break;
+        case 'langgraph':
+          runWithLangGraph(agentDir, manifest, { prompt: options.prompt, workspace: options.workspace });
+          break;
+        case 'deepagents':
+          runWithDeepAgents(agentDir, manifest, { prompt: options.prompt, workspace: options.workspace });
+          break;
         case 'git':
           if (!options.repo) {
             error('The git adapter requires --repo (-r)');
@@ -148,7 +156,7 @@ export const runCommand = new Command('run')
           break;
         default:
           error(`Unknown adapter: ${options.adapter}`);
-          info('Supported adapters: claude, openai, crewai, openclaw, nanobot, lyzr, github, opencode, gemini, gitclaw, git, prompt');
+          info('Supported adapters: claude, openai, crewai, openclaw, nanobot, lyzr, github, opencode, gemini, gitclaw, langgraph, deepagents, git, prompt');
           process.exit(1);
       }
     } catch (e) {

src/runners/deepagents.ts

@@ -0,0 +1,14 @@
+import { exportToDeepAgentsString } from '../adapters/deepagents.js';
+import { AgentManifest } from '../utils/loader.js';
+import { runPythonModule, type PythonRunOptions } from './python.js';
+
+const INSTALL_HINT = 'Install dependencies: pip install deepagents langchain-anthropic';
+
+export function runWithDeepAgents(
+  agentDir: string,
+  _manifest: AgentManifest,
+  options: PythonRunOptions = {},
+): void {
+  const code = exportToDeepAgentsString(agentDir);
+  runPythonModule(agentDir, code, 'deepagents', INSTALL_HINT, options);
+}