convez.ai
AgenteAutomaçãoAvançado
maxmoran23

Claude Agent Fleet

maxmoran23/Claude-Agent-Fleet

Framework para operar frotas de agentes autônomos, auto-reparáveis e com orçamento inteligente

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de produção para construir, agendar e operar frotas de agentes autônomos no Claude. Inclui kernel com autoridade de estado local, idempotência, auto-modificação controlada por humanos, gerenciamento JIT de orçamento de tokens e camada de dados SQLite. Acompanha seis agentes de referência executáveis (pesquisa, monitoramento de mercado, conformidade regulatória, saúde da frota) e 22 exemplos adicionais apenas de prompt.

Instalação

$npx convez-ai maxmoran23/Claude-Agent-Fleet

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 3 semanas
Versão
v1.5.0
Issues abertas
6
Contribuidores
2

Casos de uso

  • Automação de análise e síntese de dados em tempo real
  • Monitoramento regulatório e conformidade contínua
  • Coordenação de múltiplos agentes com persistência de memória
  • Análise de mercado e pesquisa cronometrada
  • Operações autônomas com self-repair e observabilidade

Veredito

Arquitetura robusta e pensada para produção, com implementação real de padrões críticos (idempotência, budgeting, auto-reparo). Exige conhecimento profundo de agentes e infra, mas oferece referência valiosa para sistemas multi-agente em escala. Documentação exemplar com runnable code.

README

A tradução para o português deste README ainda está na fila.

Claude Agent Fleet

ci python license

A production-grade framework for building, scheduling, and operating autonomous agent fleets on Claude. Self-repairing, self-budgeting, with runnable Python reference implementations.


What This Is

A reference architecture for operating multiple autonomous agents as a cohesive intelligence system — covering real-time monitoring, scheduled analysis, workflow automation, and operational self-maintenance. Designed around the idea that a structured natural language prompt executed on a schedule, with persistent memory and self-observability, is a production-viable software component.

Every agent is a structured natural language prompt executed on a schedule. Agents gather live data from external sources, maintain persistent memory across runs via Slack Canvases and a SQLite data layer, rate their own output quality, and — when something breaks — repair themselves without human intervention. A JIT budget manager monitors fleet-wide token consumption and autonomously throttles agent frequencies as resource limits approach, preserving output quality by reducing run count rather than degrading the model or prompt depth.

This repository documents the architecture, design decisions, and operational patterns. It also includes runnable Python reference agents wired to GitHub Actions so the scheduling and observability story is demonstrated end-to-end — not just described. Twenty-two additional agent specs are included in examples/ as prompt-only references — including a dedicated compliance-operations tier (control testing, risk register maintenance, sanctions-list monitoring, model governance, committee reporting, examination response) — and companion analytical dashboards in showcase/ illustrate the visual half of the output stack.


Running the Reference Agents

Six agents ship as runnable Python modules backed by the Anthropic Messages API, with GitHub Actions workflows for scheduled execution.

AgentScheduleOutput
research_digestDaily 11:00 UTCSynthesis of noteworthy AI/ML developments
market_monitorEvery 8hCrypto market snapshot + narrative
regulatory_oracleDaily 12:00 UTCDigital-asset and AML/CFT regulatory briefing
fleet_watchdogEvery 6hFleet health report from GitHub Actions run history
synthesis_engineDaily 01:00 UTCMeta-analysis across sibling agents' runs — themes, contradictions, gaps
sanctions_list_monitorDaily 22:15 UTCOFAC SDN list delta — additions/removals/modifications, severity-classified

Local

pip install -r requirements.txt
cp .env.example .env  # fill in ANTHROPIC_API_KEY, SLACK_BOT_TOKEN, SLACK_DEFAULT_CHANNEL
PYTHONPATH=. python agents/research_digest/agent.py

CI

Set these as repository secrets:

  • ANTHROPIC_API_KEY
  • SLACK_BOT_TOKEN
  • SLACK_DEFAULT_CHANNEL

The workflows under .github/workflows/ will then run on their cron schedules. ci.yml runs the test suite on every push.

Tests

pip install -e ".[dev]"
pytest

Why This Matters

