Deep Research Assistant¶

Tutorial นี้พาไปดู examples/deep_research/research.py — สคริปต์แบบสมบูรณ์ในตัวที่ใช้เอเจนต์ orchestrator วิจัยหัวข้อหนึ่ง รวบรวมแหล่งข้อมูลข้ามหลายรอบการเรียกใช้ tool และสร้างรายงานพร้อมอ้างอิงแหล่งที่มา สาธิตวิธีประกอบการค้นหาเว็บ, memory และการเขียนไฟล์ เข้าด้วยกันเป็นเวิร์กโฟลว์การวิจัยที่สอดคล้องกันชิ้นเดียว

สิ่งที่ต้องมีก่อน

Python 3.10 ขึ้นไป
ติดตั้ง OpenJarvis แล้ว: รัน uv sync --extra dev จาก root ของ repository
มี inference engine กำลังรันอยู่ — ไม่ว่าจะเป็น Ollama ในเครื่อง (ดูด้านล่าง) หรือ cloud API key ในไฟล์ .env ของคุณ

Quick Start¶

รันสคริปต์วิจัยจาก root ของ repository โดยส่งหัวข้อของคุณเป็น positional argument:

Terminal

python examples/deep_research/research.py "quantum computing advances 2026"

บันทึกรายงานลงไฟล์:

Terminal

python examples/deep_research/research.py "quantum computing advances 2026" \
    --output report.md

ใช้โมเดล cloud แทน engine ในเครื่อง:

Terminal

source .env  # load API keys
python examples/deep_research/research.py "climate policy trends" \
    --model gpt-4o --engine cloud --max-turns 20

ทำงานอย่างไร¶

สคริปต์สร้าง instance ของ Jarvis และมอบหมายงานวิจัยให้กับ OrchestratorAgent ที่ต่อสาย tool ไว้ 5 ตัว orchestrator จะวนผ่านรอบการเรียกใช้ tool หลายรอบ โดยตัดสินใจในแต่ละขั้นตอนว่าจะค้นหา, เก็บข้อมูล, คิด หรือสังเคราะห์

sequenceDiagram
    participant U as User
    participant J as Jarvis SDK
    participant O as OrchestratorAgent
    participant W as web_search
    participant T as think
    participant MS as memory_store
    participant MQ as memory_search
    participant F as file_write

    U->>J: research.py "quantum computing"
    J->>O: ask(prompt, agent="orchestrator", tools=[...])
    loop Up to max_turns iterations
        O->>W: search("quantum computing 2026")
        W-->>O: search results
        O->>T: think(reasoning about findings)
        T-->>O: structured thoughts
        O->>MS: store(key finding)
        MS-->>O: stored
        O->>MQ: search(earlier findings)
        MQ-->>O: related context
    end
    O->>F: file_write(report.md)
    F-->>O: saved
    O-->>J: final report with citations
    J-->>U: print report

ในแต่ละรอบ orchestrator จะตัดสินใจว่าจะเรียก tool ตัวไหน โดยอิงจากสิ่งที่เรียนรู้มาจนถึงตอนนั้น tool think ให้โมเดลให้เหตุผลได้โดยไม่มี side effect ในขณะที่ memory_store และ memory_search เป็นพื้นที่ร่างที่คงอยู่ข้ามรอบ — ทำให้สิ่งที่พบในรอบที่ 3 ยังคงถูกนำมาใช้ในการสังเคราะห์ที่รอบที่ 12 ได้

ตัวสคริปต์¶

examples/deep_research/research.py

from openjarvis import Jarvis

tools = ["web_search", "think", "file_write", "memory_store", "memory_search"]

j = Jarvis(model="qwen3:8b", engine_key="ollama")  # (1)!
try:
    response = j.ask(
        "Research the following topic in depth and produce a report:\n\nquantum computing",
        agent="orchestrator",     # (2)!
        tools=tools,              # (3)!
        system_prompt=...,        # (4)!
        max_turns=15,             # (5)!
        temperature=0.5,
    )
finally:
    j.close()

สร้าง instance ของ Jarvis ที่ชี้ไปยัง Ollama engine ในเครื่องด้วย qwen3:8b ทั้งสองพารามิเตอร์เป็นตัวเลือกเสริม — หากไม่ระบุจะใช้ค่าเริ่มต้นที่ตรวจจับอัตโนมัติจาก ~/.openjarvis/config.toml
เลือก OrchestratorAgent ซึ่งรันลูปการเรียกใช้ tool แบบหลายรอบ แทนที่จะเป็นการไปกลับเพียงครั้งเดียว
รายการ tool ถูกส่งตรงเข้าไปในเอเจนต์ tool ทั้งห้าตัวลงทะเบียนไว้ใน tool registry แล้ว ไม่ต้องตั้งค่าเพิ่มเติม
system prompt สั่งให้โมเดลอ้างอิงแหล่งที่มาและแยกแยะข้อเท็จจริงออกจากข้อกล่าวอ้างที่ยังไม่ยืนยัน
ลูปจะสิ้นสุดหลังจากผ่านไป 15 รอบการเรียกใช้ tool หรือเมื่อเอเจนต์ตัดสินใจว่ามีข้อมูลเพียงพอแล้ว

