Hands‑On: Build a Hybrid Agent That Uses Qiskit for Quantum Subroutines

Hook: Why hybrid agents solve the biggest barrier for quantum developers in 2026

If you're a developer or IT pro trying to move from reading papers to shipping hybrid quantum-classical work, you hit two recurring walls: the steep conceptual math of quantum algorithms and the fragmented toolchain that splits symbolic design (best handled by large language models) from numerical execution (handled by quantum SDKs and simulators). This tutorial shows a pragmatic engineering pattern: build a LangChain-style agent that delegates heavy symbolic tasks to an LLM and numerical quantum work to Qiskit (local simulator or cloud backend). The result: a repeatable, observable hybrid pipeline you can iterate on in minutes.

What you'll build (and why it matters now)

By the end of this code lab you'll have a working hybrid agent that:

• Accepts high-level task prompts (e.g., "Design a VQE ansatz for H2 and estimate the ground state energy").
• Uses an LLM to perform symbolic decomposition and generate a Qiskit circuit template.
• Executes the numerical portion on a quantum simulator (Aer) or an IBM Quantum backend, including transpilation and shot control.
• Feeds numeric results back to the LLM for interpretation and next-step suggestions.

This pattern matches 2026 trends: agentic AI is mainstream (desktop and cloud agents from major labs), teams are building smaller, nimble hybrid projects, and cloud providers expose quantum runtimes with APIs suitable for orchestration. Combining LLM reasoning + Qiskit numerical power is the practical next step.

Quick prerequisites

• Python 3.10+ (3.11 recommended)
• pip install qiskit qiskit-ibm-runtime langchain openai asyncio aiohttp numpy scipy
• API keys: OpenAI/Anthropic (or your LLM provider) and optional IBM Quantum credentials if you want to run on hardware.
• Basic familiarity with Qiskit concepts: QuantumCircuit, transpile, execute.

Architecture: a LangChain-style agent for quantum tasks

The pattern is intentionally simple and extensible. Think in terms of three components:

1. Router / Decomposer (LLM-assisted): Accepts the user prompt and decides if the task is symbolic (language-heavy) or numeric (quantum execution).
2. Tools (callable): - LLMTool for symbolic tasks (circuit design, ansatz choices, pseudo-code). - QuantumTool for numerical runs (simulator/hardware).
3. Orchestrator: Handles retries, caching, postprocessing and sends final answers to the user. It allows iterative loops (LLM proposes circuit → simulator returns result → LLM suggests improvements).

Step 1 — Project setup

Install minimal dependencies:

pip install qiskit qiskit-ibm-runtime langchain openai numpy scipy aiohttp

Set your env vars (example):

export OPENAI_API_KEY="sk-..."
export IBMQ_API_TOKEN="..."  # optional for IBM hardware

Step 2 — Implement the LangChain-style building blocks

Below is a minimal but practical implementation. It's intentionally explicit so you can replace components with real LangChain agents or other toolkits.

2.1 LLM wrapper (symbolic tool)

# llm_tool.py
from langchain import OpenAI

class LLMTool:
    def __init__(self, model_name="gpt-4o", temperature=0.0):
        # This uses LangChain's LLM wrapper; swap to your provider if needed.
        self.llm = OpenAI(model_name=model_name, temperature=temperature)

    def call(self, prompt: str) -> str:
        # Return raw text response to keep control in the orchestrator
        return self.llm(prompt)

2.2 Qiskit executor (quantum tool)

# quantum_tool.py
from qiskit import QuantumCircuit, transpile, Aer, execute
from qiskit.providers.aer import AerSimulator
import numpy as np

class QuantumTool:
    def __init__(self, backend_name="aer_simulator", shots=8192):
        if backend_name == "aer_simulator":
            self.backend = AerSimulator()
        else:
            # placeholder for cloud backends (IBM Quantum run/jupyter runtime, etc.)
            self.backend = AerSimulator()
        self.shots = shots

    def run_circuit(self, qc: QuantumCircuit):
        # Transpile for the backend (hardware-aware in a real cloud call)
        t_qc = transpile(qc, self.backend)
        job = execute(t_qc, backend=self.backend, shots=self.shots)
        result = job.result()
        counts = result.get_counts()
        # Convert counts to expectation values (example for Z on qubit 0)
        return {"counts": counts}

    def expectation_from_counts(self, counts: dict, pauli_string: str = "Z0"):
        # Simple utility: for single-qubit Z expectation
        total = sum(counts.values())
        exp = 0.0
        for bitstring, c in counts.items():
            # assume bitstring '0' or '1' for qubit 0; reverse indexing depending on Qiskit version
            val = 1 if bitstring[-1] == '0' else -1
            exp += val * c / total
        return exp

2.3 Minimal router (decide which tool to use)

