How skyworkai/deepresearchagent works
1. What this repository is
- A Python runtime for “self-evolving” LLM agent systems.
- The core idea is to treat prompts, agents, tools, environments, and memory as composable, versioned resources that can be observed and improved over time.
2. Top-level architecture
- The repository is organized around a small set of runtime primitives in src/ and a large config layer in configs/.
- examples/ contains runnable entrypoints that wire these primitives together for specific demos, benchmarks, and domain tasks.
- tests/ mirrors the same surfaces and acts like an executable architecture spec for the system.
3. Composition and configuration boundary
- src/config/ and configs/ are the main assembly layer.
- Configs define how to combine a model backend, agent policy, tools, environment, memory system, and optimizer into a runnable workflow.
- This repo uses a strongly configuration-driven style rather than hard-coded application wiring.
4. Agent runtime
- src/agent/ contains the decision-making layer: simple chat, tool-calling, planning, debate, mobile, browser/operator, ESG, and trading agents.
- Agents are the orchestration boundary between the LLM and the rest of the system.
- They choose actions, invoke tools, consume environment feedback, and may hand off to optimizers or memory.
5. Tool layer
- src/tool/ exposes capabilities to agents.
- It includes default utilities like bash, file editing/reading, Python execution, web search/fetch, markdown conversion, and LeetCode helpers.
- There are also workflow tools for research, reporting, todo generation, browser operations, and skill generation.
- This is the main “action surface” an agent uses to affect the outside world.
6. Environment layer
- src/environment/ is the stateful execution boundary.
- It includes browser, mobile, filesystem, GitHub, database, FAISS, Alpaca, Binance, Hyperliquid, quick backtest, signal research, and QLib-related environments.
- Many environments have subpackages like alpacaentry, binanceentry, and browser/ that implement service, producer/consumer, and event handling internals.
- Environments encapsulate external systems and expose structured state, actions, and feedback.
7. Memory and long-lived state
- src/memory/ stores session-level and long-term artifacts, including general memory and trading-specific memory systems.
- Memory is where summaries, insights, records, and optimization traces accumulate across steps or runs.
- This is one of the key “evolution” boundaries: the system can remember what happened and reuse it later.
8. Optimization / self-improvement loop
- src/optimizer/ contains the improvement algorithms: reflection, GRPO, Reinforce++, and a larger TextGrad-based optimizer stack.
- These optimizers transform feedback into updated prompts, variables, or solution artifacts.
- They are the “Optimize” phase in the repo’s Act → Observe → Optimize → Remember loop.
9. Model/provider abstraction
- src/model/ centralizes LLM access and backend-specific serializers/clients.
- Provider support includes OpenAI, Anthropic, Google, and OpenRouter.
- This layer isolates the agent/runtime from vendor-specific APIs and response formats.
10. Prompt management and versioned templates
- src/prompt/ contains prompt templates and a prompt server/manager.
- Templates are specialized by agent type: trading, debate, planning, mobile, browser, tool-calling, optimization, and chat.
- This layer is important because prompts are treated as first-class resources rather than ad hoc strings.
11. Tracing, versioning, and runtime services
- src/tracer/ records trajectories and execution artifacts.
- src/version/ manages version metadata for evolving resources.
- src/interaction/, src/message/, src/session/, and src/task/ provide supporting types and event/message boundaries for runtime coordination.
- Together these modules make the system inspectable and auditable.
12. Domain-specific data and evaluation pipelines
- src/benchmark/, src/data/, src/download/, src/process/, src/metric/, and src/indicator/ support datasets, downloaders, preprocessing, scoring, and evaluation.
- The repo covers math/code benchmarks, ESG, financial time series, and trading/backtesting workflows.
- This makes the architecture not just an inference system, but also a research/evaluation platform.
13. Specialized external integration: LightRAG / ESG tooling
- src/tool/esg_tools/lightrag/ vendors a substantial retrieval/graph/RAG subsystem with its own API, web UI assets, LLM backends, and graph/vector store adapters.
- This is effectively a nested platform inside the repo, used for ESG-oriented retrieval and graph reasoning.
- If drawing architecture, treat it as a separate integrated service boundary rather than a small utility.
14. Execution surfaces
- examples/ provides the main runnable flows for agents, downloads, benchmarks, backtests, debates, and process pipelines.
- src/*/server.py modules indicate some components can run as services rather than only as local libraries.
- tests/ includes many end-to-end scenarios, confirming that the repo’s architecture is meant to be assembled and exercised in multiple modes.
15. Operational/tooling boundaries
- environment.yml, requirements.txt, .env.template, and GitHub Actions deployment config define the operational footprint.
- libs/ contains vendored or embedded dependencies.
- The repo is primarily a Python research/runtime system with optional UI/server components and external API integrations, not a single monolithic app.
Main entry points: agent Agents · configs Configs · src Services · tests Tests
Components 21
Composition
Configuration and assembly layer
- Configs · Repository-wide configuration layer that wires models, agents, tools, environments, memory, and optimizers.
configs - Runtime Config · Core configuration helpers and shared config structures.
src/config
Runtime
Core agent/runtime primitives
Action & State
Tools, environments, memory, and external effects
- Tools · Default, workflow, MCP, and domain tools exposed to agents.
src/tool - Environments · Stateful external-system environments for browsers, mobile, trading, filesystem, databases, and research.
src/environment - Memory · Session and long-term memory systems for general, trading, and optimizer artifacts.
src/memory
Learning
Optimization, prompts, tracing, and versions
- Prompts · Prompt templates and prompt server/manager for versioned agent prompts.
src/prompt - Optimizers · Reflection, GRPO, Reinforce++, and TextGrad-based optimization stacks.
src/optimizer - Tracing · Trajectory and execution artifact recording for observability.
src/tracer - Versioning · Version metadata for evolving prompts, agents, and other resources.
src/version - Runtime Types · Messages, interactions, sessions, and task types that connect runtime components.
src/interaction - Services · Server modules and runtime service entrypoints across major subsystems.
src
Data & Eval
Benchmarks, datasets, download, processing, metrics
- Benchmarks · Benchmark loaders, contexts, utilities, and server support for math/code evaluation.
src/benchmark - Data · Dataset loaders, collators, scalers, and task-specific data structures.
src/data - Download · Data acquisition adapters for market and benchmark sources.
src/download - Process · Data processing and scoring pipelines for market and benchmark workflows.
src/process - Metrics · Evaluation metrics for classification, ranking, and trading performance.
src/metric
Execution
Runnable demos and tests
LightRAG
Nested ESG retrieval and graph subsystem
- LightRAG · Integrated ESG retrieval, knowledge graph, vector store, API, and web UI subsystem.
src/tool/esg_tools/lightrag
Connections 35
- Configs → Runtime Config: assembles · Configuration definitions are normalized through shared config helpers.
- Configs → Agents: builds · Configs instantiate agent policies and runtime wiring.
- Configs → Tools: binds · Configs select the tool surface for each agent/workflow.
- Configs → Environments: binds · Configs select the environment boundary for each workflow.
- Configs → Memory: binds · Configs choose session and long-term memory systems.
- Configs → Optimizers: binds · Configs attach optimization loops to agent workflows.
- Agents → Models: queries · Agents rely on provider abstraction for LLM calls.
- Agents → Prompts: uses · Agents consume versioned prompt templates.
- Agents → Tools: invokes · Agents execute tools to act on the world.
- Agents → Environments: observes · Agents receive structured environment state and feedback.
- Agents → Memory: reads/writes · Agents store and retrieve summaries and artifacts.
- Optimizers → Prompts: updates · Optimizers refine prompts and related variables.
- Optimizers → Memory: stores · Optimization traces and lessons accumulate in memory.
- Tracing → Agents: records · Tracing captures agent trajectories and execution artifacts.
- Versioning → Prompts: versions · Prompt resources are versioned as first-class artifacts.
- Runtime Types → Agents: coordinates · Messages, sessions, and tasks structure agent execution.
- Benchmarks → Data: loads · Benchmarks consume datasets and task examples.
- Download → Data: feeds · Download adapters populate datasets.
- Process → Data: transforms · Processing pipelines prepare and score data.
- Metrics → Benchmarks: scores · Metrics evaluate benchmark and trading outputs.
- Examples → Configs: runs · Examples are the main executable entrypoints for configured workflows.
- Examples → Agents: demonstrates · Examples exercise the agent runtime in concrete scenarios.
- Examples → Benchmarks: executes · Some examples run benchmark and evaluation flows.
- Examples → Process: executes · Some examples run ingestion and processing pipelines.
- Tests → Agents: verifies · Tests cover agent behavior and integrations.
- Tests → Environments: verifies · Tests exercise environment adapters and services.
- Tests → Models: verifies · Tests cover provider integrations and serialization.
- Tests → Prompts: verifies · Tests cover prompt management and template selection.
- Tests → LightRAG: verifies · Tests touch the integrated LightRAG/ESG subsystem where relevant.
- LightRAG → Tools: exposed via · LightRAG is surfaced as an ESG-oriented tool subsystem.
- Services → Agents: serves · Some components expose server entrypoints for agents.
- Services → Environments: serves · Some environments run as services.
- Services → Memory: serves · Memory has service entrypoints for shared access.
- Services → Benchmarks: serves · Benchmarks include server surfaces.
- Services → Prompts: serves · Prompt resources can be managed through a server.