Build and run the genai-graph Document Graph deep agent — genai_graph/agent/docgraph_agent.py (create_docgraph_agent, prepare_docgraph_agent, run_docgraph_agent, resolve_db_path, build_docgraph_system_prompt), the colocated runtime skills under genai_graph/agent/skills, the cli docgraph agent command, the deepseek_v4flash@openrouter LLM registry entry, and the docgraph profile. Use when editing the agent module, its runtime skills, the agent CLI, or wiring a downstream project (e.g. rfq_prici...
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Kg Docgraph Agent?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/tclatos-kg-docgraph-agent)
---
name: kg-docgraph-agent
description: Build and run the genai-graph Document Graph deep agent — genai_graph/agent/docgraph_agent.py (create_docgraph_agent, prepare_docgraph_agent, run_docgraph_agent, resolve_db_path, build_docgraph_system_prompt), the colocated runtime skills under genai_graph/agent/skills, the cli docgraph agent command, the deepseek_v4flash@openrouter LLM registry entry, and the docgraph profile. Use when editing the agent module, its runtime skills, the agent CLI, or wiring a downstream project (e.g. rfq_pricing) to extract information from a document folder.
---
# Document Graph Deep Agent
## Read First
- `genai_graph/agent/docgraph_agent.py` — `create_docgraph_agent`, `prepare_docgraph_profile`, `run_docgraph_agent`, `resolve_db_path`, `build_docgraph_system_prompt`
- `genai_graph/agent/skills/navigate-document-graph/SKILL.md` — runtime skill: the vectorless agentic-RAG loop
- `genai_graph/agent/skills/document-graph-tools/SKILL.md` — runtime skill: tool + schema reference
- `genai_graph/core/commands_docgraph.py` — `cli docgraph agent` subcommand
- `config/agents/docgraph.yaml` — unified `agents:` profile (`docgraph`, type: deep)
- `config/providers/llm.yaml` — `deepseek_v4flash` → `deepseek/deepseek-v4-flash` on openrouter
- `genai_graph/kg/query/document_graph_tools.py` — the navigation tools the agent calls
## What it is
A genai-tk `type: deep` agent (DeepAgents SDK) that answers questions by
**navigating** the Ladybug Document Graph with read-only tools — no embeddings,
no chunking. The agent orients with `get_folder_toc`, gets a document's section
map with `get_document_toc`, reads only the relevant sections with
`get_section_content`, and keyword-searches with `search_sections`.
The navigation tools and target folder are **injected at runtime** by
`create_docgraph_agent` (via the harness `extra_tools`) so `--db` / `--folder` /
`--llm` overrides work without editing the profile YAML.
## Skills
Runtime skills ship colocated with the agent under `genai_graph/agent/skills/`:
- `navigate-document-graph` — the navigation loop and grounding/citation rules.
- `document-graph-tools` — exact tool arguments, return shapes, and the
Folder → Document → MarkdownSection schema.
They are resolved from the **package location** (`Path(__file__).parent/"skills"`),
so they load whether the agent is launched from genai-graph or a downstream
project. `prepare_docgraph_profile` sets a `FilesystemBackend` rooted at the
**common ancestor** of all skill directories (package skills + any caller/project
skills) so DeepAgents' `SkillsMiddleware` can read them under `virtual_mode=True`.
## Public API
```python
from genai_graph.agent import (
create_docgraph_agent, # profile -> LangChainHarness (tools + skills + folder injected)
prepare_docgraph_profile, # mutate profile in place (system prompt, skills, backend)
run_docgraph_agent, # async: stream one turn, return assistant text
resolve_db_path, # db_path or graph_db.default
create_document_graph_tools_from_config,
build_docgraph_system_prompt,
DEFAULT_LLM, # "deepseek_v4flash@openrouter"
DEFAULT_PROFILE, # "docgraph"
)
```
`create_docgraph_agent(profile, *, llm=None, db_path=None, folder_id=None,
extra_skill_dirs=None)` → `LangChainHarness`. The harness lazily compiles the
deep agent on first use. Use `run_docgraph_agent(harness, query)` to stream a
one-shot turn, or `genai_tk.agents.harness.chat_repl.run_chat_repl(harness)` for
an interactive REPL.
## CLI
```bash
cli docgraph agent "What IT services is Alko requesting?" --folder <folder-id>
cli docgraph agent --chat --folder <folder-id>
cli docgraph agent "Summarize the SLAs" --llm deepseek_v4flash@openrouter --db ./data/kg/tree.db
cli docgraph agent "..." --profile docgraph --skill-dir ./extra-skills --recursion-limit 160
```
## Wiring a downstream project (e.g. rfq_pricing)
1. Add `deepseek_v4flash` to the project's `config/providers/llm.yaml` (openrouter
slug `deepseek/deepseek-v4-flash`). Reference it as `deepseek_v4flash@openrouter`
(the bare id fuzzy-resolves to azure).
2. Add a unified `agents:` profile (`type: deep`) in `config/agents/<name>.yaml`
with the use-case `system_prompt` and `skill_directories` pointing at the
project's use-case skills (e.g. `${paths.project}/skills/custom`).
3. In a CLI command, call `create_docgraph_agent(profile, llm=..., db_path=...,
folder_id=..., extra_skill_dirs=[...])` then `run_docgraph_agent`. The generic
`genai_graph/agent/skills` are injected automatically; pass the project's
use-case skills via `extra_skill_dirs` or list them in the profile.
4. Install the `harnessing` extra (`uv sync --extra harnessing`) — `deepagents` is
required for `type: deep` agents.
5. Declare **every** model the profile references explicitly in
`config/providers/llm.yaml` — never rely on models.dev fuzzy resolution
(the cache is unavailable offline, and fuzzy matches can pick the wrong
provider or variant).
6. Verify every middleware `class:` path against the actual module layout
(`genai_tk.agents.langchain.middleware.*`,
`genai_graph.agent.middleware.*`) instead of copying another project's
`agents.yaml` — a stale path (e.g. officeqa's old
`genai_graph.agent.middleware.wrap_up.WrapUpMiddleware`) fails only at
agent build time. `cli info doctor` checks both this and the llm.yaml
entries.
## Change Workflow
1. Navigation-tool changes live in `document_graph_tools.py` (keep them
schema-tolerant); the agent calls them by name.
2. Navigation-loop guidance changes go in the `navigate-document-graph` skill.
3. Profile/LLM changes: `config/agents/docgraph.yaml` and `config/providers/llm.yaml`.
4. Keep `prepare_docgraph_profile`'s common-ancestor backend-root logic in sync
with DeepAgents' `FilesystemBackend` virtual-mode path checks.
## Commands
```bash
uv run cli docgraph agent "..." --folder <folder-id>
uv run ruff check genai_graph/agent genai_graph/core/commands_docgraph.py
uv run just test
```
## Avoid
- Do not put the runtime skills under `skills/genai-graph/` — that tree holds
**developer** skills (for editing the codebase). Runtime skills belong in
`genai_graph/agent/skills/` so they ship with the package.
- Do not reference the LLM as a bare `deepseek_v4flash` in profiles — use the
explicit `deepseek_v4flash@openrouter` id (the bare id auto-resolves to azure).
- Do not inject the navigation tools via the profile `tools:` list — they depend
on `--db`, so inject them at runtime via `create_docgraph_agent`/`extra_tools`.
- Do not add embeddings/Chunk nodes to support the agent — it is deliberately
vectorless.
## Complements
- `kg-document-graph` — the Document Graph schema, factories, and navigation tools.
- `kg-query` — the broader Cypher/text-to-Cypher query story.
- `genai-tk/agent-profiles` — the unified `agents:` profile format and `type: deep`.