Agents Handbook
Agents Handbook is a governed, Colab-first suite for teaching agentic architectures in finance using LangGraph only. It is deliberately explicit about what it is not: it does not promise correct real-world facts, it does not claim deployability, and it does not treat generated outputs as verified evidence. Its purpose is more demanding and more useful: mechanism clarity under constraint. If you cannot explain how state, routing, gates, and bounded loops produce a decision, then “the model decided” is not a workflow. It is a liability.
Most agent demos over-teach clever prompts and under-teach the thing that matters in professional settings: control. Real finance workflows have missing information, suitability boundaries, evidence gaps, escalation paths, and stop rules. This repository makes that structure explicit. Every notebook is intentionally constrained to be reviewable: you can inspect the graph, audit the state transitions, and reconstruct why the system terminated where it did.
The architectural contract is consistent across the entire suite: explicit TypedDict state → AgentNode abstraction → conditional routing → bounded loops → termination logic → mandatory artifacts. Each run produces a compact audit trail that makes the workflow inspectable rather than persuasive: run_manifest.json, graph_spec.json, and final_state.json. Outputs are tagged Not verified by design until independently reviewed.
This is not “extra process.” This is what makes agentic work defensible.
What’s inside
The repository has two primary components. The handbook is the interpretive layer: mental models, failure modes, and governance posture. The notebooks are the execution layer: ten end-to-end LangGraph workflows that operationalize those concepts with explicit state, routing, and bounded iteration.
The Handbook (written layer)
Architecture notes and governance framing that explain what each workflow is doing, why the controls exist, and how to read the run artifacts as a reviewer. The goal is to prevent “graph theater” by making the control logic and failure modes legible.
Open Handbook FolderThe Notebooks (execution layer)
Ten Colab notebooks that implement canonical finance workflows as governed agent graphs. Each notebook uses LangGraph only and enforces an invariant: TypedDict state, conditional routing, bounded loops, early termination, and mandatory exported artifacts per run.
Open Notebooks FolderNon-negotiable artifacts
Every run exports a compact audit bundle that makes behavior reconstructible. This is the minimum standard for professional reviewability.
The Ten Finance Workflows (LangGraph-Only Colab Notebooks)
Each notebook is a finance objective mapped to an agentic pattern. The content is intentionally architecture-heavy: nodes, state transitions, gates, bounded loops, and termination reasons. This teaches how a real team would structure a governed workflow rather than how to “get an answer.”
CHAPTER 1 — Personal Finance Triage (Missing-Info Loop)
Intake and triage as a control loop: discover missing fields, request only what is necessary, and stop when sufficiency is reached or retries are exhausted. The point is disciplined information discovery with bounded iteration.
Open NotebookCHAPTER 2 — Suitability Boundary (Refuse / Redirect)
Hard branching and early termination for suitability and scope boundaries. Enforces a refusal posture where required and routes toward safer alternatives when appropriate.
Open NotebookCHAPTER 3 — Credit Memo Drafting (Evidence-Gap Critique Loop)
Drafting as governed synthesis: generate a memo, critique for unsupported claims, and iterate to surface evidence gaps. Outputs explicitly separate facts, assumptions, and open items to support review.
Open NotebookCHAPTER 4 — Trading Hypothesis + Backtest Wrapper (Tool-Augmented Node)
Hypothesis formation integrated with a test harness and diagnostics. The workflow treats backtests as diagnostics, not evidence, and forces a gate decision (promote / revise / reject).
Open NotebookCHAPTER 5 — Execution Tactics Under Liquidity (Regime Machine)
Stateful execution under changing liquidity/volatility regimes. Tactics adapt to regime while respecting bounded steps and explicit termination logic (pause, slow, slice, escalate).
Open NotebookCHAPTER 6 — Portfolio Rebalancing (Parallel Committee + Aggregation)
Multiple perspectives evaluate the same rebalance (risk, cost, constraints) in parallel. An aggregator reconciles outputs and records disagreements rather than hiding them.
Open NotebookCHAPTER 7 — IB Pitchbook (Hub-and-Spoke Constellation)
A hub coordinates section agents for comps, rationale, risks, and narrative cohesion. The hub enforces completeness checks and flags missing inputs rather than improvising certainty.
Open NotebookCHAPTER 8 — M&A Diligence Q&A (Router + Retrieval)
Route questions to the right sub-workflow, retrieve evidence, and answer with provenance. The workflow surfaces uncertainty and escalates when evidence is insufficient.
Open NotebookCHAPTER 9 — Treasury Monitoring (Event-Driven Workflow)
Covenant and liquidity monitoring as an event-driven agentic system. Detect breaches, produce escalation-ready outputs, and keep the run reconstructible for oversight.
Open NotebookCHAPTER 10 — Multi-Desk Research Synthesis (Supervised + Red-Team)
A supervised multi-agent synthesis workflow with an explicit red-team pass. The goal is not consensus; it is a publish gate supported by objections, gaps, and review hooks.
Open NotebookLicensing, Governance & AI Use Disclosure
Educational / Non-Reliance: All materials are provided for educational and research purposes only. Nothing here constitutes investment, trading, legal, tax, accounting, audit, compliance, or operational advice.
Not verified by default: Unless explicitly stated otherwise in a particular artifact, treat all outputs, claims, calculations, citations, and conclusions as Not verified.
Confidentiality and data hygiene: Do not paste confidential, proprietary, regulated, or personally identifying information into external systems. Use anonymization/redaction and minimum-necessary inputs by default.
AI use disclosure: Generative AI tools may have been used to assist drafting, editing, formatting, or code scaffolding. Conceptual design, governance decisions, and final approval are human-led. Responsibility remains with the human professional.