DDAgent: Dynamic Decision Agent for Druggability Analysis

DDAgent is a lightweight, decision‑driven agent designed to automate the logical reasoning and parameter selection process in a multi‑step druggability analysis workflow.
Unlike traditional code‑generation agents, DDAgent does not write or revise code.
Instead, it observes the printed output from each step, interprets the results, and decides what to do next based on predefined biological logic and workflow rules.

DDAgent is inspired by the step‑wise execution and context‑tracking architecture of GEOAgent, but adapted for a decision‑only pipeline.

---

🔍 Key Features

✔ No code generation

DDAgent never writes Python code.
All functions required in the workflow (e.g. find_highaffres, cluster_hotspots, search_mol) already exist in utils.

✔ Output‑driven decision making

Each step prints structured information.
DDAgent reads and interprets the printed output and then:

• adjusts parameters (via LLM) when needed
• re‑runs the current step, or
• proceeds to the next step

✔ Automatic parameter tuning

• Example: If STEP3 produces no high‑affinity residue clusters, DDAgent asks the LLM to propose a new threshold and re‑runs STEP3 with the updated parameter.

✔ Step‑to‑step context tracking

DDAgent records a rich context so later steps can access all relevant history:

• step name
• printed output
• chosen parameters
• final decision

✔ Modular action‑based design

Each workflow step is implemented as an Action unit, similar to GEOAgent:

• reads the previous step's output
• makes a decision
• executes the corresponding utility function(s)
• returns control to DDAgent

This results in a clean, interpretable execution graph.

---

🧠 How DDAgent Works

1. Run an Action

Each step is defined as an Action class with an execute() method. A typical pattern:

output = find_highaffres(threshold)
agent.context.add_step("STEP3", output)

2. Interpret output

The Action inspects the text output and decides what happened. For example:

if "No high affinity clusters found" in output:
    # Ask LLM to adjust threshold instead of proceeding

3. LLM‑assisted decision

DDAgent queries the LLM to adjust parameters:

new_threshold = agent.invoke_llm_adjustment(current_threshold)

The LLM returns a suggested parameter (e.g. “lower threshold to 3.5”), which the Action then applies.

4. Re‑execute or move forward

Based on the interpreted output and LLM suggestion:

• If the step succeeds → move to the next Action
• If the step fails → re‑execute the current Action with updated parameters

---

⚙️ Architecture Overview

TaskContext

• Stores: step outputs, decisions, chosen parameters, dynamically updated state
• Used for:
  • cross‑step reasoning
  • constructing LLM prompts
  • reproducibility and debugging

Action Units

Every workflow step (e.g. STEP0–STEP8) is implemented as an Action class. Each Action:

• runs pre‑written utility functions
• parses printed output
• requests LLM help when decisions are ambiguous
• returns a signal indicating success/failure

DDAgent Controller

The controller is responsible for:

• executing Actions in order
• passing context between Actions
• routing LLM queries
• handling retries and parameter adjustments

---

📚 Summary

DDAgent is a decision‑only agent designed for scientific pipelines where:

• the core analysis code is already implemented
• what matters is interpreting outputs
• and making adaptive, biologically meaningful decisions

It provides:

• transparent step logic
• LLM‑supported reasoning
• full automation without code generation

If you need a clean, automated decision workflow for molecular simulations, druggability analysis, or other sequential scientific protocols, DDAgent is a good fit.