Article 3.2: A Complete Medical Use Case with YAML Scenarios, Firmware Injection, and Evolving Agents

By Matías Molinas and Ismael Faro

Introduction

In Article 3.1 (“Multi-Agent Framework with Firmware, Smart Library, and Semantic Search”), we presented a System Agent that:

1. Injects Firmware into every agent, ensuring global governance rules.
2. Uses a Smart Library for storing and retrieving existing snippets or agents.
3. Decides whether to reuse, evolve, or create new items based on semantic search.

Now, in Article 3.2, we focus on YAML-based scenarios where all domain-specific prompts, disclaimers, and instructions live in a YAML file—keeping the System Agent code generic. We also highlight how Firmware is automatically injected whenever a new agent or tool is defined, created, or evolved, ensuring system-wide governance.

Medical Example

A user (or an external system) wants an agent to:

“Perform a preliminary medical diagnosis for a patient with lupus-like symptoms and research the latest immunosuppressant treatments.”

Key Points:

1. Scenario details (domain “medical,” disclaimers, steps to evolve or reuse snippets) are in a YAML file.
2. System Agent reads that YAML and calls Firmware to ensure domain rules are included in any code generation or agent creation.
3. The final result is a Bee ReAct agent that merges a newly evolved “MedicalDiagnosisTool” with a reused “DeepResearchTool.”

1. YAML Definition Incorporating Firmware

Below is an example YAML file, medical_scenario.yaml, that defines:

• Domain: "medical."
• Global disclaimers: Pulled from the user’s scenario (not the code).
• FirmwareInjections: A placeholder to remind that “medical” domain requires additional firmware rules.
• Steps: Telling the System Agent exactly how to define, create, and execute the agent.

# medical_scenario.yaml

scenario_name: "Medical Diagnosis and Research"
domain: "medical"

disclaimers:
  - "# MEDICAL_DISCLAIMER: This output is not a substitute for professional medical advice."
  - "Always consult with qualified healthcare providers."
  - "For informational purposes only."

firmware_injections:
  # This might be just a note or reference to how the firmware’s “medical” domain is enforced:
  - "HIPAA compliance"
  - "Ethical guidelines for medical data"
  - "Include disclaimers in docstrings"

steps:
  - type: "DEFINE"
    item_type: "TOOL"
    name: "MedicalDiagnosisTool"
    from_existing_snippet: "generic_llm_classification_tool"
    evolve_changes:
      docstring_update: "Evolved tool specialized in medical diagnosis."
      disclaimers: "Always include disclaimers in docstrings and responses."
    description: "Tool that takes a patient's data and returns a preliminary diagnosis."

  - type: "DEFINE"
    item_type: "TOOL"
    name: "DeepResearchTool"
    from_existing_snippet: "deep_research_smolagent"
    reuse_as_is: true
    description: "Tool that performs advanced web/data analysis for references."

  - type: "DEFINE"
    item_type: "AGENT"
    name: "MedicalDiagnosisAndResearchAgent"
    agent_type: "BeeReActAgent"
    description: "A Bee ReAct agent that provides quick diagnosis and looks up immunosuppressant treatments."
    disclaimers_in_docstring: true
    required_tools:
      - "MedicalDiagnosisTool"
      - "DeepResearchTool"

  - type: "CREATE"
    item_type: "AGENT"
    name: "MedicalDiagnosisAndResearchAgent"

  - type: "EXECUTE"
    item_type: "AGENT"
    name: "MedicalDiagnosisAndResearchAgent"
    user_input: |
      "I have a 35-year-old patient with lupus-like symptoms.
      Please provide a diagnosis and the latest immunosuppressant research."        

Highlights

• firmware_injections: We note that “medical” domain triggers additional guidelines from the Firmware.
• DEFINE steps reference existing snippets (from_existing_snippet) to either reuse or evolve them.
• CREATE: We instantiate the new agent in the environment.
• EXECUTE: We run the agent with real user input.