Most approaches to "agent systems" fall into one of two failure modes:

  1. Monolithic prompts — a single agent with a giant prompt trying to do everything. Brittle, unobservable, hard to evolve.
  2. Orchestration-heavy frameworks — tightly coupled pipelines with complex state machines. High cognitive overhead for operators; cascading failures when any link breaks.

This framework takes a different path: loosely coupled agents that communicate through shared state, each following a common production pattern, collectively forming a self-observing and self-repairing system. The outcome is a fleet that can scale from 3 agents to 50+ without the operator rebuilding the orchestration every time, that fails gracefully rather than catastrophically, and that produces an audit trail of its own evolution.

The patterns here emerged from building and operating such a system in production — refined through cycles of iteration under real resource constraints and real operator attention budgets. Everything in this repository is battle-tested architecture, generalized for reuse.


Who This Is For

  • Builders designing their own agent fleets and looking for architectural patterns that have survived production pressure
  • Engineers evaluating how autonomous agent systems can be structured, observed, and maintained at scale
  • Compliance and fintech practitioners specifically — the examples skew toward regulatory, on-chain, and market-intelligence use cases because that's where the patterns were battle-tested
  • Claude Code users looking for reference implementations beyond single-agent examples
  • AI infrastructure engineers thinking about cost management, observability, and fault isolation in agent systems

If you're building a fleet of 3+ agents that need to run autonomously on a schedule and produce reliable output, this framework maps directly to your problem. If you're building a single agent or a one-shot tool, this is probably more framework than you need.


What It Does

The framework is built to operate an agent fleet across any domain. Illustrative use cases where this architecture has been applied:

DomainExample AgentsFunction
Crypto MarketsPrice monitor, macro sentiment, on-chain analytics, virtual portfolio manager, token discoveryReal-time data feeds synthesized into narrative intelligence
Regulatory / AMLEnforcement tracker, legislation watch, sanctions screening, deadline alertsCompliance landscape monitoring with structured severity scoring
ResearchPaper translation, cross-domain synthesis, topic discoverySignal extraction from high-volume research streams
WorkflowMeeting prep, email triage, channel summarization, interactive Q&AActive participation in day-to-day work
DeliveryConsolidated digest aggregator, calendar alerts, critical escalation routingMany-to-few notification consolidation
Fleet OpsHealth monitoring, self-repair, budget management, engagement tracking, meta-analysisThe fleet monitoring and maintaining itself
Execution ScaffoldingThreshold-triggered action packages (pre-filled drafts)Human-in-the-loop handoff where the agent does the prep work

Each category can be extended without touching the others — agents communicate through shared state stores rather than direct dependencies, so any agent can fail without cascading.


Architecture

┌──────────────────────────────────────────────────────────────┐
│                      DATA SOURCES                            │
│  Real-time prices  Social sentiment  On-chain data           │
│  Financial news  Market tearsheets  Email  Calendar          │
│  Government databases  Regulatory filings                    │
└────────────────────────────┬─────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────┐
│                        AGENT FLEET                           │
│                                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Analysis │ │ Real-    │ │ Daily    │ │ Workflow │       │
│  │  Engines │ │ Time     │ │ Briefs   │ │ Auto.    │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Fleet    │ │ Specialty│ │ Execution│ │ Maint.   │       │
│  │ Infra    │ │ Intel    │ │ Scaf.    │ │ Util.    │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│                                                              │
│  Each agent: Load State -> Gather -> Analyze -> Deliver ->   │
│              Update Dashboard -> Write Data Layer ->          │
│              Self-Rate -> Persist State                       │
│                                                              │
│  JIT Budget Manager: Watchdog monitors burn rate,            │
│  autonomously throttles frequencies across 4 priority tiers  │
└────────────────────────────┬─────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────┐
│                        OUTPUT LAYER                          │
│  Slack channels + canvases (primary backbone)                │
│  Consolidated digest emails (morning + evening)              │
│  Calendar (iOS push for deadlines)                           │
│                                                              │
│  Structured archive: SQLite data layer + Notion database     │
└──────────────────────────────────────────────────────────────┘

Full architecture documentation: ARCHITECTURE.md


Core Patterns

Thirteen architectural patterns form the foundation of the framework. Each has its own deep-dive documentation:

