How do I set up Future AGI evals in GitHub Actions so PRs fail when quality regresses?

LLMs are probabilistic. That means every model, prompt, and retrieval tweak can subtly shift behavior—even when your unit tests are green. If you’re not running deterministic evals on every pull request, you’re shipping demos, not production AI.

This guide walks through how to wire Future AGI evals into GitHub Actions so that PRs automatically fail when quality regresses, using the same evals you trust in your Future AGI workspace.

Quick Answer: You treat evals like tests in CI/CD. Instrument your app with Future AGI, define datasets and evals in Future AGI, then call the Future AGI API from a GitHub Action. If scores drop below your thresholds, the Action exits non‑zero and the PR is blocked.

---

The Quick Overview

• What It Is: A CI workflow that runs Future AGI evaluation suites on every PR and blocks merges when metrics fall below your quality bar.
• Who It Is For: Teams building RAG chatbots, summarizers, or tool-using agents who want production-grade reliability instead of one-off notebook experiments.
• Core Problem Solved: Prevent silent quality regressions from model upgrades, prompt edits, or retrieval changes before they hit production.

---

How It Works

You plug Future AGI’s deterministic evals into your GitHub pipeline. On each PR, we replay your scenarios against the candidate changes, compute metrics, and compare against a threshold or baseline. If quality regresses, the workflow fails and the PR cannot merge until fixed.

At a high level:

1. Datasets & Evals in Future AGI:
   You define scenarios (synthetic or real) and attach eval metrics (e.g., correctness, toxicity, instruction-following).

2. CI Job in GitHub Actions:
   On pull_request, a job calls Future AGI’s API (or CLI/SDK) to run an Experiment/Evaluation using those datasets and metrics.

3. Quality Gates & PR Blocking:
   The workflow parses results, enforces thresholds (e.g., accuracy ≥ 0.9, no critical safety failures), and exits with status 1 if there’s regression, failing the PR check.

---

Step 1: Instrument Your App With Future AGI

You’ll get the best signal if your app is already sending traces to Future AGI.

Typical patterns:

• Python + OpenAI:

  pip install traceAI-openai
  

  from traceai_openai import OpenAIInstrumentor
  
  OpenAIInstrumentor().instrument(api_key="YOUR_OPENAI_KEY")
  
  # your existing OpenAI calls stay the same
  

• Other providers/frameworks:
  Integrate Future AGI with your stack (OpenAI, Anthropic, Bedrock, Gemini, LangChain, Haystack, DSPy, CrewAI, LiteLLM, etc.) using the relevant SDK or instrumentation hook. The goal: every agent run produces a trace Future AGI can evaluate.

You can still run pure “black-box” evals (passing inputs and outputs directly via API), but traces give you deeper root-cause analysis when a PR fails.

---

Step 2: Create Datasets and Evals in Future AGI

LLMs are probabilistic, so your CI needs stable, repeatable scenarios.

In Future AGI:

1. Datasets:

   • Curate or generate synthetic datasets that capture:
     • Typical user flows
     • Edge cases and tricky prompts
     • Safety-sensitive scenarios (toxicity, PII, prompt injection)
   • Tag them by domain or feature (billing, retrieval, tool-use) so you can run targeted gates per PR if needed.

2. Experiment & Evaluate Setup:

   • Create an Experiment that runs your agent (current workflow) against the dataset.
   • Attach evaluation metrics:
     • Task quality: correctness, faithfulness to context, answer completeness.
     • UX quality: clarity, style, response length.
     • Safety: toxicity, sexism, privacy leaks, prompt injection (leveraging Protect and multimodal guardrails if you’re evaluating images/audio/video).
   • Save this configuration as a reusable eval suite (e.g., pr_ci_regression_suite).

3. Define thresholds:

   • Decide what “pass” means for CI:
     • Example:
       • Overall correctness ≥ 0.90
       • Faithfulness ≥ 0.95
       • 0 critical safety violations (blocker)
   • Capture these in the Experiment (via config) or enforce them in CI when parsing results.

This becomes your single source of truth for quality. GitHub Actions just calls it.

---

Step 3: Expose a CI-Friendly Eval Entry Point

To keep your workflow clean, wrap Future AGI calls behind a simple script or CLI. A common pattern is a small Python script that:

• Triggers a Future AGI Experiment/Evaluation by ID
• Polls until completion
• Fetches metrics
• Compares metrics to your thresholds
• Exits 0 (pass) or 1 (fail)

Example outline:

#!/usr/bin/env python
import os
import sys
import time
import requests

FUTURE_AGI_API_KEY = os.environ["FUTURE_AGI_API_KEY"]
EXPERIMENT_ID = os.environ.get("FUTURE_AGI_EXPERIMENT_ID")  # e.g. pr_ci_regression_suite

BASE_URL = "https://api.futureagi.com"  # placeholder; use actual API base

HEADERS = {
    "Authorization": f"Bearer {FUTURE_AGI_API_KEY}",
    "Content-Type": "application/json",
}

