Skip to content

Commit 47d4739

Browse files
mnvsk97mnvsk97
committed
AgentBreak — chaos proxy for testing LLM agent resilience
Supports OpenAI, Anthropic, and MCP. Injects faults like latency, HTTP errors, timeouts, and malformed responses between your agent and the real API. Features: - Configurable fault injection via YAML scenarios - 7 built-in presets (standard, brownout, mcp-slow-tools, etc.) - Mock mode (no API keys) and proxy mode (real traffic) - 0-100 resilience scoring with pass/degraded/fail outcome - MCP tool discovery and chaos testing - Run history and comparison - Claude Code plugin for guided testing - CI/CD ready (GitHub Actions, GitLab CI)
0 parents  commit 47d4739

50 files changed

Lines changed: 8344 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude-plugin/marketplace.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "mnvsk97-agentbreak",
3+
"owner": {
4+
"name": "mnvsk97"
5+
},
6+
"metadata": {
7+
"description": "Chaos-test LLM agents for resilience, reliability, and fault tolerance by injecting failures between your agent and the real API.",
8+
"version": "0.4.5"
9+
},
10+
"plugins": [
11+
{
12+
"name": "agentbreak",
13+
"description": "Chaos-test LLM agents for resilience. Injects latency, errors, timeouts, and malformed responses to find failure modes before production does.",
14+
"version": "0.4.5",
15+
"author": {
16+
"name": "mnvsk97"
17+
},
18+
"source": "./plugins/agentbreak"
19+
}
20+
]
21+
}