2. Firmware Injection at Each Step

Our Firmware (from Article 3.1) typically includes global governance rules (ethical, security, domain placeholders). For domain “medical,” it might add lines like:

- This system is for informational purposes only and not a substitute for professional advice
- Include disclaimers in all responses
- Comply with HIPAA and medical privacy guidelines        

Whenever the System Agent does a define/evolve/create action, it merges:

• The firmware rules for the domain.
• The disclaimers from the YAML.
• The base snippet or newly generated code.

Hence, any code or agent produced must contain the disclaimers and docstrings required by both the Firmware and the YAML instructions.

3. Generic System Agent Pseudocode

Below is a simplified version of how the System Agent might interpret the YAML, calling the firmware every time it defines, creates, or evolves something:

# system_agent_firmware_injection.py (pseudocode)

import yaml
from library_manager import RecordType

class SystemAgent:
    def __init__(self, firmware, smart_library, llm):
        self.firmware = firmware           # e.g. Firmware()
        self.smart_library = smart_library # e.g. LibraryManager()
        self.llm = llm                     # LLMService or similar

    async def load_and_process_scenario(self, yaml_path: str):
        with open(yaml_path, 'r', encoding='utf-8') as f:
            scenario = yaml.safe_load(f)

        domain = scenario.get("domain", "general")
        disclaimers_list = scenario.get("disclaimers", [])
        firmware_injections = scenario.get("firmware_injections", [])

        for step in scenario["steps"]:
            step_type = step["type"].upper()

            if step_type == "DEFINE":
                await self._define_item(step, domain, disclaimers_list, firmware_injections)
            elif step_type == "CREATE":
                await self._create_item(step, domain)
            elif step_type == "EXECUTE":
                await self._execute_item(step)
            else:
                print(f"[SystemAgent] Unknown step type: {step_type}")

    async def _define_item(self, step: dict, domain: str, disclaimers_list: list[str], firmware_injections: list[str]):
        """
        Possibly evolve or reuse existing library items, but always inject the firmware rules
        for the domain. 
        """
        item_type = step["item_type"]   # e.g., "TOOL" or "AGENT"
        name = step["name"]
        # Gather relevant firmware text
        domain_firmware = self.firmware.get_firmware_prompt(domain)

        # We combine disclaimers, firmware_injections, etc. with the existing snippet or new snippet
        if "from_existing_snippet" in step:
            snippet_name = step["from_existing_snippet"]
            if step.get("reuse_as_is"):
                print(f"[DEFINE] Reusing '{snippet_name}' as '{name}' under domain '{domain}' with firmware.")
                await self._reuse_snippet(
                    snippet_name=snippet_name,
                    new_name=name,
                    item_type=item_type,
                    domain_firmware=domain_firmware,
                    disclaimers_list=disclaimers_list,
                    firmware_injections=firmware_injections
                )
            else:
                print(f"[DEFINE] Evolving '{snippet_name}' -> '{name}', injecting firmware for domain '{domain}'.")
                evolve_changes = step.get("evolve_changes", {})
                await self._evolve_snippet(
                    snippet_name=snippet_name,
                    new_name=name,
                    item_type=item_type,
                    domain_firmware=domain_firmware,
                    disclaimers_list=disclaimers_list,
                    firmware_injections=firmware_injections,
                    evolve_changes=evolve_changes
                )
        else:
            print(f"[DEFINE] Creating brand-new '{name}' with domain firmware injection.")
            # define from scratch, adding disclaimers, domain_firmware, etc.

    async def _create_item(self, step: dict, domain: str):
        """
        Instantiates the item (agent/tool), injecting domain firmware in runtime context if needed.
        """
        item_type = step["item_type"]
        name = step["name"]
        print(f"[CREATE] Instantiating {item_type} '{name}' with domain '{domain}' firmware.")

        # e.g., load the snippet from library, wrap it with firmware meta-prompt at runtime

    async def _execute_item(self, step: dict):
        """
        Runs an already created agent with user input, then updates usage metrics.
        """
        item_type = step["item_type"]
        name = step["name"]
        user_input = step["user_input"]
        print(f"[EXECUTE] Running {item_type} '{name}' with input:\n{user_input}")
        # 1. retrieve agent from memory or library
        # 2. run with user_input
        # 3. save usage stats

    # Example placeholders for reusing or evolving code:
    async def _reuse_snippet(self, snippet_name, new_name, item_type, domain_firmware, disclaimers_list, firmware_injections):
        # Reuse snippet as is, but might add disclaimers or domain_firmware references to metadata
        pass

    async def _evolve_snippet(self, snippet_name, new_name, item_type, domain_firmware, disclaimers_list, firmware_injections, evolve_changes):
        # LLM-based transformation: merges old snippet + domain_firmware + disclaimers
        pass        