PatternWhat It Solves
State ManagementOne authority (local state files) + projections (canvases, SQLite) so agents have durable memory that platform limits can't silently destroy
Agent KernelVersioned contract + shared CLI helpers replacing per-agent boilerplate — pattern improvements stop being 70-file fan-outs
Fallback ChainsGraceful source degradation so no agent hard-fails and observability survives broken inputs
Quality Self-RatingAgents self-assess 1–10 per run, giving the operator a triage signal for what to read closely
Evaluation HarnessIndependent rubric scoring (0–100) of published output — drift detection and before/after evidence for upgrades
Idempotency OutboxClaim/confirm dedup so a retried agent never duplicates an email, post, or trade
Execution ScaffoldingThreshold-triggered pre-filled action packages — agents do the prep, humans approve
JIT Budget ManagementAutonomous throttle protocol that reduces run frequency under resource pressure (never quality)
Self-RepairFleet agents scan configurations, detect drift, apply safe fixes autonomously
Propose-and-GateHuman-gated self-modification — full diffs reviewed up front, one-commit rollback, an approval queue that doubles as the change-control log
Generated RegistryFleet inventory generated from primary sources, never hand-written — spec-vs-runtime drift surfaces in hours, plus out-of-band deadman liveness
Fleet EvolutionWeekly maturity assessment + bounded upgrade cycles with experiment tracking
Visual CardsDynamic PNG cards embedded in Slack output for at-a-glance dense information

Case Studies

End-to-end walkthroughs showing what the framework actually delivers:

Case StudyWhat It Shows
Regulatory Enforcement ResponseOFAC action breaks → oracle drafts brief → scaffold generates response kit → operator approves in minutes
On-Chain Sanctions HitMonitored address triggers alert → watchlist enriches with typology → critical escalation + incident response package
Daily Intelligence DigestSix agents consolidate into a single 500-word morning brief the operator reads in four minutes
Agent Self-RepairWatchdog detects degraded agent → auto-repair diagnoses → fix applied → validated — zero operator time

Showcase — Companion Analytical Surfaces

Static, single-file HTML dashboards that share the same domain focus as the agent fleet. Independent reference artifacts illustrating the visual half of the output stack — text intelligence from agents in agents/, visual surfaces for the operator in showcase/.

Live demos: maxmoran23.github.io/Claude-Agent-Fleet — both dashboards served via GitHub Pages, no clone required.

DashboardWhat It Is
Crypto AML Typology EngineReference library of 15 crypto AML typologies — sanctions evasion, money laundering, fraud — with detection rules and regulatory citations
Digital Asset Regulatory Intelligence TrackerFilterable view of the active digital-asset regulatory landscape — proposed legislation, agency rulemaking, enforcement actions

Crypto AML Typology Engine

See showcase/README.md for context, audience, and how the showcase relates to the agent fleet's output stack.


Example Agents

Twenty-two fully specified example agents, organized by complexity and domain. Each includes a complete AGENT.md with the full production pattern — state loading, data gathering with fallback chains, quality self-assessment, structured output, and state persistence.

Entry-level (demonstrates the basic production pattern)

AgentDomainDemonstrates
Research DigestAI/ML researchStructured prompt + severity-rated findings
Breaking News MonitorBreaking newsReal-time intelligence drops, Twitter-style brevity
Market PulseCrypto marketsMulti-source data aggregation, snapshot pattern

Intermediate (state management, multi-source, consolidation)

AgentDomainDemonstrates
Market MonitorCrypto marketsState deltas across runs, narrative synthesis
Regulatory OracleRegulatory/AMLCross-jurisdictional tracking, deadline awareness
Calendar AlertsCompliance deadlinesTime-sensitive routing to external calendar
Daily Intelligence BriefCross-domainMulti-agent consolidation, morning-digest synthesis
Meeting PrepWorkflowContext aggregation, attendee research

Advanced (sophisticated patterns)

AgentDomainDemonstrates
Fleet WatchdogFleet opsFleet self-monitoring, missed-run detection
On-Chain WatchlistBlockchain complianceAddress monitoring, sanctions screening, typology flagging
Synthesis EngineCross-agent metaCross-cutting theme detection, contradiction flagging
DeFi Protocol MonitorDeFi analyticsProtocol risk monitoring, TVL shift detection
Execution ScaffoldHuman-in-loopThreshold-triggered action packages, reaction schema
Fleet Auto-RepairFleet opsAutonomous self-healing, config scanning
Fleet QueryConversationalMulti-source retrieval, data-cited answers

