Skip to main content

Agent Integration Guide

This guide covers how to integrate AI agents — Claude, LangChain, AutoGen, CrewAI, and others — with all Softquantus services through MCP tools, the REST API, and the Python SDK.

Integration patterns​

Pattern 1 — MCP (recommended for agent frameworks)​

The QCOS MCP server is the simplest way to give an agent access to all Softquantus services. The agent discovers available tools automatically and calls them without needing to handle HTTP.

Best for: Claude Desktop, Claude API with MCP, LangChain with MCP adapters, AutoGen, CrewAI.

See MCP Quickstart.

Pattern 2 — REST API (for custom integrations)​

Call the QCOS, QuantumLock, and SynapseX REST APIs directly from agent tool definitions. Full control over request/response handling.

Best for: custom agent frameworks, backend services calling QCOS server-to-server.

Pattern 3 — Python SDK (for Python-native agents)​

Use the softqcos Python package inside agent tool functions. Handles auth, retries, and result polling automatically.

Best for: Python-native agent pipelines, Jupyter environments, research workflows.

Full agent example — Claude API with MCP​

The following builds an agent that runs a quantum optimization workflow end-to-end:

import anthropic
import os

client = anthropic.Anthropic()

system_prompt = """
You are a quantum computing assistant with access to the Softquantus platform.

Available services:
- QCOS: quantum circuit execution, VQE, QAOA, backend management
- QuantumLock: post-quantum key management and license verification
- SynapseX: AI inference, quantum reranking, embeddings

When executing quantum jobs:
1. Always call qcos_list_backends first to check calibration status
2. Prefer backends with DRR score > 80 (GREEN signal)
3. For optimization problems, start with QAOA depth=2 before increasing
4. Report DRR scores alongside results so the user knows result reliability

When in doubt about reliability, explain the DRR signal to the user.
"""

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    system=system_prompt,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.softquantus.com/sse",
            "name": "softquantus",
            "authorization_token": os.environ["QCOS_API_KEY"],
        }
    ],
    messages=[
        {
            "role": "user",
            "content": """
                I need to optimize a portfolio of 6 assets to maximize Sharpe ratio.
                The covariance matrix and expected returns are in the attached JSON.
                Run QAOA and return the optimal weights.
            """,
        }
    ],
    betas=["mcp-client-2025-04-04"],
)

Full agent example — LangChain​

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
from langchain_anthropic import ChatAnthropic

QCOS_API_KEY = "sk-..."

async def run_quantum_agent(task: str) -> str:
    async with MultiServerMCPClient(
        {
            "softquantus": {
                "url": "https://mcp.softquantus.com/sse",
                "transport": "sse",
                "headers": {"Authorization": f"Bearer {QCOS_API_KEY}"},
            }
        }
    ) as mcp_client:
        tools = mcp_client.get_tools()
        llm = ChatAnthropic(model="claude-sonnet-4-6", temperature=0)

        prompt = ChatPromptTemplate.from_messages([
            ("system", "You are a quantum computing assistant with access to QCOS, QuantumLock, and SynapseX."),
            ("human", "{input}"),
            ("placeholder", "{agent_scratchpad}"),
        ])

        agent = create_tool_calling_agent(llm, tools, prompt)
        executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
        result = await executor.ainvoke({"input": task})
        return result["output"]

# Run
asyncio.run(run_quantum_agent("Run VQE for H2 on the best available backend and report the ground state energy."))

Full agent example — Python SDK (no MCP)​

For cases where you want direct SDK control inside agent tool functions:

from softqcos import QCOSClient
from quantumlock import QuantumLockClient

qcos = QCOSClient(api_key="sk-...")
ql = QuantumLockClient(api_key="sk-...")

# Define tool functions for your agent framework
def list_backends() -> list:
    return qcos.backends.list(status="online")

def run_circuit(circuit_qasm: str, backend: str, shots: int = 1024) -> dict:
    job = qcos.jobs.run(circuit=circuit_qasm, backend=backend, shots=shots, wait=True)
    return {
        "counts": job.counts,
        "drr_score": job.drr.score,
        "drr_signal": job.drr.signal,
        "proof_hash": job.proof_hash,
    }

def generate_key(algorithm: str = "ML-KEM-768", label: str = None) -> dict:
    key = ql.keys.create(algorithm=algorithm, label=label)
    return {"key_id": key.id, "public_key": key.public_key}

Multi-agent patterns​

Orchestrator–worker pattern​

Orchestrator agent (Claude)
    │
    ├──► Quantum worker (QCOS MCP tools)
    │        Submits circuits, retrieves results
    │
    ├──► Security worker (QuantumLock MCP tools)
    │        Manages key lifecycle, verifies licenses
    │
    └──► AI worker (SynapseX MCP tools)
             Reranks results, generates summaries

The orchestrator decomposes the task and delegates subtasks to workers that each have scoped access to one service.

Feedback loop pattern​

# Agent loop: submit circuit → check DRR → adjust if needed → resubmit
async def reliable_quantum_run(circuit, backend, drr_threshold=80):
    while True:
        drr = await agent.call_tool("qcos_get_drr_score", circuit=circuit, backend=backend)
        if drr["score"] >= drr_threshold:
            result = await agent.call_tool("qcos_submit_circuit", circuit=circuit, backend=backend, wait_for_result=True)
            return result
        else:
            # Ask the agent to simplify the circuit or choose a different backend
            circuit = await agent.simplify_circuit(circuit)

Billing and quota​

Every tool call that executes a quantum job deducts QCOS Credits from your account. The MCP server returns a credits_used field in every job result.

{
  "counts": { "00": 512, "11": 512 },
  "credits_used": 12,
  "credits_remaining": 2988
}

Agents can check balance with qcos_get_balance before submitting large jobs.

Next steps​