Observations:

• No scenario-specific disclaimers or textual prompts are in the code. Instead, we see placeholders referencing domain_firmware, disclaimers_list, firmware_injections—all read from the YAML plus the Firmware object.
• The System Agent code remains generic: it simply merges these data sources to produce a final prompt for the LLM or to fill metadata in the Smart Library.
• At runtime (in _create_item), the firmware is also applied so that each agent has the correct meta-prompt enforcing governance.

4. End-to-End Medical Flow

1. User (or developer) places domain disclaimers, docstring instructions, and step definitions in medical_scenario.yaml.
2. System Agent calls load_and_process_scenario("medical_scenario.yaml").
3. Each step:DEFINE: Possibly evolves “generic_llm_classification_tool” → “MedicalDiagnosisTool,” reusing or injecting domain disclaimers from the firmware.DEFINE: Reuses “deep_research_smolagent” → “DeepResearchTool.”DEFINE: A new “MedicalDiagnosisAndResearchAgent” referencing these two tools.CREATE: Instantiates the agent in memory with domain firmware injection.EXECUTE: Finally runs that agent with real user input about lupus.
4. Smart Library is updated with new or evolved items, usage counts, etc., always under domain governance from the firmware.

5. Final thoughts

5.1 Key Takeaways

• Firmware Injection: The System Agent ensures that domain rules from the Firmware (e.g., medical disclaimers, HIPAA constraints) are always merged into any code or agent definition. This happens during DEFINE, CREATE, and EVOLVE steps.
• Scenario Data in YAML: All prompts, disclaimers, docstring instructions, and snippet references live in a YAML file. The System Agent code doesn’t contain scenario logic—it's purely generic.
• Medical Example: We show how to produce a Bee ReAct agent for diagnosing lupus-like symptoms and referencing immunosuppressant treatments by evolving or reusing existing library snippets.

5.2 Next Steps

5.2.1 Validation: Final LLM-Based Checks for Disclaimers and Firmware References

One critical enhancement is to validate newly created or evolved snippets before finalizing them in the Smart Library:

