Teach builder to author DeepAgents skills

agent_builder/skills/deepagents-implementation-patterns/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: deepagents-implementation-patterns
+description: Implement DeepAgents inside a2a-pack agents with real deterministic tools, project skills, custom subagents, workspace-backed files, and caller-provided ChatOpenAI models. Use when editing create_deep_agent calls or deciding what belongs in tools, skills, or subagents.
+---
+# DeepAgents Implementation Patterns
+
+DeepAgents supplies the inner agent loop. In this platform, the reliable shape
+is: caller-provided `ChatOpenAI`, A2A workspace backend, project DeepAgents
+skills, and a small number of exact tools.
+
+## Implementation Shape
+
+```python
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from langchain_core.tools import tool
+from langchain_openai import ChatOpenAI
+from deepagents import create_deep_agent
+
+RUNTIME_SKILLS_ROOT = "/outputs/research-agent/.deepagents/skills/"
+
+SYSTEM_PROMPT = """\
+You are a careful research agent. Use project skills for workflow rules and
+write durable files under /workspace/outputs/.
+"""
+
+
+def build_graph(ctx: Any) -> Any:
+    creds = ctx.llm
+    model = ChatOpenAI(
+        model=creds.model,
+        base_url=creds.base_url,
+        api_key=creds.api_key,
+        temperature=0.0,
+    )
+
+    @tool
+    def validate_citations(items_json: str) -> str:
+        """Validate that each citation has title, url, and claim fields."""
+        items = json.loads(items_json)
+        missing = [
+            i for i, item in enumerate(items)
+            if not {"title", "url", "claim"} <= set(item)
+        ]
+        return json.dumps({"ok": not missing, "missing_indexes": missing})
+
+    backend = ctx.workspace_backend()
+    skill_sources = seed_runtime_skills(backend)
+    return create_deep_agent(
+        model=model,
+        backend=backend,
+        skills=skill_sources or None,
+        tools=[validate_citations],
+        subagents=[
+            {
+                "name": "source-reviewer",
+                "description": "Reviews source quality and citation coverage.",
+                "system_prompt": (
+                    "Check whether sources support the claims. Return gaps "
+                    "and concrete fixes."
+                ),
+                "skills": skill_sources,
+            }
+        ],
+        system_prompt=SYSTEM_PROMPT,
+    )
+
+
+def seed_runtime_skills(backend: Any) -> list[str]:
+    root = Path(__file__).parent / "skills"
+    if not root.exists():
+        return []
+    uploads: list[tuple[str, bytes]] = []
+    for path in root.rglob("*"):
+        if path.is_file():
+            rel = path.relative_to(root).as_posix()
+            uploads.append((RUNTIME_SKILLS_ROOT + rel, path.read_bytes()))
+    if uploads:
+        backend.upload_files(uploads)
+        return [RUNTIME_SKILLS_ROOT]
+    return []
+```
+
+## Choose The Right Primitive
+
+Use a DeepAgents skill when the agent needs reusable judgement, process, domain
+rules, examples, or a checklist. Put it under `skills/<skill-name>/SKILL.md`.
+
+Use a subagent when a separate LLM pass can independently research, review,
+transform, or critique work. Custom subagents should receive their own `skills`
+field; do not assume they inherit every main-agent skill.
+
+Use a deterministic tool only for exact work: JSON validation, schema checks,
+filesystem transforms, API calls, calculations, sandbox commands, conversion
+commands, or database queries.
+
+Do not write tools whose body is prompt text, canned answers, or another hidden
+LLM call. That logic belongs in a DeepAgents skill or a subagent.
+
+## Skill Files
+
+Each skill directory must contain `SKILL.md` with frontmatter:
+
+```markdown
+---
+name: market-research
+description: Run market research with source review, competitor mapping, and cited synthesis. Use for market questions, competitive analysis, or customer research.
+---
+# Market Research
+
+Follow this workflow...
+```
+
+The `description` is the trigger text visible to the LLM before full skill
+loading. Keep it concrete. Put long examples or data dictionaries into
+`references/`, scripts into `scripts/`, and reusable assets into `assets/`.
+
+## Backend Rules
+
+DeepAgents' default state backend is not enough for hosted agents because file
+outputs can disappear into graph state. Always pass `backend=ctx.workspace_backend()`
+for generated agents that read or write files.
+
+Use `skills=skill_sources or None`, not an empty list, so agents without a
+`skills/` directory still build cleanly.