Enterprise Agentic Ai Suite

Enterprise Agentic AI Platform Suite

[](https://github.com/mmoideen/enterprise-agentic-ai-suite/actions/workflows/ci.yml) [](LICENSE) [](.python-version)

> Governed MCP server · multi-agent A2A orchestration · telemetry-driven cost forecasting — one suite answering the three questions every enterprise asks before letting AI agents near a system of record.

The 90-second pitch

Enterprises adopting agentic AI against HCM/Financials platforms hit the same three walls. Each module here takes one down, and proves it with measured evidence from this repository:

1. **Governance — can an agent be trusted with our data?**

Module 1 is an MCP server where zero-trust enforcement happens at the tool layer: JWT → role → scope → row → field, with per-role redaction and a full audit trail. Proof: an offline end-to-end test drives two real MCP clients over real HTTP into one server process — the hr_partner client receives a tokenized SSN (tok_ssn_-NNNN) while the finance_analyst client's response contains no ssn key at all, for the same worker, from the same process ([tests/test_mcp_http_e2e.py](tests/testmcphttp_e2e.py)).

1. **Orchestration — can agents run a real business process?**

Module 2 runs a headcount-and-budget approval end to end: a deterministic engine routes typed A2A envelopes between specialist Claude agents (HR, Finance), parks at a persisted human approval gate, and commits through the governed server only after a human decides. Proof: the committed live run [data/sample_runs/run_demo_approved/](data/sampleruns/rundemo_approved/) went goal → HR → Finance → human approval → governed commit (ledger led_b5343da61f79) for $0.0440 total model cost with 82.8% of prompt tokens served from cache. The denied run shows the other path: finance flagged CC-4200's $50,000 remaining against a $190,000 ask, and the human denial ended the run with the rationale on record.

1. **Economics — what does this cost at 10,000 seats?**

Module 3 parses the recorded telemetry from Modules 1–2 and produces seat-scaled spend forecasts, cache scenarios, and rate-limit/concurrency analysis — every figure provenance-tagged. Proof: from the two committed sample runs, year-1 spend at 10,000 seats is $9,849 with the measured cache-hit rate vs $22,697 uncached; the lowest API tier that fits is tier2, with input-tokens-per-minute as the bottleneck dimension ([examples/sample_blueprint.md](examples/sample_blueprint.md)).

All three modules share one telemetry contract, one synthetic Workday-shaped data platform (61 workers, 6 cost centers, 8 supervisory orgs — fully synthetic), and one identity model. Module 1 proves governance, Module 2 proves orchestration, Module 3 proves economics — from the same recorded runs.

Architecture

flowchart TB
    subgraph M2["Module 2 — A2A Orchestrator (src/orchestrator)"]
        ENG["Deterministic enginestate machine + HITL gate"]
        ORC["orchestrator agentno tools, no token"]
        HR["hr_specialistJWT role: hr_partner"]
        FIN["finance_specialistJWT role: finance_analyst"]
        CXO["committerJWT role: cxo + can_use_tool guard"]
        ENG --> ORC
        ENG --> HR
        ENG --> FIN
        ENG --> CXO
    end

    subgraph M1["Module 1 — Governed MCP Server (src/mcp_server)"]
        AUTH["ASGI auth middlewareBearer JWT → Principal"]
        PIPE["Governance pipelinescope → row → redact → audit"]
        AUTH --> PIPE
    end

    subgraph F["Shared foundations"]
        DATA["Synthetic HCM/Financials datasrc/core/data"]
        IDN["Identity: roles × scopes, JWT issuersrc/core"]
        TEL["Telemetry contract (JSONL)src/telemetry"]
    end

    M3["Module 3 — Forecast Engine (src/forecast)joins tool_span + agent_turn on trace_id"]

    HR -->|"HTTP · Bearer JWT · X-Trace-Id"| AUTH
    FIN -->|"HTTP · Bearer JWT · X-Trace-Id"| AUTH
    CXO -->|"HTTP · Bearer JWT · X-Trace-Id"| AUTH
    PIPE --> DATA
    IDN -.-> AUTH
    PIPE -->|"tool_span events"| TEL
    ENG -->|"agent_turn events"| TEL
    TEL --> M3

Each specialist presents its own role-scoped JWT to the same server, so the audit trail proves the server treats each caller differently — redaction and authorization are demonstrated per identity, not asserted. Every event on both sides of the HTTP boundary carries the run's trace_id (propagated via X-Trace-Id), which is what lets the forecast engine join agent-side token costs to server-side governance evidence.

> The zero-trust proof. One server process serves two MCP clients holding two different role JWTs, and returns two different redacted views of the same worker record — hr_partner gets a deterministic HMAC SSN token, finance_analyst gets no ssn key at all — with each call audited under its caller's identity in the same audit stream. In the recorded live run, a single trace_id joins the hr_partner, finance_analyst, and cxo tool calls into one cross-process trace. See [tests/test_mcp_http_e2e.py](tests/testmcphttpe2e.py) for the executable proof and [docs/mcp_architecture.md](docs/mcparchitecture.md) for the design.

Quickstart (offline — no API key required)

Prerequisite: uv. Three commands from a fresh clone:

make setup      # uv sync + create .env from .env.example
make test       # full offline suite: 240 tests (2 live-gated tests skip without credentials)
make forecast   # seat-scaled cost forecast from the committed real-run telemetry

make forecast runs suite forecast --runs data/sample_runs --seats 100 --seats 10000 --mode production and prints:

           Year-1 spend forecast (2 recorded runs)
┏━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃  Seats ┃ year-1 zero ┃ year-1 measured ┃ year-1 optimized ┃
┡━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│    100 │     $226.97 │          $98.49 │           $97.08 │
│ 10,000 │  $22,696.67 │       $9,848.64 │        $9,708.23 │
└────────┴─────────────┴─────────────────┴──────────────────┘
Selected tier: tier2 (bottleneck: itpm)
Blueprint: runs/forecast/blueprint.md
Forecast JSON: runs/forecast/forecast.json

The GSI Partner Blueprint lands at runs/forecast/blueprint.md with the machine-readable runs/forecast/forecast.json beside it (a committed copy of each is in [examples/](examples/)).

To poke the governed server directly: make serve-mcp boots it on 127.0.0.1:8765 (GET /healthz returns {"status":"ok"}; an unauthenticated POST /mcp returns HTTP 401 with WWW-Authenticate: Bearer), and make mint-token prints a role-scoped dev JWT with its decoded claims.

Live demo (Module 2 — real Claude agents)

Requires a Claude Code login (the Agent SDK rides it) or ANTHROPIC_API_KEY in .env. A full run costs about $0.05 (the recorded run measured $0.0440). The demo boots the governed MCP server as a subprocess for the duration of the run, so its audit trail lands in the run directory next to the agents' telemetry.

make demo GOAL="Hire a Staff Engineer in Q3 for $190k"   # decompose → HR → Finance → pause
suite approve      # human gate → governed commit → CXO dashboard
suite deny  --reason "Budget freeze"             # ...or the denial path

suite demo runs the specialists and then exits at the approval gate: a terminal panel shows the decomposed request, the HR verdict (level and band check), the Finance verdict (remaining budget), and any flags — then waits for a human. State is persisted atomically, so approve/deny can run minutes or days later, from a different process. suite status and suite dashboard inspect any run.

No API key? The committed artifacts under [data/sample_runs/](data/sample_runs/) are real recorded runs of exactly these commands — both the approved and the denied path — and every offline test and forecast works against them.

Sample outputs

| Artifact | What it shows | Headline numbers | |---|---|---| | [examples/sample_dashboard.md](examples/sampledashboard.md) | CXO value dashboard from the approved live run | $0.0440 total cost [measured] · 82.8% cache-read fraction [measured] · ≈801x vs manual baseline [assumption] | | [examples/sample_blueprint.md](examples/sampleblueprint.md) | GSI Partner Blueprint — spend, cache scenarios, capacity | Year-1 at 10,000 seats: $9,849 measured-cache vs $22,697 uncached · tier2 · itpm bottleneck | | [examples/sample_forecast.json](examples/sampleforecast.json) | Machine-readable forecast with full assumptions registry | Same forecast, every input provenance-tagged | | [data/sample_runs/run_demo_approved/](data/sampleruns/rundemoapproved/) | Full approved run: telemetry, state, approval, ledger, dashboard | Commit led_b5343da61f79 · one trace_id across 3 caller roles | | [data/sample_runs/run_demo_denied/](data/sampleruns/rundemo_denied/) | Full denied run: finance flags insufficient budget | CC-4200: $50k remaining vs $190k ask · run ends failed with rationale |

See [examples/README.md](examples/README.md) for what regenerates each artifact.

Module map

| Module | Question it answers | Key paths | Design doc | Tests | |---|---|---|---|---| | 1 — Governed MCP Server | Can an agent be trusted with our data? | src/mcp_server/, src/core/policy/, src/core/tokens/ | [docs/mcp_architecture.md](docs/mcparchitecture.md) | test_mcp_http_e2e.py, test_http_auth.py, test_security_guardrails.py, test_redaction.py, test_mcp_tools.py | | 2 — A2A Workflow Orchestrator | Can agents run a real business process? | src/orchestrator/, src/reports/ | [docs/a2a_orchestration.md](docs/a2aorchestration.md) | test_engine.py, test_hitl_gate.py, test_a2a_schema.py, test_live_wiring_offline.py, test_value_dashboard.py | | 3 — Token & Cost Forecast Engine | What does it cost at 10,000 seats? | src/forecast/, config/, templates/ | [docs/forecast_methodology.md](docs/forecastmethodology.md) | test_forecast_math.py, test_blueprint_render.py, test_stats.py, test_parser.py | | Shared foundations | — | src/core/, src/telemetry/ | [docs/telemetry_contract.md](docs/telemetrycontract.md) | test_data_store.py, test_identity_scopes.py, test_token_issuer.py, test_telemetry_events.py |

Global views: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) (module boundaries, sequence diagram, execution model) · [docs/adr/](docs/adr/) (decision records) · [docs/GSI_PRACTICE_BLUEPRINT.md](docs/GSIPRACTICEBLUEPRINT.md) (what a partner practice takes from this) · [PRD.md](PRD.md) (the authoritative spec).