Compliance operations (institutional assurance patterns)

Agent specs for the second-line and assurance side of a compliance program at a financial institution — the same production pattern applied to controls, governance, and regulatory response.

AgentDomainDemonstrates
Sanctions List MonitorSanctions complianceDaily list-delta detection, program classification, same-day escalation
Control TestingInternal controlsWorkpaper-grade test execution, exception tracking, remediation re-tests
Risk Register KeeperRisk managementLiving risk register, inherent/residual re-scoring, appetite breaches
Model Governance MonitorModel & AI governanceModel inventory, validation calendar, drift and override-rate signals
Committee Pack AssemblerGovernance reportingKPI/KRI aggregation, escalations, prior-action tracking
Exam Response CoordinatorRegulatory responseRequest register, evidence mapping, pre-submission QC
Compliance Intelligence HubCross-agent aggregationComposite pressure index, jurisdiction tiering, consolidated reporting

See QUICKSTART.md for deploying any of these as a Claude Code scheduled task.


Key Design Decisions

DecisionChoiceWhy
RuntimeClaude Code scheduled tasksAlways-on remote execution — no server, no laptop dependency
StateLocal state files as authority; canvases as display projectionsPlatform write limits can degrade a dashboard but never destroy memory; canvases stay human-readable
BoilerplateVersioned kernel contract + shared CLI helpersPattern improvements are one-file edits; choke-point validation kills silent drift
Historical dataSQLite append-only layerCanvases are dashboards (current state); SQLite is the ledger (what was true on date X)
CouplingZero file dependencies between agentsAny agent can fail without cascading — total fault isolation
InventoryGenerated registry, never proseEvery hand-written agent count is a future lie; drift is computed, not discovered
External sendsIdempotency outbox (claim/confirm)A retry after an ambiguous failure must never duplicate an email, post, or trade
DeliveryConsolidated multi-app pipelineSlack (backbone) + digest emails + calendar (iOS push)
ObservabilityFleet agents + out-of-band deadmanThe fleet monitors itself; one liveness check runs outside it so the monitor can't die with the monitored
Self-repairAutonomous for restore, gated for changeAuto-Repair restores declared state autonomously; changing declared state goes through propose-and-gate
BudgetJIT throttle protocol + declared model tiersReduce run frequency first; model changes only within each agent's declared policy tier, never silently

Production Pattern

Every agent follows the same execution cycle — documented in FLEET-OPS.md:

STEP 0        STEPS 1-5      STEP 6        STEP 6.5       STEP 7
Load State -> Execute ------> Deliver ----> Write Data --> Persist State
(local file   (gather,        (channels,    Layer          (local file,
 + run         analyze,        dashboards,   (SQLite)       then canvas
 history)      self-rate)      DB, email)                   mirror)

The mechanical steps (state load/persist, health footer, idempotency guard) are shared kernel helpers, not per-agent prose — see docs/patterns/agent-kernel.md.

Key properties enforced across every agent:

  • Fallback chains — every source has graceful degradation
  • Quality self-assessment — agents rate their own output 1-10, validated at a single choke point
  • Health footers — every output includes sources used, fallbacks triggered, quality score
  • Idempotent sends — non-idempotent actions (email, posts) pass through the claim/confirm outbox
  • Structured data bus — findings (severity >= MEDIUM) written to shared archive
  • Escalation routing — CRITICAL findings bypass normal channels, go direct to alerts
  • JIT-aware — agents operate within a budget-managed framework

Schemas & Reference


Repository Structure

