design-research-agents#

A modular framework for building and studying AI agents in engineering design workflows.

What This Library Does#

design-research-agents provides reusable abstractions for agent behavior, tool use, workflow composition, and multi-step reasoning. It is built for research workflows where traceability, reproducibility, and controlled comparison matter as much as raw model capability.

Interpretable traces, explicit tool boundaries, and documented workflow contracts are core features. They make agent studies easier to reproduce, compare, and audit across experiments.

CI Coverage Examples Passing Public API In Examples Docs PyPI Version Python Versions

Highlights#

  • Two core agent entry points: DirectLLMCall and MultiStepAgent

  • Explicit multi-step modes for direct, json, and code execution

  • A study-facing execution facade in design_research_agents.study

  • Workflow primitives for model, tool, delegate, loop, and memory steps

  • Model-selection policies with local and remote catalogs

  • Tool contracts and schemas for safe, structured I/O

  • Tracing hooks and emitters for debugging, evaluation, and reproducibility

  • Workflow-native memory and reusable reasoning patterns including tree search, Ralph loops, nominal teams, debate, and RAG

  • Runnable examples for deterministic validation and experimentation

The public surface is intentionally layered: start with DirectLLMCall for one-shot execution, move to MultiStepAgent for managed loops, use Workflow when you need to author reusable graphs, reach for design_research_agents.patterns when a prebuilt orchestration strategy fits, and use runnable examples as exemplars rather than as the primary abstraction.

Typical Workflow#

  1. Start from DirectLLMCall or MultiStepAgent depending on the level of control you need.

  2. Configure runtime mode, tools, models, and any workflow or memory helpers.

  3. Run a deterministic example or local quickstart to validate the environment.

  4. Inspect traces, tool boundaries, and structured outputs for debugging and evaluation.

  5. Reuse the same runtime contracts inside broader experiments through design_research_agents.study.AgentRunRequest, design_research_agents.study.execute_agent_request(...), design_research_agents.study.normalize_agent_execution(...), and downstream analysis.

Note

New here? Start with Where To Start to choose the right layer, then use Quickstart to run the smallest end-to-end example.

Guides#

Learn the base concepts, setup flow, and execution patterns that shape a stable agent-research pipeline.

Examples#

Browse runnable examples and guided landing pages for the major public subsystems.

Reference#

Look up the stable import surface, package extras, and deeper API reference material for the runtime boundaries that matter in CI and downstream studies.

Integration With The Ecosystem#

The Design Research Collective maintains a modular ecosystem of libraries for studying human and AI design behavior.

  • design-research-agents implements AI participants, workflows, and tool-using reasoning patterns.

  • design-research-problems provides benchmark design tasks, prompts, grammars, and evaluators.

  • design-research-analysis analyzes the traces, event tables, and outcomes generated during studies.

  • design-research-experiments sits above the stack as the study-design and orchestration layer, defining hypotheses, factors, conditions, replications, and artifact flows across agents, problems, and analysis.

Together these libraries support end-to-end design research pipelines, from study design through execution and interpretation.

Ecosystem diagram showing experiments above agents, problems, and analysis.

Start Here#