130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
---
|
|
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.
|