Agent Modules

This page documents the stable public design_research_agents.agent facade.

Stable public agent facade exports with lazy loading.

class design_research_agents.agent.DirectLLMCall(*, llm_client, system_prompt=None, temperature=None, max_tokens=None, provider_options=None, tracer=None)[source]

One-shot direct model call with no tool runtime.

Design choices:

  • Uses a small Workflow with three LogicSteps (prepare, call, finalize) so the trace mirrors multi-step agents.

  • Keeps defaults (system prompt, temperature, max_tokens, provider_options) on the agent, but allows per-run overrides via normalized_input.

Initialize a direct-LLM agent with optional default generation args.

Parameters:

  • llm_client – LLM client used for prompt execution.

  • system_prompt – Optional default system prompt.

  • temperature – Optional default sampling temperature.

  • max_tokens – Optional default output-token cap.

  • provider_options – Optional default backend-specific options.

  • tracer – Optional explicit tracer dependency.

Raises:

ValueError – If max token configuration is invalid.

compile(prompt, *, request_id=None, dependencies=None)[source]

Compile one direct model call into a bound workflow execution.

run(prompt, *, request_id=None, dependencies=None)[source]

One direct model call and return normalized workflow-first output.

class design_research_agents.agent.MultiStepAgent(*, mode, llm_client, tool_runtime=None, max_steps=5, stop_on_step_failure=True, controller_system_prompt=None, controller_user_prompt_template=None, continuation_system_prompt=None, continuation_user_prompt_template=None, step_user_prompt_template=None, tool_calling_system_prompt=None, tool_calling_user_prompt_template=None, alternatives_prompt_target='user', continuation_memory_tail_items=6, step_memory_tail_items=8, memory_store=None, memory_namespace='default', memory_read_top_k=4, memory_write_observations=True, max_tool_calls_per_step=5, execution_timeout_seconds=5, validate_tool_input_schema=False, normalize_generated_code_per_step=False, default_tools_per_step=None, allowed_tools=None, tracer=None)[source]

Single multi-step runtime entrypoint for direct/json/code strategies.

Initialize one mode-specific multi-step strategy.

Parameters:

  • mode – Required strategy mode (direct, json, or code).

  • llm_client – LLM client shared by all strategy modes.

  • tool_runtime – Tool runtime required for json and code modes.

  • max_steps – Maximum number of multi-step iterations.

  • stop_on_step_failure – Whether to stop loop execution on failed steps.

  • controller_system_prompt – Direct-mode controller system prompt override.

  • controller_user_prompt_template – Direct-mode controller user prompt override.

  • continuation_system_prompt – Continuation system prompt override.

  • continuation_user_prompt_template – Continuation user prompt override.

  • step_user_prompt_template – Step action user prompt override.

  • tool_calling_system_prompt – Json mode tool-calling system prompt override.

  • tool_calling_user_prompt_template – Json mode tool-calling user prompt override.

  • alternatives_prompt_target – Prompt insertion target for alternatives blocks.

  • continuation_memory_tail_items – Continuation memory tail item count.

  • step_memory_tail_items – Step memory tail item count.

  • memory_store – Optional persistent memory dependency.

  • memory_namespace – Memory namespace for read/write operations.

  • memory_read_top_k – Memory retrieval top-k.

  • memory_write_observations – Whether to persist per-step observations.

  • max_tool_calls_per_step – Code-mode per-step tool call cap.

  • execution_timeout_seconds – Code-mode sandbox timeout.

  • validate_tool_input_schema – Code-mode tool input schema validation toggle.

  • normalize_generated_code_per_step – Code-mode code normalization toggle.

  • default_tools_per_step – Code-mode default tool allowlist.

  • allowed_tools – Optional json-mode tool allowlist.

  • tracer – Optional tracer dependency.

Raises:

ValueError – Raised when mode/tool configuration is invalid.

compile(prompt, *, request_id=None, dependencies=None)[source]

Compile one run through the selected strategy mode.

run(prompt, *, request_id=None, dependencies=None)[source]

Execute one run through the selected strategy mode.

property workflow

Expose the most recently compiled workflow from the selected strategy.