• Disclaimers in Docstrings: After each “DEFINE” or “EVOLVE” step, the System Agent can run a post-generation check (e.g., an additional LLM prompt) to inspect the resulting code snippet’s docstrings. The check would confirm that the snippet includes any domain-specific disclaimers (e.g., # MEDICAL_DISCLAIMER or “For informational purposes only”).
• Firmware Compliance: The System Agent can similarly verify that the snippet references the Firmware constraints, especially for high-risk domains like medical. For instance, a snippet should mention “HIPAA compliance” or “ethical constraints” if the domain is medical.
• Automated Flagging: If disclaimers or references are missing, the snippet can be flagged. The System Agent might automatically re-run an “evolve” prompt to inject the missing text or disclaimers before saving the snippet.

This validation step ensures the framework remains consistent and safe—even if the initial code generation or evolution inadvertently omits important disclaimers.

5.2.2 Human Approval: SME Review for High-Risk Domains

For high-risk domains (like medical or finance), where incorrect or incomplete disclaimers could have serious consequences:

• Mandatory SME (Subject-Matter Expert) Approval: Any newly evolved or created snippet can be put into a “pending approval” state. A domain expert (e.g., a qualified healthcare professional) then reviews the code, disclaimers, docstrings, and references.
• Approval Workflow:The System Agent completes its generation or evolution steps.The snippet enters a “draft” record in the Smart Library.A designated SME receives a notification (via email, Slack, or other channels).If the SME finds issues, they can annotate them; the snippet can be re-submitted for another iteration of disclaimers or corrections.Once approved, the snippet transitions to “active” status, ready for user queries.
• Audit Logs: Keep an audit trail of SME feedback and changes. This is especially relevant in regulated environments (healthcare, legal, financial, etc.) to prove compliance with policy or legal frameworks.

5.2.3 Tooling: Expanding the YAMLDefinitionTool for Automatic Scenario Generation

Currently, the YAMLDefinitionTool is a conceptual tool that:

• Reads the user’s request.
• Does a semantic search in the Smart Library for partial matches (e.g., existing LLM or deep research smolagents snippets).
• Produces a YAML file specifying how to define or evolve each relevant snippet, plus instructions for create and execute steps.

Future expansions might include:

• Dynamic YAML Editing: If an SME or a secondary agent determines the scenario needs additional disclaimers or disclaimers in different languages, the YAMLDefinitionTool can update the existing YAML file rather than creating a new one from scratch.
• Multi-Step Scenario Generation: For more complex use cases (e.g., “I want an agent that does data ingestion, medical triage, and advanced research”), the tool can produce multiple “DEFINE” steps—one for each partial snippet in the library—then chain them into a single scenario.
• Domain-Agnostic: The YAMLDefinitionTool itself doesn’t hardcode any single domain’s disclaimers; it references the Firmware or a domain-specific disclaimers registry. For example, the tool could retrieve disclaimers for “finance” or “insurance” just as easily as “medical,” injecting them into the newly generated YAML.
• Conversation-Driven Revisions: The System Agent might present the user or SME with a “draft” YAML plan, then revise it interactively based on feedback (e.g., “I also need disclaimers about pediatric usage in medical domain,” or “We want to add a tool that calculates dosage.”). The YAMLDefinitionTool can incorporate these modifications iteratively.

With these enhancements, scenario generation becomes much more flexible and user-friendly—the entire process (from first user request to final, domain-compliant multi-tool agent) can be orchestrated automatically, with human-in-the-loop checks for safety or compliance as needed.

About the Authors

Matías Molinas : CTO with a passion for building adaptive, real-world AI solutions.

Ismael Faro : VP and Distinguished Engineer at IBM, working in Quantum + AI.

Final Note

All code examples here are pseudocode, showing how Firmware can be injected at every step while deferring domain disclaimers and prompts to YAML. During this week, we will publish a new GitHub repository demonstrating a basic implementation of this framework, including the medical scenario and its disclaimers, multi-tool orchestration, and automatic firmware governance. Stay tuned for more on:

• Integrating domain firmware constraints with advanced AI code generation.
• Seamlessly evolving or reusing library snippets for rapid multi-agent solutions.
• Maintaining strict governance via an always-injected firmware layer.

Additional Resources & Links

• BeeAI Framework (AI agent framework in TypeScript and Python) https://github.com/i-am-bee/beeai-framework/tree/main
• BeeLabs (experimental projects like Maestro, a multi-agent platform to deploy and run AI agents) https://github.com/i-am-bee/beeai-labs/tree/main
• Smolagents Framework (a library that enables you to run powerful agents, includes an example of an agent that implements deep research) https://github.com/huggingface/smolagents/tree/main