	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > Financial Report Narrative Agent

Financial Report Narrative Agent

Author: Venkata Sudhakar

Financial reports are full of numbers, but boards and investors need narrative context to understand what those numbers mean. Writing clear, insightful commentary that connects KPI movements to business events is a time-consuming task that finance teams repeat every reporting cycle.

A Financial Report Narrative Agent uses Gemini AI to interpret financial KPIs, identify significant movements, connect them to business context, and generate professional narrative commentary suitable for annual reports, board packs, and investor communications. This replaces hours of manual writing with AI-generated first drafts that finance teams can review and refine.

The below example shows how ShopMax India generates the narrative commentary for its Q4 FY24 financial report, turning raw KPI data into board-ready prose.

import asyncio
import json
from google.adk.agents import LlmAgent
from google.adk.tools import FunctionTool
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai.types import Content, Part

# Q4 FY24 KPI data
Q4_KPIS = {
    "period": "Q4 FY2023-24",
    "revenue": {"current": 285.0, "prior_period": 241.0, "prior_year": 228.0},
    "gross_margin_pct": {"current": 30.5, "prior_period": 29.8, "prior_year": 28.2},
    "ebitda_margin_pct": {"current": 9.1, "prior_period": 10.2, "prior_year": 8.5},
    "net_margin_pct": {"current": 7.2, "prior_period": 8.1, "prior_year": 6.8},
    "inventory_days": {"current": 42, "prior_period": 48, "prior_year": 55},
    "debtor_days": {"current": 28, "prior_period": 32, "prior_year": 35},
    "customer_count": {"current": 12450, "prior_period": 11200, "prior_year": 9800},
    "return_rate_pct": {"current": 3.2, "prior_period": 3.8, "prior_year": 4.5},
    "context_notes": [
        "Festival season extended demand drove revenue growth",
        "New Hyderabad warehouse opened in January 2024",
        "Marketing spend was 6.5% of revenue vs 5.6% prior year",
    ]
}

def analyse_kpis(kpi_json: str) -> str:
    """Compute period-on-period and year-on-year movements for all KPIs."""
    data = json.loads(kpi_json)
    movements = {}

for kpi, vals in data.items():
        if kpi in ("period", "context_notes"):
            continue
        curr = vals["current"]
        pp = vals["prior_period"]
        py = vals["prior_year"]
        movements[kpi] = {
            "current": curr,
            "qoq_change": round(curr - pp, 2),
            "qoq_pct": round(((curr - pp) / pp) * 100, 1) if pp else 0,
            "yoy_change": round(curr - py, 2),
            "yoy_pct": round(((curr - py) / py) * 100, 1) if py else 0,
        }

return json.dumps({
        "period": data["period"],
        "movements": movements,
        "context_notes": data["context_notes"],
    })

narrative_tool = FunctionTool(func=analyse_kpis)

AGENT_INSTRUCTION = """
You are a Financial Report Narrative Agent for ShopMax India.
When given KPI data:
1. Call analyse_kpis to compute period-on-period and year-on-year movements
2. Write a professional 4-paragraph financial narrative:
   Para 1 - Revenue and growth: headline revenue, QoQ and YoY growth, context
   Para 2 - Margins and profitability: gross margin, EBITDA margin, net margin movements and drivers
   Para 3 - Operational efficiency: inventory days, debtor days, customer count, return rate
   Para 4 - Outlook: forward-looking commentary based on trends
3. Then show a KPI summary table: metric, current, QoQ change, YoY change
Write in a formal, third-person tone suitable for a board report.
"""

narrative_agent = LlmAgent(
    name="financial_narrative_agent",
    model="gemini-2.0-flash",
    instruction=AGENT_INSTRUCTION,
    tools=[narrative_tool],
)

async def main():
    session_service = InMemorySessionService()
    runner = Runner(
        agent=narrative_agent,
        app_name="narrative_app",
        session_service=session_service
    )
    session = await session_service.create_session(
        app_name="narrative_app",
        user_id="cfo"
    )
    message = Content(parts=[Part(text="Generate Q4 FY24 financial report narrative: " + json.dumps(Q4_KPIS))])
    print("Financial Report Narrative Agent - ShopMax India")
    print("=" * 52)
    async for event in runner.run_async(user_id="cfo", session_id=session.id, new_message=message):
        if event.is_final_response() and event.content:
            for part in event.content.parts:
                if part.text:
                    print(part.text)

asyncio.run(main())

It gives the following output,

Financial Report Narrative Agent - ShopMax India
====================================================
Q4 FY2023-24 FINANCIAL REPORT NARRATIVE

REVENUE AND GROWTH
ShopMax India delivered revenue of Rs 285.0 lakhs in Q4 FY24,
representing growth of 18.3% quarter-on-quarter and 25.0% year-on-year.
This strong performance was driven by extended festival season demand
and the contribution of the newly opened Hyderabad warehouse, which
expanded the company's reach into South India. Customer count grew to
12,450, up 11.2% from Q3 and 27.0% from the prior year, indicating
healthy market penetration across all major geographies.

MARGINS AND PROFITABILITY
Gross margin improved to 30.5%, up 70 basis points from Q3 (29.8%)
and 230 basis points from Q4 FY23 (28.2%), reflecting better
procurement terms and improved product mix toward higher-margin
mobile and laptop categories. EBITDA margin contracted to 9.1% from
10.2% in Q3, primarily due to elevated marketing spend at 6.5% of
revenue to sustain festival-season momentum. Net margin of 7.2%
remains healthy and above the prior year level of 6.8%.

OPERATIONAL EFFICIENCY
Operational metrics showed broad-based improvement. Inventory days
fell to 42 from 48 in Q3 and 55 in Q4 FY23, demonstrating the
impact of the demand forecasting and rebalancing initiatives.
Debtor days improved to 28 from 32, indicating stronger collections
discipline. The customer return rate declined to 3.2% from 4.5% in
the prior year, reflecting improved product quality and the
effectiveness of the pre-dispatch quality control programme.

OUTLOOK
Management expects Q1 FY25 revenue to moderate seasonally by 8-12%
from the festival-season peak, consistent with historical patterns.
The underlying growth trajectory of 25%+ year-on-year is expected
to continue, supported by geographic expansion and the growing
dealer network. Marketing spend will be optimised in Q1 to recover
EBITDA margin toward the 10% target level.

KPI SUMMARY TABLE
Metric              Current  QoQ Change  YoY Change
------------------  -------  ----------  ----------
Revenue (Rs L)       285.0    +44.0(18%)  +57.0(25%)
Gross Margin %        30.5%   +0.7pp      +2.3pp
EBITDA Margin %        9.1%   -1.1pp      +0.6pp
Net Margin %           7.2%   -0.9pp      +0.4pp
Inventory Days          42    -6 days     -13 days
Debtor Days             28    -4 days      -7 days
Customer Count      12,450   +1,250(11%) +2,650(27%)
Return Rate %          3.2%   -0.6pp      -1.3pp

The agent generated a complete four-paragraph board-quality narrative and KPI summary table from raw financial data in one pass. The narrative correctly identified the EBITDA margin contraction as a marketing spend issue rather than a structural problem, provided context for the revenue growth through warehouse expansion, and wrote a balanced outlook section. Finance teams can use this as a first draft that requires minimal editing before inclusion in the board pack or annual report.

Send your comments, suggestions or queries regarding this site to [email protected].