Repository layout

├── PRD.md                     # authoritative spec (v2)
├── Makefile                   # setup / test / ci / serve-mcp / demo / forecast targets
├── pyproject.toml             # single uv-managed distribution; console script `suite`
├── .github/
│   └── workflows/ci.yml       # lint + typecheck + offline tests + secrets scan (zero secrets)
├── config/                    # pricing, rate-limit tiers, benchmarks (all with as_of + source)
├── data/
│   └── sample_runs/           # committed real-run artifacts (approved + denied)
├── docs/
│   ├── ARCHITECTURE.md        # global ecosystem view
│   ├── mcp_architecture.md    # Module 1 deep-dive
│   ├── a2a_orchestration.md   # Module 2 deep-dive
│   ├── forecast_methodology.md   # Module 3 deep-dive (worked example)
│   ├── telemetry_contract.md  # normative event schemas
│   ├── GSI_PRACTICE_BLUEPRINT.md
│   └── adr/                   # architecture decision records
├── examples/                  # sample dashboard, blueprint, forecast.json
├── scripts/                   # secrets scan (runs in CI)
├── src/
│   ├── core/                  # data model, identity, redaction policy, JWT issuer
│   ├── telemetry/             # frozen event contract, writer, parser, stats
│   ├── mcp_server/            # Module 1: tools, auth middleware, governance pipeline
│   ├── orchestrator/          # Module 2: engine, A2A schema, HITL gate, SDK adapter
│   ├── reports/               # CXO value dashboard
│   ├── forecast/              # Module 3: pricing, forecast math, capacity, blueprint
│   └── cli/                   # `suite` console entrypoint
├── templates/                 # partner_blueprint.md.j2 (StrictUndefined)
└── tests/                     # 235 offline tests + 2 live-gated smoke tests

Runtime output (demo runs, generated forecasts) is written under runs/, which is gitignored — the curated copies live in data/sample_runs/ and examples/.

Engineering approach

• Spec first. The original PRD was reviewed for accuracy before any code: three technical errors were found (misnamed "encryption" that was actually redaction, HTTP-status semantics that don't exist in MCP, token accounting placed in a layer that can't observe tokens) and corrected in [PRD.md](PRD.md) — the v1→v2 changelog is Appendix A, and the original ships at [docs/prd_v1_original.md](docs/prdv1original.md).
• Contracts before construction. The cross-module interfaces (core/errors.py, telemetry/events.py, the A2A schema) were written and frozen first; every dependent module treats them as read-only.
• Gates at every milestone. Lint, type check, the full test suite, and a secrets scan pass before each milestone lands — CI runs the same gates with zero secrets configured.
• Adversarial review before publish. An independent security audit (including a full git-history secret scan) and an independent code review ran against the finished code. The review's best finding — the governed commit's idempotency key was proposed by the model rather than enforced — was fixed by having the permission callback rewrite the tool input deterministically, with a regression test.
• Live verification. The recorded runs under [data/sample_runs/](data/sample_runs/) are real executions against the real Claude API, driven from the terminal, with measured costs and cache rates committed unedited.

---

> Disclaimer. This is an independent portfolio project by Manish Moideen. It is not affiliated with, endorsed by, or connected to Workday, Inc. All data in this repository is synthetic; entity naming mirrors common HCM/Financials domain concepts for realism only, and no Workday trademarks, logos, or proprietary APIs are used. Built with the Model Context Protocol Python SDK and the Anthropic Claude Agent SDK. Licensed under [Apache-2.0](LICENSE) (see [NOTICE](NOTICE)).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mmoideen
• Source: mmoideen/enterprise-agentic-ai-suite
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.