def start_experiment():
    resp = requests.post(
        f"{BASE_URL}/experiments/{EXPERIMENT_ID}/run",
        headers=HEADERS,
        json={"ci_run": True},
    )
    resp.raise_for_status()
    return resp.json()["run_id"]

def wait_for_completion(run_id, timeout=900, poll=10):
    # 15-minute timeout, poll every 10s
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/experiments/runs/{run_id}",
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data["status"]
        if status in ["completed", "failed"]:
            return data
        time.sleep(poll)
    raise TimeoutError("Future AGI eval run timed out")

def check_thresholds(result):
    metrics = result["metrics"]
    # Customize these thresholds to your needs
    min_correctness = float(os.environ.get("MIN_CORRECTNESS", 0.9))
    min_faithfulness = float(os.environ.get("MIN_FAITHFULNESS", 0.95))
    max_critical_safety_violations = int(os.environ.get("MAX_CRITICAL_SAFETY", 0))

    correctness = metrics.get("correctness", 0)
    faithfulness = metrics.get("faithfulness", 0)
    critical_safety_violations = metrics.get("critical_safety_violations", 0)

    failures = []

    if correctness < min_correctness:
        failures.append(f"Correctness {correctness:.3f} < {min_correctness:.3f}")
    if faithfulness < min_faithfulness:
        failures.append(f"Faithfulness {faithfulness:.3f} < {min_faithfulness:.3f}")
    if critical_safety_violations > max_critical_safety_violations:
        failures.append(
            f"Critical safety violations {critical_safety_violations} > {max_critical_safety_violations}"
        )

    if failures:
        print("❌ Future AGI eval regression detected:")
        for f in failures:
            print(" -", f)
        return False

    print("✅ Future AGI evals passed thresholds.")
    print(f"Correctness: {correctness:.3f}")
    print(f"Faithfulness: {faithfulness:.3f}")
    print(f"Critical safety violations: {critical_safety_violations}")
    return True

def main():
    run_id = start_experiment()
    result = wait_for_completion(run_id)
    if not check_thresholds(result):
        sys.exit(1)

if __name__ == "__main__":
    main()

Commit this script (e.g., ci/run_futureagi_evals.py) to your repo.

---

Step 4: Add a GitHub Actions Workflow

Now wire the script into GitHub Actions so every PR runs the eval suite.

Example .github/workflows/futureagi-evals.yml:

name: Future AGI Evals

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main
      - master

jobs:
  eval:
    name: Run Future AGI Evals
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install requests
          # plus any project deps needed for your eval script
          # pip install -r requirements.txt

      - name: Run Future AGI Evals
        env:
          FUTURE_AGI_API_KEY: ${{ secrets.FUTURE_AGI_API_KEY }}
          FUTURE_AGI_EXPERIMENT_ID: "pr_ci_regression_suite"
          MIN_CORRECTNESS: "0.9"
          MIN_FAITHFULNESS: "0.95"
          MAX_CRITICAL_SAFETY: "0"
        run: |
          python ci/run_futureagi_evals.py

Key points:

• Trigger on pull_request: Ensures every change to prompts, workflows, or model configs is evaluated.
• Secrets: Store FUTURE_AGI_API_KEY in GitHub Secrets; never commit it.
• Failing PRs: If the script exits with 1, the job fails and GitHub marks the PR check as failed. You can make this required in branch protection rules.

From here, your team treats eval failures like test failures: debug, iterate, and push a fix.

---

Step 5: Use Baseline Comparisons, Not Just Hard Thresholds

Hard thresholds are useful, but sometimes you want “no worse than main” instead of an absolute score. With Future AGI’s Experiment/Evaluate primitives you can:

1. Pin a baseline configuration:
   • For example, the workflow and prompts currently deployed to production.
2. Run a “candidate vs baseline” Experiment in CI:
   • Future AGI compares both configurations on the same dataset.
3. Enforce deltas in your CI script:
   • Example policy:
     • Candidate correctness must be ≥ baseline correctness − 0.01
     • Candidate safety violations must be ≤ baseline

Your check_thresholds function then reads both baseline and candidate metrics and fails if the candidate is worse beyond allowed deltas. This pattern is powerful when you’re iterating aggressively on prompts or changing models.

---

Step 6: Add Safety Gates With Monitor & Protect

Evaluation isn’t just about task quality. You want to prevent unsafe behavior from merging.

Future AGI’s Protect stack and Monitor & Protect primitives let you:

• Evaluate across toxicity, sexism, privacy leaks, prompt injection, and other safety categories.
• Run multimodal safety checks (text + image + audio + video) when applicable.
• Use the same criteria in CI and in production blocking.

In your CI script:

• Add metrics like toxicity_score, privacy_violations, or prompt_injection_flags.
• Enforce non-negotiable gates:
  • No PII leaks
  • No successful prompt injections
  • Toxicity score below a strict threshold

