AgentHeal

AgentHeal is a pluggable, GitOps-safe self-healing layer for single-agent and multi-agent applications. It turns observable failures—poor outputs, tool errors, latency regressions, explicit user feedback, and validation failures—into a targeted, reviewable repair proposal.

It is deliberately not an autonomous file editor. AgentHeal produces a unified Git diff, checks it against a safety policy, validates it in a disposable Git worktree, and only creates a GitHub pull request when a human has explicitly opted in.

Build Week note: the complete, browser-based demonstration is intentionally kept separate in AgentHeal-LLMCouncil-Sandbox. That application imports this package just like a customer application would. This repository is the reusable developer tool.

What it does

Agent telemetry + user feedback + repository signals
  -> DriftDetector: score and localise a regression
  -> SelfEditGenerator: request a minimal unified Git diff
  -> Validator: apply only in an isolated worktree and run checks
  -> PRGenerator: optionally push a reviewable GitHub pull request

AgentHeal accepts framework-neutral trace records, so it can sit beside LangGraph, custom Python orchestration, or a single agent without taking control of the agent runtime. Each trace may include the agent name, input/output, tools, files, latency, confidence, errors, and human feedback. AgentHeal uses those signals to map the likely affected agent to the smallest relevant source-file set before asking a model to reason about a repair.

Judge quick path: install, test, and inspect

The commands below are enough to verify the package without an API key or any code mutation.

git clone https://github.com/ChiragAJain/AgentHeal.git
cd AgentHeal
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

# Deterministic offline safety test: validates a patch in a disposable Git worktree.
pytest -q

Expected result: the tests pass, the original fixture repository remains unchanged, and no pull request is created. This is the safest way to validate the core self-healing path without spending model credits.

For the full live Council + AgentHeal demonstration, follow the setup and critical-routing test path in AgentHeal-LLMCouncil-Sandbox.

BYOK: Sarvam by default, other providers by choice

AgentHeal is bring-your-own-key (BYOK). The package configuration defaults to Sarvam with two lanes:

Lane	Suggested model	Responsibility
Coding	sarvam-105b	Generate minimal, codebase-compatible repair diffs only.
Operations	sarvam-30b	Assess drift, review traces/errors, interpret validation, and draft PR material.

Create a local .env from the tracked example; it is ignored by Git:

Copy-Item .env.example .env

Set only your own values in .env:

AGENTHEAL_PROVIDER=sarvam
AGENTHEAL_CODING_PROVIDER=sarvam
AGENTHEAL_CODING_MODEL=sarvam-105b
SARVAM_CODING_API_KEY=replace-with-your-coding-key
AGENTHEAL_OPERATIONS_PROVIDER=sarvam
AGENTHEAL_OPERATIONS_MODEL=sarvam-30b
SARVAM_OPERATIONS_API_KEY=replace-with-your-operations-key

Validate readiness without exposing any credential values:

agentheal doctor --provider sarvam --dotenv .env

Run a live preview against a Git repository:

agentheal maintain "Investigate repeated security-routing failures" `
  --provider sarvam `
  --repo-path C:\path\to\your-agent-repository `
  --agents SupportRouter,SecurityIncident `
  --observations '[{"agent":"SupportRouter","drift":0.91,"detail":"security incidents were routed to GeneralSupport"}]' `
  --dotenv .env

The core also supports fully local Ollama, OpenAI, and AWS Bedrock. Select a provider with AGENTHEAL_PROVIDER or --provider; selected integrations report a clear install or credential error instead of silently falling back. SARVAM_API_KEY remains supported as a single-key fallback. Keys are never emitted in traces, connection reports, diffs, validation logs, or PR text.

Integrate into any agent system

Wrap an existing agent call, emit a trace, and let AgentHeal decide whether measurable drift warrants a preview. AgentHeal does not require the caller to adopt a particular agent framework.

import time

import agentheal as ah

healer = ah.AgentHeal(
    ah.AgentHealConfig.from_environment(
        repo_path="/workspace/my-agent-system",
        agent_names=["SupportRouter", "SecurityIncident"],
        validation_commands=(("pytest", "-q"),),
    )
)

started = time.perf_counter()
try:
    answer = support_router.invoke("My account may be compromised")
    trace = ah.AgentTrace(
        agent_name="SupportRouter",
        input_query="My account may be compromised",
        output=answer.text,
        tools_used=("ticket_lookup",),
        files_involved=("agents.py",),
        latency_ms=(time.perf_counter() - started) * 1000,
        confidence=answer.confidence,
        human_feedback="Unsafe: routed a security incident to GeneralSupport",
    )
except Exception as exc:
    trace = ah.AgentTrace(
        agent_name="SupportRouter",
        input_query="My account may be compromised",
        error=str(exc),
        files_involved=("agents.py",),
    )

# Preview-only is the default: no checkout mutation and no PR.
preview = healer.run(
    objective="Restore security-first ticket routing",
    traces=[trace],
)
print(preview["drift_report"], preview["validation"], preview["pr"])

Use create_pull_request=True in AgentHealConfig (or --create-pr) only after reviewing the preview and configuring GITHUB_TOKEN, GITHUB_REPOSITORY=owner/repo, and Git push credentials. AgentHeal uses the GitHub API only to open the PR; your Git remote still needs permission to push the review branch.

Safety model

• Preview-first: normal runs never alter the caller’s checkout and never publish a PR.
• Targeted scope: trace attribution and LOC/source mapping focus model context on the implicated agent and files rather than scanning the entire codebase.
• Diff-only generation: the model may propose a unified Git patch; it never receives a direct file-write capability.
• Deterministic policy gate: protected paths, traversal attempts, oversized patches, and excessive file changes are rejected before application.
• Isolated validation: a patch is applied only in a disposable Git worktree, then compilation and configured validation commands run there.
• Human-controlled delivery: a successful validation produces a reviewable result; branch push and PR creation are explicit opt-ins.
• Auditable evidence: graph state records detector findings, source mapping, patch rationale, validation output, provider lane selection, and any errors.

This is how AgentHeal follows the self-adaptation idea: it adapts code or configuration in response to measured degradation, while preserving an approval boundary that makes every proposed change reversible and inspectable.

How Codex and GPT-5.6 were used

AgentHeal was built during OpenAI Build Week with Codex as the engineering collaborator. Codex and GPT-5.6 were used to design and implement the LangGraph workflow, trace schema, provider adapters, isolated-worktree validation, patch-policy gates, CLI, tests, and the companion Council demo. They were also used to iteratively review implementation choices and produce judge-facing documentation.

At runtime, AgentHeal does not require Codex or GPT-5.6: it uses the developer’s selected BYOK provider. When OpenAI is selected, AgentHeal uses a Codex-style prompt that demands the smallest compatible unified diff, explicit assumptions, and no unrelated refactors.

Documentation

• Getting started
• Authentication and roles for the standalone demo
• Council demo documentation

For the Build Week submission, remember to capture and enter the /feedback Codex session ID.