# router.py
class Router:
    def __init__(self, llm_tool: LLMTool):
        self.llm = llm_tool

    def decide(self, user_prompt: str) -> str:
        # A simple prompt that asks the LLM to decide: SYMBOLIC or QUANTUM
        prompt = f"Decide whether the following user request is primarily SYMBOLIC (language, design) or QUANTUM (numerical execution):\n\nRequest: {user_prompt}\n\nAnswer with exactly one token: SYMBOLIC or QUANTUM."
        resp = self.llm.call(prompt).strip().upper()
        if "SYMBOLIC" in resp:
            return "SYMBOLIC"
        if "QUANTUM" in resp:
            return "QUANTUM"
        # fallback heuristic
        if any(k in user_prompt.lower() for k in ["simulate", "run", "execute", "expectation", "shots"]):
            return "QUANTUM"
        return "SYMBOLIC"

Step 3 — The orchestrator: glue everything together

The orchestrator receives the user payload, uses the router, and then calls the appropriate tool. It also performs an iterative loop where the LLM can refine the circuit based on simulator output.

# orchestrator.py
from qiskit import QuantumCircuit
import time

class HybridAgent:
    def __init__(self, router: Router, llm_tool: LLMTool, quantum_tool: QuantumTool):
        self.router = router
        self.llm = llm_tool
        self.qtool = quantum_tool

    def handle(self, user_prompt: str):
        route = self.router.decide(user_prompt)
        if route == "SYMBOLIC":
            # Ask LLM to produce a Qiskit circuit as Python code snippet
            prompt = (
                "You are a quantum programming assistant. Produce a Qiskit QuantumCircuit" 
                " that matches this request in runnable Python code. Only return the code block.\n\n"
                f"Request: {user_prompt}\n\nExample output must define a variable named 'qc' (QuantumCircuit)."
            )
            code = self.llm.call(prompt)
            # Evaluate code in a controlled environment — sandboxing is essential in prod
            local_env = {}
            try:
                exec(code, {"QuantumCircuit": QuantumCircuit, "np": __import__('numpy')}, local_env)
                qc = local_env.get('qc')
                if qc is None:
                    return {"error": "LLM did not return a variable named 'qc'"}
            except Exception as e:
                return {"error": f"Error executing LLM code: {e}", "llm_output": code}

            # Run numeric execution
            result = self.qtool.run_circuit(qc)

            # Ask LLM to interpret numeric results
            interp_prompt = (
                f"I executed the circuit and got counts: {result['counts']}.\n"
                "Explain the result and next steps (e.g., increase shots, change ansatz, or perform optimization)."
            )
            interpretation = self.llm.call(interp_prompt)
            return {"circuit_code": code, "run_result": result, "interpretation": interpretation}

        else:  # QUANTUM route — do numerical execution even if user asked for it directly
            # We'll ask the LLM to produce a circuit and method, then run it
            prompt = (
                "Produce a Qiskit code snippet that builds a circuit and returns a variable 'qc'" 
                f" for this numerical request: {user_prompt}"
            )
            code = self.llm.call(prompt)
            local_env = {}
            try:
                exec(code, {"QuantumCircuit": QuantumCircuit, "np": __import__('numpy')}, local_env)
                qc = local_env.get('qc')
                if qc is None:
                    return {"error": "LLM did not produce 'qc'"}
            except Exception as e:
                return {"error": f"Execution error: {e}", "llm_output": code}

            result = self.qtool.run_circuit(qc)
            interpretation = self.llm.call(f"I ran the circuit and got counts: {result['counts']}. What is the expectation value and next steps?")
            return {"circuit_code": code, "run_result": result, "interpretation": interpretation}

Step 4 — Example: a minimal parameter sweep task

Let's walk through a concrete example: "Find theta that minimizes the expectation value of Z on qubit 0 for circuit RX(theta)". We'll show how the LLM generates the circuit and the agent executes it on Aer.

# Example LLM-produced code snippet (truncated):
from qiskit import QuantumCircuit, Parameter

theta = Parameter('θ')
qc = QuantumCircuit(1)
qc.rx(theta, 0)
qc.measure_all()

# Agent will substitute numeric values and run multiple shots

The orchestrator can then perform a parameter sweep (or call an optimizer) and use the quantum tool to compute expectation values at each theta. The LLM interprets the results and recommends the minimal theta with confidence intervals.

Practical considerations and production hardening

Below are immediate issues you will face and actionable solutions:

• Sandbox LLM code execution: Never exec arbitrary LLM output in production without sandboxing. Use secure sandboxes (e.g., Firejail, gVisor, or language-specific AST parsing and translator) or require the LLM to output JSON that you validate and compile into circuit constructs.
• Costs and quotas: Quantum cloud runs are metered. Implement cost estimation (shots * backends * runs) and a budget guardrail that falls back to Aer when costs exceed thresholds.
• Determinism & reproducibility: Cache circuit transpilation and simulation results. Use explicit random seeds and record job ids when using cloud backends.
• Noise-aware compilation: Query backend topology and noise model (if available) and request the LLM to produce hardware-aware ansatzes. In 2026 many providers expose noise-adaptive compilation APIs—integrate them into the transpile stage.
• Security & IP: LLMs can leak proprietary circuit designs in some cases. If your circuits are sensitive, keep symbolic processing on in-house models or enforce strict data governance.