Claude-Agent-Fleet/
├── README.md                             # This file
├── ARCHITECTURE.md                       # System design, state management, data flow
├── FLEET-OPS.md                          # Operational patterns, observability, self-repair
├── QUICKSTART.md                         # Deploy an example agent in 5 minutes
├── CONTRIBUTING.md                       # Contribution guidelines
├── CHANGELOG.md                          # Version history
├── CODEOWNERS                            # Default reviewer
├── LICENSE                               # MIT
├── pyproject.toml                        # Python project metadata + ruff/pytest config
├── requirements.txt                      # Runtime dependencies
├── .env.example                          # Template for local secrets
├── .pre-commit-config.yaml               # Formatting + lint hooks
│
├── fleet_core/                           # Shared library used by all runnable agents
│   ├── config.py                         # Environment-backed config loader
│   ├── runner.py                         # Anthropic Messages API wrapper
│   ├── publisher.py                      # Slack publishing helper
│   └── kernel/                           # Reference implementations of the kernel patterns
│       ├── state.py                      # Step 0/7 — atomic state load/persist, corruption quarantine
│       ├── outbox.py                     # Idempotency outbox — claim/confirm/fail protocol
│       └── eval_runner.py                # Evaluation harness — 0-100 rubric scoring
│
├── agents/                               # Runnable Python reference agents
│   ├── research_digest/                  # Daily AI/ML research synthesis
│   ├── market_monitor/                   # Crypto market snapshot + narrative
│   ├── regulatory_oracle/                # Daily digital-asset + AML/CFT briefing
│   ├── fleet_watchdog/                   # Fleet health via GH Actions run history
│   ├── synthesis_engine/                 # Meta-analysis across sibling agents
│   └── sanctions_list_monitor/           # Daily OFAC SDN list delta, severity-classified
│
├── showcase/                             # Companion analytical dashboards
│   ├── README.md                         # Positioning, audience, how to view
│   ├── images/                           # Screenshots embedded in main README
│   ├── crypto-aml-typology-engine/       # 15-typology AML reference library
│   └── regulatory-intelligence-tracker/  # Digital-asset regulatory landscape
│
├── tests/                                # 264 unit + integration tests (incl. examples lint)
│   ├── test_config.py
│   ├── test_runner.py
│   ├── test_publisher.py
│   └── test_agents.py
│
├── .github/
│   ├── workflows/                        # ci.yml, pages.yml + 6 scheduled agent workflows
│   ├── ISSUE_TEMPLATE/                   # Bug and feature templates
│   ├── pull_request_template.md
│   └── dependabot.yml                    # Weekly pip + actions updates
│
├── examples/                             # 22 prompt-only agent specs (AGENT.md format)
│   ├── research-digest/                  # Entry-level
│   ├── breaking-news-monitor/            # Entry-level
│   ├── market-pulse/                     # Entry-level
│   ├── market-monitor/                   # Intermediate
│   ├── regulatory-oracle/                # Intermediate
│   ├── calendar-alerts/                  # Intermediate
│   ├── daily-intelligence-brief/         # Intermediate
│   ├── meeting-prep/                     # Intermediate
│   ├── fleet-watchdog/                   # Advanced
│   ├── onchain-watchlist/                # Advanced
│   ├── synthesis-engine/                 # Advanced
│   ├── defi-protocol-monitor/            # Advanced
│   ├── execution-scaffold/               # Advanced
│   ├── fleet-auto-repair/                # Advanced
│   ├── fleet-query/                      # Advanced
│   ├── sanctions-list-monitor/           # Compliance operations
│   ├── control-testing/                  # Compliance operations
│   ├── risk-register-keeper/             # Compliance operations
│   ├── model-governance-monitor/         # Compliance operations
│   ├── committee-pack-assembler/         # Compliance operations
│   ├── exam-response-coordinator/        # Compliance operations
│   └── compliance-intelligence-hub/      # Compliance operations
│
├── docs/
│   ├── patterns/                         # 13 deep-dive pattern docs
│   ├── case-studies/                     # 4 end-to-end case studies
│   └── examples/                         # Structural references
│
└── schemas/                              # 4 schema & reference docs
    ├── data-layer.sql
    ├── slack-canvas-structure.md
    ├── notion-intelligence-feed.md
    └── agent-skill-frontmatter.md

Production agent configurations, skills libraries, serverless endpoints, and operational data built on top of this framework are maintained separately.


About

This framework emerged from building and operating a production autonomous agent fleet at the intersection of crypto/AML regulatory work and hands-on AI agent system design. The compliance background shapes how the framework is structured — audit-defensible documentation, structured severity frameworks, escalation protocols, and systematic evidence-based analysis are native operating principles, not afterthoughts bolted onto an AI project.

Actively used in production and continues to evolve.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados