Skip to main content

​
What This Does

This guide helps you create a custom agent that uses LoopIQ MCP safely. A custom agent can use MCP to read LoopIQ records, retrieve release governance evidence, run AI/ML agents, and request approved actions such as remediation work-package creation. Use this pattern for production agents:
  1. The user authenticates with your application.
  2. Your backend obtains or receives a LoopIQ-approved access token.
  3. Your backend connects to the LoopIQ MCP server.
  4. The agent discovers available tools.
  5. The agent uses read tools first to ground its answer.
  6. The agent previews any write action.
  7. The user approves or rejects the payload.
  8. The backend executes approved writes with an idempotency key.
  9. Your app stores the audit trail.
Do not put long-lived bearer tokens in browser code, mobile apps, prompts, screenshots, or shared configuration files.

​
Good First Custom Agents

Start with agents that read context before they write:
  • Release readiness copilot
  • Evidence gap reviewer
  • Security blocker summarizer
  • Sprint planning assistant
  • Incident triage assistant
  • Compliance evidence packager
  • Analytics dashboard assistant
  • Remediation work-package creator

​
Required Safety Behavior

Every production custom agent should:
  • preserve tenant and user context
  • pass request ID and trace ID
  • use read-only tools before write tools
  • prefer semantic tools over raw route invocation
  • use dryRun: true before important mutations
  • show the exact payload before approval
  • use an idempotency key for approved writes
  • store the approval ID and tool result
  • reject actions with missing parent records, missing titles, or unclear ownership

​
Example Agent Flow

For a release remediation agent:
  1. Ask the user for a release or certification.
  2. Call loopiq_get_release_certification.
  3. Call loopiq_get_release_certification_evidence_graph.
  4. Identify failed controls, evidence gaps, and provider blockers.
  5. Draft one parent remediation story and child tasks.
  6. Call loopiq_create_remediation_work_package with dryRun: true.
  7. Show the user the payload.
  8. If approved, call the same tool with dryRun: false, approvalId, and idempotencyKey.
  9. Show created story and task IDs.

​
Openai Custom Agent Example

The exact SDK syntax may vary by OpenAI SDK version, but the production pattern is stable: 
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const loopiqMcpServer = {
  type: "mcp",
  server_label: "loopiq",
  server_url: process.env.LOOPIQ_MCP_URL,
  headers: {
    Authorization: `Bearer ${process.env.LOOPIQ_ACCESS_TOKEN}`,
  },
};

const response = await openai.responses.create({
  model: "gpt-4.1",
  tools: [loopiqMcpServer],
  input: [
    {
      role: "system",
      content:
        "You are a LoopIQ release governance assistant. Read evidence before making recommendations. Never create or update records without explicit user approval.",
    },
    {
      role: "user",
      content:
        "Review release backend-v1.0-GCN and draft a remediation work package for blockers. Do not execute writes yet.",
    },
  ],
});

console.log(response.output_text);
For write actions, build an approval step in your application. The agent should return a proposed payload, not execute the write immediately.

​
Approval Loop Example

const proposedPayload = {
  tenantId: "fusiononeplatform",
  story: {
    title: "Remediate release blockers for backend-v1.0-GCN",
    description: "Parent story for release certification blockers.",
    release_id: "REL_ID",
    certification_id: "CERT_ID",
  },
  tasks: [
    {
      title: "Triage critical Checkmarx findings",
      description: "Review exploitable critical findings attached to the release evidence graph.",
    },
  ],
  dryRun: true,
};

// First run a dry-run through your MCP client.
// Then display proposedPayload to the user.

const approvedPayload = {
  ...proposedPayload,
  dryRun: false,
  approvalId: "approval_123",
  idempotencyKey: "release-backend-v1-remediation-2026-06-04",
};

// Execute only after approval.

​
Prompt Template for a Custom LoopIQ Agent

Use a system prompt like this: 
You are a governed LoopIQ agent.

Rules:
- Always preserve tenant and user context.
- Prefer semantic LoopIQ MCP tools over raw route invocation.
- Read relevant records before recommending action.
- For release readiness, read the release certification and evidence graph first.
- For remediation, create a parent story and child tasks only through an approved work-package tool.
- Never invent backlog items, evidence, provider findings, owners, releases, or certifications.
- For write actions, produce a preview payload and wait for explicit approval.
- Include request ID, trace ID, approval ID, and idempotency key in action metadata.
- If evidence is missing or stale, say so and request a refresh instead of giving a confident answer.

​
Tool Selection Guide

Use these rules:
  • Use loopiq_get_mcp_reliability_contract at startup to understand server guarantees.
  • Use loopiq_list_ai_ml_agents before running AI/ML agents.
  • Use loopiq_list_resources before generic record operations.
  • Use loopiq_list_routes before fallback route invocation.
  • Use release certification tools for release compliance workflows.
  • Use evidence graph tools for provider-normalized evidence.
  • Use analytics tools for metrics, charts, and dashboard workflows.
  • Use loopiq_create_remediation_work_package for approved parent-story-plus-child-task creation.

​
Tenant and Auth Setup

Your custom agent should not ask the user to paste a token into a prompt. Use one of these patterns:
  • backend session exchanges user auth for a LoopIQ token
  • short-lived user token stored server-side
  • organization-approved service account token with strict tenant allow-list
  • Helix backend-mediated flow where LoopIQ handles MCP auth propagation
For multi-tenant users, always show the selected tenant before executing actions.

​
Dry-run and Approval Strategy

For read-only tools, execute normally. For write tools:
  1. Call with dryRun: true when supported.
  2. Show the exact payload.
  3. Ask for approval.
  4. Add approvalId.
  5. Add idempotencyKey.
  6. Execute once.
  7. Store the result.
If the network drops after approval, check the audit trail before retrying.

​
Testing Checklist

Before production, test:
  • tool discovery works
  • tenant context is correct
  • read-only calls return expected records
  • unauthorized tenants are rejected
  • stale or expired tokens fail safely
  • dry-run write calls do not create records
  • approved writes create exactly the expected records
  • duplicate idempotency keys do not create duplicates
  • action results include created IDs
  • audit metadata is stored

​
Troubleshooting

​
The Agent Sees Too Many Tools

Constrain the agent with instructions to prefer semantic tools and specific tool families. Use loopiq_list_resources or loopiq_list_ai_ml_agents instead of listing every route.

​
The Agent Chooses loopiq_invoke_route Too Often

Add a system instruction: “Use raw route invocation only when no named semantic tool exists.”

​
The Agent Proposes Ungrounded Tasks

Reject the action. Ask the agent to list the records it read: release, certification, evidence graph records, failed controls, provider blockers, evidence gaps, and linked work items.

​
The Action Fails with Missing Fields

Regenerate the payload with explicit required fields. For work items, require clear titles, parent story details, release ID, certification ID, team, and evidence references.

​
The Custom Agent Gives a Confident Answer with Missing Evidence

Change the prompt so missing provider evidence forces a caveated answer and a refresh recommendation.