Advanced integrations (2026 forward-looking strategies)

The landscape in 2026 is more agentic and integrated than a few years ago. Here are advanced strategies to consider as you mature the agent:

• Policy-based routing: Replace the simple router with a policy engine that accounts for cost, urgency, and sensitivity. For example: if budget < X, route to simulator; if accuracy > Y, route to hardware.
• Multi-tool orchestration: Add tools for PennyLane and Cirq. Create an abstraction layer so the agent can choose the best SDK for the target backend (PennyLane for hybrid gradient-based VQE, Qiskit for IBM devices).
• Async job management: Use asyncio and job queues for long-running hardware jobs. Let the agent provide intermediate updates and resume when results arrive.
• Telemetry + MLOps: Log prompts, circuit versions, backend configs and metrics. This data powers prompt engineering and reproducibility.
• AutoVerifier: Implement a static verifier that checks circuits for safety and resource estimates before sending to hardware (depth, qubit count, expected run time).

Sample prompts & prompt engineering tips

Prompt engineering matters for reliable routing and circuit generation. Use constraints and strict output formats to simplify parsing. Examples:

• Router prompt: "Answer exactly SYMBOLIC or QUANTUM. Do not provide explanations."
• Circuit prompt: "Return only Python code that constructs a QuantumCircuit assigned to variable 'qc'. No commentary."
• Interpretation prompt: "Summarize results in three bullets: numeric summary, confidence, next recommended experiment (one sentence)."

Testing, benchmarking and evaluation

Build a test suite with deterministic circuits (e.g., GHZ, Bell states) so you can verify the end-to-end pipeline. Include unit tests for:

• Router behavior on known prompts.
• LLMTool format conformance (validate code returns 'qc').
• QuantumTool numeric correctness using fixed seeds and small shot counts.

For performance benchmarking, measure latency (prompt → decision → run → interpretation) and cost per run. These metrics help you tune shot counts, caching and routing policies.

Limitations and failure modes

• LLMs hallucinating mathematically incorrect circuits — mitigate via static checks and known-good templates.
• Simulator results that don't generalize to noisy hardware — always include a noise-model test or run a small subset on real hardware.
• Job queue failures or timeouts on cloud backends — build robust retry/backoff and notify users when hardware runs exceed expected duration.

Real-world case study (mini)

A dev team at a fintech startup used this pattern in late 2025 to prototype a portfolio optimization heuristic: the LLM decomposed the objective into a parameterized quantum circuit (QAOA-style ansatz), the agent ran short shot experiments on Aer for exploration, and hardware runs were used to validate top candidates. They reduced experimental cycles by 5× versus manual orchestration and kept cloud costs manageable by automatic simulator fallback.

“Smaller, nimbler AI projects win. Use agents to glue LLM reasoning and quantum runtimes — it reduces friction between ideas and experiments.” — Practical takeaway from 2025–2026 hybrid projects

Actionable checklist (do this next)

1. Clone a starter repo (create one from the code above) and run the example locally with Aer.
2. Implement sandboxing for LLM code execution: prefer AST-to-API translation instead of raw exec.
3. Add budget and shot-guard rails to avoid runaway cloud spend.
4. Integrate a cloud quantum backend and test a single hardware run with strict resource limits.
5. Log prompts and results — iterate on prompt templates based on observed failures.

Future predictions for 2026 and beyond

The agentic trend that accelerated in 2024–2025 (desktop and multi-tool agents from Anthropic, Alibaba and others) will reshape quantum experimentation in 2026. Expect:

• Out-of-the-box agentic integrations in quantum SDKs: built-in routers that select hardware, noise models, and compilation strategies.
• Lower barrier-to-entry LLMs fine-tuned for quantum reasoning, reducing hallucinations for circuit generation.
• Unified orchestration standards for quantum-classical APIs to simplify multi-cloud experiments.

Final best practices

• Keep symbolic reasoning auditable — store the LLM’s intermediate outputs.
• Prefer templates and constrained outputs over free-form code from LLMs.
• Start on simulators; escalate to hardware only after verification and cost checks.
• Design for iterative experiments — agents should make it cheap to run follow-up jobs.

Call to action

Try the sample pipeline: spin up a local Aer session, wire the LLMTool to an inexpensive model, and run the example prompts above. If you want a starter repo, enterprise integrations (hardware cost controls, secure sandboxes) or hands-on workshops for your team, sign up for our workshops and repo access — we’ll help you turn one-off experiments into repeatable quantum-classical products.

Related Reading

• Local DevOps Playbook for AI Apps: GPUs, RISC-V, NVLink, and Edge HATs
• How Tesco’s Celebrity Cooking Series Can Inspire Your Weekly Meal Plan
• Design Briefs That Stop AI Slop: Templates for Generating Accurate Quantum Research Summaries
• Capsule Wardrobe for Modest Fashion: 10 Investment Pieces to Buy Before Prices Rise
• How to Build a Secure Meal-Delivery App That Accepts Autonomous Truck Capacity