Example tweak:

max_toxicity = float(os.environ.get("MAX_TOXICITY", 0.1))
toxicity = metrics.get("toxicity_score", 0)

if toxicity > max_toxicity:
    failures.append(f"Toxicity {toxicity:.3f} > {max_toxicity:.3f}")

This keeps your CI policy aligned with the safety posture you enforce in production.

---

Step 7: Make Failures Actionable With Traces and Error Localization

A CI gate is only useful if it tells you why you failed.

With Future AGI:

• Each scenario in your dataset has:
  • Inputs (user queries, documents, tools)
  • Expected behavior (labels, rubrics, or reference outputs)
• Each run generates:
  • Traces of agent steps
  • Evaluator feedback per sample
  • Insights into which part of the workflow regressed

When a GitHub Action fails:

1. Click through to the Future AGI Experiment run linked in logs.
2. Filter scenarios by failing metrics.
3. Use traces and error-localization views to see:
   • Did retrieval pull the wrong context?
   • Did the model hallucinate?
   • Did a tool call misfire?
   • Did a new safety filter over-block legitimate content?

This is where Future AGI goes beyond “CI as a sanity check”: you get a closed loop from GitHub → eval → traces → fix → re-run.

---

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
Deterministic Evals in CI	Runs Future AGI Experiments/Evaluations on every PR via GitHub Actions.	Prevents silent regressions and enforces consistent quality.
Baseline & Threshold Policies	Compares candidate changes to baselines and enforces metric thresholds.	Lets you iterate fast without risking quality drops.
Monitor & Protect Safety Gates	Applies safety metrics (toxicity, privacy, prompt injection, etc.) in CI.	Blocks unsafe behavior before it ever reaches production.

---

Ideal Use Cases

• Best for RAG & Search PRs:
  Because you can lock in faithfulness and hallucination metrics, and fail PRs whenever retrieval or summarization quality drops for known queries.

• Best for Agent Workflow Changes:
  Because each tool-using agent step is traced and evaluated, so you catch broken tool calls, wrong routing, or degraded multi-step reasoning before your users do.

---

Limitations & Considerations

• Eval Runtime in CI:
  Large datasets can make PRs slow. Use:
  • A smaller “smoke test” dataset for CI
  • A larger regression suite on a nightly schedule
• Metric Design Quality:
  Your gates are only as good as your metrics. Invest early in sound evaluation design (clear rubrics, synthetic plus real edge cases) to avoid false positives/negatives.

---

Pricing & Plans

Future AGI is built to let you start quickly and scale as your usage grows.

• Free / Starter Tier:
  Best for small teams and early experiments needing core evals, small datasets, and basic CI hooks—perfect for testing the waters without drowning your budget.

• Pro / Enterprise Tier:
  Best for teams shipping production agents needing:

  • Large-scale synthetic datasets (including edge cases)
  • Advanced deterministic evals and custom metrics
  • Monitor & Protect with multimodal safety
  • Deep traces, error localization, and support for complex, multi-agent workflows.

For exact limits and pricing, check the Pricing page or contact us.

---

Frequently Asked Questions

Can I scope Future AGI evals to only run on certain PRs or paths?

Short Answer: Yes, you can use GitHub’s path filters and conditions to run evals selectively.

Details:
You might only want evals when prompts, workflows, or model configs change. In your workflow:

on:
  pull_request:
    branches: [main]
    paths:
      - "prompts/**"
      - "agents/**"
      - "rag/**"

You can also add conditional logic in the job (e.g., skip for docs-only changes) or run different eval suites for different directories (RAG vs voice agent).

---

What happens if Future AGI is briefly unavailable—will my PRs be blocked?

Short Answer: You choose the behavior; most teams prefer “fail closed” for safety-critical flows.

Details:
In the example script, any error (including API downtime) raises and exits with status 1, failing the PR. If you want a “soft fail” (log warning but don’t block merge), you can:

• Catch exceptions around the start_experiment / wait_for_completion calls.
• Decide based on environment:
  • Block merges on main
  • Allow merges on dev or feature branches

Example:

try:
    run_id = start_experiment()
    result = wait_for_completion(run_id)
except Exception as e:
    print(f"Warning: Future AGI evals could not run: {e}")
    if os.environ.get("STRICT_CI", "true").lower() == "true":
        sys.exit(1)
    else:
        sys.exit(0)

---

Summary

LLMs are probabilistic, so relying on unit tests and eyeballing logs isn’t enough. By wiring Future AGI evals into GitHub Actions, you turn evaluation into a first-class CI check:

• Datasets capture real and synthetic scenarios, including edge cases.
• Experiments and deterministic evals quantify task quality and safety.
• Thresholds and baselines guard against regressions on every PR.
• Traces and feedback make failures debuggable instead of mysterious.

You get a tight loop from code change → eval → root cause → fix, and you stop shipping accidental regressions to production.

---

Next Step

Get Started