การตั้งค่า Engine¶

Ollama (ในเครื่อง)Cloud APIvLLM

เริ่ม daemon ของ Ollama และดึงโมเดลก่อนรันสคริปต์:

Terminal

ollama serve
ollama pull qwen3:8b
python examples/deep_research/research.py "your topic here"

ไม่ต้องใส่ flag ใดๆ — --engine ollama และ --model qwen3:8b คือค่าเริ่มต้นอยู่แล้ว

ตั้งค่า API key ของคุณใน .env แล้วส่ง --engine cloud พร้อม identifier ของโมเดลที่เหมาะสม:

Terminal

# .env (in the repository root, gitignored)
OPENAI_API_KEY=sk-...

source .env
python examples/deep_research/research.py "your topic" \
    --model gpt-4o --engine cloud

หากคุณกำลังรัน vLLM inference server อยู่ (เช่น บน node ที่มีหลาย GPU):

Terminal

python examples/deep_research/research.py "your topic" \
    --model meta-llama/Meta-Llama-3-8B-Instruct \
    --engine vllm

ตรวจสอบว่าได้ตั้งค่า VLLM_BASE_URL ใน .env ให้ชี้ไปยัง vLLM server ของคุณแล้ว

เอกสารอ้างอิง Configuration¶

Flag	ค่าเริ่มต้น	คำอธิบาย
`--model`	`qwen3:8b`	Identifier ของโมเดลที่ส่งไปยัง engine
`--engine`	`ollama`	Engine backend (`ollama`, `cloud`, `vllm`, `llamacpp`, `mlx`)
`--max-turns`	`15`	จำนวนรอบการวนลูปสูงสุดของ orchestrator
`--output`	(ไม่มี)	Path ของไฟล์สำหรับบันทึกรายงานสุดท้าย; หากไม่ระบุจะพิมพ์ออกทาง stdout

Configuration แบบขับเคลื่อนด้วย Recipe¶

research.toml ที่มาคู่กันใน examples/deep_research/ แสดงการตั้งค่าแบบเดียวกันในรูปแบบ declarative คุณสามารถโหลดมันเชิงโปรแกรมด้วย load_recipe() แล้วส่งผลลัพธ์ไปยัง SystemBuilder:

Using the recipe

from openjarvis.recipes import load_recipe
from openjarvis import SystemBuilder

recipe = load_recipe("examples/deep_research/research.toml")
system = SystemBuilder(**recipe.to_builder_kwargs()).build()
response = system.ask("quantum computing advances 2026")
system.close()

วิธีนี้มีประโยชน์เมื่อคุณต้องการทำ version control กับการตั้งค่าการวิจัย, แชร์กับผู้ร่วมงาน หรือป้อนเข้า jarvis eval runner สำหรับการวัดประสิทธิภาพ

การปรับแต่ง¶

สลับเอเจนต์¶

แทนที่ "orchestrator" ด้วย "native_react" สำหรับลูปแบบ Thought-Action-Observation หรือ "native_openhands" สำหรับเอเจนต์แบบ CodeAct ที่เขียนและรันโค้ดได้:

response = j.ask(prompt, agent="native_react", tools=tools)

เพิ่ม Tool เพิ่มเติม¶

เพิ่มชื่อ tool ที่ลงทะเบียนไว้เข้าไปในรายการ tools ตัวอย่างเช่น หากต้องการ query knowledge base ในเครื่องด้วย:

tools = ["web_search", "think", "file_write",
         "memory_store", "memory_search", "knowledge_graph_query"]

รัน jarvis agent info orchestrator เพื่อดูแคตตาล็อก tool ทั้งหมด

ปรับ Temperature¶

ค่าต่ำ (0.2) ให้รายงานที่เจาะจงและอิงข้อเท็จจริงมากขึ้น ค่าสูง (0.7-0.8) ส่งเสริมการสำรวจที่กว้างขึ้นและการสังเคราะห์ที่สร้างสรรค์มากขึ้น:

Terminal

python examples/deep_research/research.py "your topic" --max-turns 20

ดูเพิ่มเติม¶

Architecture: Agents — ลำดับชั้นของเอเจนต์ (BaseAgent, ToolUsingAgent, OrchestratorAgent) และกลไก accepts_tools
Architecture: Tools and Memory — tool registry, MCP adapter และ pipeline การส่งงานของ ToolExecutor
Getting Started: Configuration — วิธีตั้งค่า engine และโมเดลใน ~/.openjarvis/config.toml