‎.github/workflows/ci.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- feat/**
8+
pull_request:
9+
10+
jobs:
11+
test:
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
python-version: ["3.10", "3.11", "3.12"]
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v5
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v6
24+
with:
25+
python-version: ${{ matrix.python-version }}
26+
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install -e '.[dev]'
31+
32+
- name: Run tests
33+
run: python -m pytest -q -m "not integration"
34+
35+
publish:
36+
needs: test
37+
runs-on: ubuntu-latest
38+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
39+
environment: pypi
40+
permissions:
41+
id-token: write
42+
steps:
43+
- name: Checkout
44+
uses: actions/checkout@v5
45+
46+
- name: Set up Python
47+
uses: actions/setup-python@v6
48+
with:
49+
python-version: "3.12"
50+
51+
- name: Build
52+
run: |
53+
python -m pip install --upgrade pip build
54+
python -m build
55+
56+
- name: Check if version exists on PyPI
57+
id: check
58+
run: |
59+
VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
60+
if pip index versions agentbreak 2>/dev/null | grep -q "$VERSION"; then
61+
echo "exists=true" >> "$GITHUB_OUTPUT"
62+
else
63+
echo "exists=false" >> "$GITHUB_OUTPUT"
64+
fi
65+
66+
- name: Publish to PyPI
67+
if: steps.check.outputs.exists == 'false'
68+
uses: pypa/gh-action-pypi-publish@release/v1

‎.github/workflows/docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs-site/**"
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: pages
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v5
24+
25+
- uses: actions/setup-python@v6
26+
with:
27+
python-version: "3.12"
28+
29+
- name: Install MkDocs
30+
run: pip install mkdocs-material
31+
32+
- name: Build site
33+
run: cd docs-site && mkdocs build
34+
35+
- uses: actions/upload-pages-artifact@v4
36+
with:
37+
path: docs-site/site
38+
39+
deploy:
40+
needs: build
41+
runs-on: ubuntu-latest
42+
environment:
43+
name: github-pages
44+
url: ${{ steps.deployment.outputs.page_url }}
45+
steps:
46+
- id: deployment
47+
uses: actions/deploy-pages@v5

‎.gitignore‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.venv/
2+
*.egg-info/
3+
__pycache__/
4+
.pytest_cache/
5+
build/
6+
dist/
7+
config.yaml
8+
.env
9+
.env.*
10+
.superdesign/
11+
.claude/
12+
.tmp/
13+
.agentbreak/
14+
application.yaml
15+
scenarios.yaml
16+
uv.lock
17+
*.pckl
18+
.langgraph_api/
19+
.agents/
20+
skills-lock.json
21+
22+
.cortex/
23+
docs-site/site/
24+
25+
# IDE plugin/skill symlinks
26+
.adal/
27+
.augment/
28+
.codebuddy/
29+
.commandcode/
30+
.continue/
31+
.crush/
32+
.cursor/
33+
.factory/
34+
.github/copilot/
35+
.goose/
36+
.iflow/
37+
.junie/
38+
.kilocode/
39+
.kiro/
40+
.kode/
41+
.mcpjam/
42+
.mux/
43+
.neovate/
44+
.openhands/
45+
.pi/
46+
.pochi/
47+
.qoder/
48+
.qwen/
49+
.roo/
50+
.trae/
51+
.vibe/
52+
.windsurf/
53+
.zencoder/

‎CLAUDE.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Claude Code — AgentBreak
2+
3+
## What this repo is
4+
5+
A Python package that proxies LLM (OpenAI + Anthropic) and MCP traffic, injecting configurable faults. Config lives in `.agentbreak/`, created by `agentbreak init`.
6+
7+
## Quick commands
8+
9+
```bash
10+
pip install -e '.[dev]'
11+
agentbreak init
12+
agentbreak validate
13+
agentbreak serve
14+
```
15+
16+
For MCP: `agentbreak inspect` then `serve`.
17+
18+
## Plugin
19+
20+
Install in Claude Code via `/plugin marketplace add mnvsk97/agentbreak`, then use `/agentbreak`.
21+
22+
## Verification
23+
24+
Before suggesting a change is done: run **`agentbreak verify`**.

‎CODE_OF_CONDUCT.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Code of Conduct
2+
3+
## Our Standard
4+
5+
Be respectful, direct, and constructive.
6+
7+
Examples of expected behavior:
8+
9+
- giving clear technical feedback
10+
- assuming good intent
11+
- accepting correction gracefully
12+
- focusing discussion on the work, not the person
13+
14+
Examples of unacceptable behavior:
15+
16+
- harassment or personal attacks
17+
- discriminatory language
18+
- doxxing or publishing private information
19+
- trolling, intimidation, or sustained disruption
20+
21+
## Scope
22+
23+
This applies to project spaces and project-related communication.
24+
25+
## Enforcement
26+
27+
Project maintainers may remove, edit, or reject comments, commits, code, issues, and other contributions that violate this Code of Conduct.
28+
29+
## Reporting
30+
31+
For conduct issues, open a private security-style report to the maintainers rather than escalating in public threads.

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing
2+
3+
## Setup
4+
5+
```bash
6+
python3 -m venv .venv
7+
source .venv/bin/activate
8+
pip install -e '.[dev]' # includes pytest; use '.' for core only
9+
```
10+
11+
## Commands
12+
13+
```bash
14+
agentbreak init # create .agentbreak/ config
15+
agentbreak verify # run pytest
16+
agentbreak validate # check config
17+
agentbreak inspect # discover MCP tools
18+
agentbreak serve # start proxy
19+
```
20+
21+
## Repo Layout
22+
23+
| Path | Role |
24+
|------|------|
25+
| `agentbreak/main.py` | CLI (`serve`, `validate`, `inspect`, `verify`), FastAPI app, proxy logic |
26+
| `agentbreak/config.py` | `application.yaml` Pydantic models, registry I/O |
27+
| `agentbreak/scenarios.py` | `scenarios.yaml` schema and validation |
28+
| `agentbreak/behaviors.py` | Response mutation helpers |
29+
| `agentbreak/discovery/mcp.py` | MCP server inspection |
30+
| `tests/` | Pytest suite (`agentbreak verify` runs these) |
31+
32+
## Guidelines
33+
34+
- Keep the product surface small.
35+
- Prefer one clear path over several aliases or modes.
36+
- Keep scenarios explicit and typed.
37+
- Preserve test isolation so `agentbreak verify` stays deterministic.
38+
- Update docs when config shape or fault types change.
39+
40+
Full docs at [mnvsk97.github.io/agentbreak](https://mnvsk97.github.io/agentbreak).

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 AgentBreak contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)