Visual Studio Learn

Does the 118K-Star AI Trading Agent Actually Work? I Installed and Tested TradingAgents v0.7.1 — Open-Source Agent, Tested #1

2026-10-31T15:33:09.149-04:00

Search description: I installed TradingAgents v0.7.1 — the 118K-star multi-agent trading framework — and tested it for real. Setup, keys, errors, honest verdict.

Labels: Python, AI Agents, Open Source, Tutorials

Versions used in this post — read this first: TradingAgents v0.7.1 (release tag, commit c4544913a14ed3df5f1ed7b9e8483270ce20682a — the exact code tested here) · Python 3.12.3 (the project requires Python 3.11 or later) · Repository figures — 118,913 stars, 22,731 forks, 884 watchers — read from the project's GitHub page on October 31, 2026; this repository gains hundreds of stars a day, so treat those numbers as a dated snapshot, not a permanent fact. Licence: Apache-2.0.

A framing note before anything else. TradingAgents describes itself, in its own documentation, as a framework "designed for research purposes" that "is not intended as financial, investment, or trading advice." This post holds it to exactly that standard. This is an engineering test — install it, run it, read what it produces — not a recommendation of any stock, strategy, or tool for real money. The framework's approved orders go to a simulated exchange. Nothing here is financial advice.

The direct answer

TradingAgents is a free, open-source Python framework that splits stock analysis across a team of LLM agents modelled on a trading firm: four analysts research in parallel, two researchers debate the evidence bull-versus-bear, a trader proposes a decision, and a risk check plus a portfolio manager can approve or reject it. It installs with a clone, a virtual environment, and one pip install . — on the machine used for this test that install finished cleanly, with no errors, and the command-line help runs before any API key exists. The one thing you must supply yourself is a language model: a provider API key, a ChatGPT Plus/Pro sign-in, or a local model.

And the test result, up front, because this series does not bury it: the full pipeline did run end to end — but it took five attempts to get one complete run, and every failure was a lesson (one quirk of my test machine, one dropped connection, and two hard lessons about free-tier API quotas). When it completed, the framework analysed NVIDIA as of October 9, 2026, debated it properly, and issued a decision — Overweight, buy the dip, with a strict stop-loss. The stock then fell straight through that stop within a week. The framework's directional call was wrong; its risk discipline was the most valuable thing it produced. The full evidence is below.

What this test is (and is not)

This is the pilot episode of Open-Source Agent, Tested, a series with three fixed rules:

The version is pinned. Every claim below is about v0.7.1 at the commit named above. If the project has released something newer by the time you read this, the post says so rather than quietly drifting.
The run is real. The install log, the errors, and the output shown here come from an actual session on an actual machine — not from the project's documentation. If something fails, the failure is the result and it gets reported as one.
The verdict is honest. Star counts measure popularity, not quality. The end of this post separates what is genuinely well-built from what is demo-grade, and says who should bother.

What it is not: a trading strategy, a signal service, or a promise. See the framing note above.

Meet the framework: a firm, not a chatbot

Most "AI stock tools" are one model answering one prompt. TradingAgents instead divides the labour the way a trading firm divides it:

Analyst Team — four specialists who work in parallel:
Fundamentals — the company's financials.
Sentiment — news headlines, StockTwits, and Reddit.
News — global news and macroeconomic events.
Technical — chart indicators such as MACD and RSI.
Researcher Team — two researchers take the analysts' reports and argue: one builds the bullish case, the other builds the bearish case. The debate is the point — a claim has to survive an opponent before it travels further.
Trader Agent — reads the reports and the debate, then composes a concrete proposal: timing and position size.
Risk Management and Portfolio Manager — the proposal is checked for volatility and liquidity risk, and the Portfolio Manager makes the final call: approve or reject. Only an approved order reaches the (simulated) exchange.

That pipeline — specialists gather, opponents argue, a gatekeeper decides — is the design being tested here. Everything else in this post is setup, evidence, and verdict.

Environment setup — do this first

Prerequisites:

Python 3.11 or later. This test used Python 3.12.3. Check yours before anything else:

bash python3 --version

If it prints 3.10 or lower, install a newer Python first (from python.org, or your OS package manager) — the project's requirement is 3.11+, and the steps below were verified on 3.12.3. - Git, to clone the repository. - A language-model route (covered in its own step below — do not skip it; the analysis cannot run without one).

Step 1 — clone the repository and pin the tested version:

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
git checkout v0.7.1

Checking out the tag prints Git's "detached HEAD" notice. That is informational, not an error — it simply confirms you pinned a release tag instead of following the moving main branch. For a test like this one, the pin is what you want: everyone reading this post can reproduce the exact code.

Step 2 — create a virtual environment and install:

python3 -m venv .venv
source .venv/bin/activate
# Windows PowerShell: py -m venv .venv ; .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install .

(Prefer uv? The project also documents uv venv --python 3.13 followed by uv pip install .. Prefer Docker? It documents docker compose run --rm tradingagents with your keys in a .env file. All three routes install the same v0.7.1 code.)

What actually happened on this test machine: Python 3.12.3 on Linux, pip install . completed successfully in roughly four and a half minutes. No errors — none. That is worth stating plainly, because a clean first install is not the open-source default, and this post will not invent friction that did not occur.

Step 3 — verify the install (no key needed yet):

tradingagents --help

This prints the CLI's options and its three subcommands (backtest, login, logout). Notably, it runs with no API key configured — the help does not ask for one. The key only becomes necessary when you run an actual analysis, which is the next step.

Step 4 — give it a language model (zero assumed setup).

An analysis run needs an LLM. The framework accepts several routes; pick ONE:

A provider API key — OpenAI, Google, Anthropic, xAI, DeepSeek, DashScope, Zhipu, MiniMax, OpenRouter, Mistral, Moonshot, Groq, NVIDIA, and others are supported. Keys go in a .env file in the project folder (see below), never in code you commit or share — a key is a password, and anyone who has it can spend your money.
Google / Gemini walkthrough (the route this test used): 1. Go to aistudio.google.com and sign in with a Google account. 2. Open Get API key and choose Create API key (create or pick a Google Cloud project when prompted). 3. Copy the key Google shows you. You will not be able to view it again in full later — save it directly into your .env file (next step), not into a note you might share. 4. Billing note: this test ran entirely on the free tier and cost $0 — but read the run section before assuming free is painless. The Gemini free tier meters requests per day, per project, per model (20 requests/day for gemini-3.8-flash; 15/day for gemini-3.5-flash-lite, at the time of this test), and a single multi-agent analysis makes dozens of model calls. The free tier is a real constraint, not a footnote.
ChatGPT-subscription sign-in (no API key at all) — new in v0.7.0: if you already pay for ChatGPT Plus or Pro, run

bash tradingagents login chatgpt

and sign in with that plan. (tradingagents logout revokes the machine's access again.) - A local model — an Ollama or other OpenAI-compatible local server works too, if you would rather nothing leaves your machine. Expect slower, weaker analysis from small local models; the framework cannot fix a model that cannot reason.

Create the .env file in the project folder with the key(s) for the route you chose, following the variable names in the project's own .env example. Keep this file out of Git — it is listed in the project's ignore rules for a reason.

Step 5 — optional data keys.

Three optional keys unlock extra data sources: FRED (macroeconomic data), Alpha Vantage (market data), and TypeSafe (sentiment screening). None is required for a first run. This test ran without the optional keys, and the effect is visible in the run below: the framework logged that FRED macro data was unavailable and carried on. Add them later, one at a time, so you can tell which source changed the output.

How a run works

A run is a single command. The flags most people need:

tradingagents --ticker NVDA --date 2026-09-26 --analysts market,news --save --no-show

--ticker — the symbol to analyse (for example NVDA, or 0700.HK for a Hong Kong listing).
--date — the analysis date, YYYY-MM-DD. A past date is the honest way to test: the framework can only use information available up to that date, and you can compare its decision against what the price actually did afterwards.
--analysts — a comma-separated subset of the analyst team (for example market,news); omit it to run the full team.
--save / --no-show — save the full report to disk without interactive prompts; --html also writes the complete report as a single HTML page, which is the comfortable way to read the whole debate afterwards.
--portfolio — a JSON file of current holdings and cash, so the trader, risk, and portfolio agents size decisions against an actual position instead of a blank slate.
--checkpoint — saves state after each step so a crashed run can resume instead of starting over. Note this test's experience in the Errors section: in our session, the checkpoint resume did not pick up and the run restarted from zero. Budget your API requests accordingly.

A separate backtest subcommand scores past decisions across a grid of tickers and dates.

Under the hood, one run walks the pipeline from "Meet the framework" in order: analysts in parallel → researcher debate → trader proposal → risk evaluation → portfolio manager's approve/reject → (simulated) fill. Two details from the v0.7.1 release notes deserve attention, because they are correctness fixes of exactly the kind a hype video skips: decisions are now scored only on final closing prices, settlements are handled across long market holidays, and a model-date bug that could let the system read company filings dated after the run date — in plain terms, peek at the future — is fixed. A framework that patches look-ahead bias is taking backtesting seriously.

The test run

The protocol, fixed before any output was seen: one well-known ticker (NVDA), one analysis date in the past (Friday, October 9, 2026 — chosen so the framework only had information available that day, and so its decision could be scored against the real prices that followed), the full four-analyst team, one researcher debate round and one risk round, the complete report saved, and cost and duration measured. Three questions to answer: does it run end to end, does the debate change anything, and what does it cost?

What it actually took: five attempts in 24 minutes. The failures are part of the result, and each one is detailed in the Errors section below. In short: attempt 1 died in 7 seconds on a proxy quirk of my test machine; attempt 2 ran ten minutes, completed the analysts and the whole debate, then died at the Research Manager when the Gemini connection dropped; attempt 3 repeated that run and died at the same desk on the free tier's daily quota (20 requests/day for the deep model); attempt 4 tried a checkpoint resume, which did not resume, and died 33 seconds in on the other model's quota (15/day); attempt 5 switched to two untouched free-tier models — gemini-3.5-flash for the deep-thinking agents, gemini-3.1-flash-lite for the quick ones — and completed the entire pipeline in 107 seconds, exit code 0. Everything below is from attempt 5's saved report. Measured cost: $0 — every attempt ran on the free tier. The real currency was quota, not money.

What each stage produced (analysis date Oct 9, 2026; NVDA closed that day at $229.28):

Market analyst — uptrend intact, momentum cooling. Price above the 50-day average ($221.94) and the 200-day ($201.82) says the structure is bullish; but the MACD histogram has narrowed to 0.118, price dipped below the 10-day EMA, and RSI is a neutral 53. Flagged a possible re-test of support at $226.73.
Fundamentals analyst — strongly bullish. Quarterly revenue of $96.2 billion, net income of $59.7 billion, over $74 billion of operating cash flow in the first half of the year, $22.4 billion in cash. Its own caveat: growth this large cannot compound forever — watch for deceleration.
Sentiment analyst — neutral, 5.0 out of 10, confidence low — because it had no data. For a historical window, its sources (news headlines, StockTwits, Reddit) returned nothing usable — Reddit's feed was blocked outright (HTTP 403) during these sessions — and the report says exactly that instead of inventing a mood. Honest, and a genuine limitation: sentiment data does not do history, so past-date tests fly blind on this desk.
News analyst — themes, disclosed gaps. Real-time news and macro feeds were unavailable (no FRED key configured; the framework logged the fallback and continued), so the report framed NVDA around AI spending, the Fed's rate path, supply chains and geopolitics — and disclosed the missing data up front.
The debate — the bear nearly won the room. The bull argued the moat (an ecosystem hyperscalers cannot abandon), the fortress balance sheet, and a healthy consolidation above both moving averages. The bear argued a blow-off top: hyperscalers are building their own silicon precisely to break NVIDIA's pricing power, growth on a $96 billion base is mathematically near-impossible to sustain, capex cycles always turn — and if $226.73 and $221.94 break, momentum selling follows. The Research Manager sided with the bull (financial dominance is current fact; the bear's case is a future risk) but adopted the bear's warning levels as the trade's entry zone and stop.
Trader — BUY. Entry $226.73, stop-loss $218.00, size 1.25× standard.
Risk debate — the numbers got moderated. The aggressive analyst wanted the full 1.25× ("the real risk is opportunity cost"). The conservative wanted 0.5–0.75× (a stop is only as good as the liquidity that fills it in a fast drop). The neutral proposed the compromise: keep the buy, size at 1.0×, and widen the stop to $215 — at $218, the stop sits less than 1.5× the daily volatility (ATR 5.68) from entry, close enough for ordinary noise to trigger it.
Portfolio Manager — final decision: OVERWEIGHT. Enter between $226.73 and $221.94, size 1.0×–1.25×, stop-loss $215–$218, horizon 3–6 months, no price target. Compare it with the Trader's proposal and you can see the debate's fingerprints: both single numbers became ranges — the neutral risk analyst's compromise, adopted.

The decision vs. reality. NVDA's actual closes after October 9 (Yahoo Finance data): $226.32 on Oct 12 — inside the buy zone, so the entry triggered on the first trading day. $221.30 on Oct 14 — below the zone, and below the 50-day average the thesis stood on. $217.23 on Oct 15 — inside the decision's own stop-loss band; a rules-following holder exits there. $214.13 on Oct 16 — below the whole band; the exit is complete, at roughly −4% to −6% depending on the entry fill. The slide continued: $204.64 by Oct 30, −10.7% from the analysis-date close. The bear's fragility warning is almost literally what happened next.

So the scoreboard is split, and this post reports both halves: the directional call was wrong — the stock broke the support the thesis rested on within four trading days — and the stop-loss was the most valuable line in the decision, because obeying it cut the loss roughly in half versus holding (−4% to −6% out versus −10.7% by month's end). One run, one ticker, one date: an observation about what this framework did here, not evidence of a repeatable edge or a repeatable failure rate.

Errors you may hit

Every error below was actually observed during this test (install errors: none — the install was clean), with the exact text where it matters. They fall into three buckets, and the bucket matters: framework behaviour, my machine, and the model provider's free tier.

Bucket 1 — provider free-tier quotas (the wall you are most likely to hit):

Daily request quota exhausted — 429 RESOURCE_EXHAUSTED. Observed in attempts 3 and 4. The Gemini API free tier allows 20 generate requests per day, per project, per model for gemini-3.8-flash, and 15 per day for gemini-3.5-flash-lite. Attempt 3's error named the limit exactly ("Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 20, model: gemini-3.8-flash") and quoted a retry delay of 52,503 seconds — about 14.6 hours, i.e. "tomorrow." A multi-agent analysis makes dozens of calls, so a free-tier day can be spent by a single deep run plus retries. Fixes: spread your runs across models (each model has its own bucket — that is what saved attempt 5), wait for the daily reset, or enable a paid tier and watch the per-run cost instead.
Model at capacity — 503 UNAVAILABLE. Observed in attempt 3, immediately before the quota error: "This model is currently experiencing high demand. Spikes in demand are usually temporary." The framework retried the step in a different mode (free text instead of structured output) on its own — good behaviour — but the retry is what met the quota wall. Fix: wait and retry; the framework already does the graceful part for you.
Provider connection drop — RemoteProtocolError: Server disconnected without sending a response. Observed in attempt 2, at the Research Manager, after ten minutes of completed analyst and debate work. The framework's one automatic free-text retry hit the same drop. Fix: re-run. This is also the practical case for --save and saved partial reports — attempt 2's completed stages were on disk, not lost.

Bucket 2 — framework behaviour worth knowing before you budget requests:

Checkpoint resume did not resume (observed, attempt 4). The resumed run restarted from the beginning instead of picking up attempt 3's saved state, and promptly re-spent requests against a fresh quota wall. Treat --checkpoint as a seatbelt you should still test on your own setup, not as a guarantee — and do not plan a quota-tight session assuming resume will save you.
Data vendors fail, and the framework carries on (observed, attempts 2 and 5). Yahoo Finance's news feed timed out twice in attempt 2 ("Vendor 'yfinance' unavailable for get_news: Yahoo Finance request failed: Timeout; trying next vendor."), Reddit's RSS returned "HTTP Error 403: Blocked" for the sentiment feeds, and the unconfigured FRED source was skipped with a logged note in attempt 5. In every case the run continued with the remaining sources, and the affected analysts disclosed the gap in their reports rather than papering over it. That is the framework behaving well — but know that a past-date analysis will have a blind sentiment desk.

Bucket 3 — my machine (probably not yours):

httpx InvalidURL crash at startup — ValueError: invalid literal for int() with base 10: ':1]'. Observed in attempt 1; the run died in 7 seconds before any analysis. Cause: this test machine's proxy environment sets a NO_PROXY value containing a bracketed IPv6 address, and httpx's URL parser chokes on it. Framework: innocent. Fix on a similarly proxied machine: clear NO_PROXY/no_proxy from the run's environment. If your machine has no such proxy variables, you will never see this.

And the basics, verified during setup:

No LLM provider configured when starting an analysis. The help command runs fine without a key, but an unattended analysis start stops with exactly this: "GOOGLE_API_KEY is not set; there is no terminal to ask for it." (The provider named is whichever one you selected.) Fix: complete Step 4 — add the key to your .env or finish the ChatGPT sign-in — then re-run.
Python older than 3.11. The project requires 3.11+. This test ran 3.12.3 throughout, so the old-Python failure itself was not reproduced here; the requirement is the project's own, stated up front. Fix: install Python 3.11 or newer and rebuild the virtual environment from Step 2.
"Detached HEAD" notice when checking out v0.7.1. Observed during this test's install. It looks like a warning and reads like a problem; it is neither. Git is telling you a tag — a fixed point — is checked out instead of a branch. For reproducing a tested version, that is the goal. No fix needed.
A provider key in the wrong place. Keys belong in the .env file or your environment — not pasted into a command you later screenshot, and never committed. If a key leaks, revoke it at the provider and issue a new one; treat it like a lost password, because functionally it is one.

The verdict

Judged against the three questions this series fixed before the run:

1. Did it run end to end? Yes — on the fifth attempt, flawlessly. The completed run walked the whole firm — four analysts in parallel (19.9s, 12.4s, 20.6s and 18.5s of wall time on their stages), a real debate, a trader, a three-way risk argument, and a portfolio decision with entry, size, stop and horizon — in 107 seconds, unattended, with a complete saved report. The four failures were not the framework's code: one was my machine's proxy quirk, one a dropped provider connection, two the free tier's daily quotas. But "eventually" is part of the grade: a tool you test for free will spend your day in request quotas, and its checkpoint resume did not rescue us when we needed it.

2. Did the debate change anything? Yes — measurably, in the final numbers. The research debate set the direction: the manager heard the bear's structural case and ruled for the bull, on current financial dominance — while adopting the bear's break-levels as the entry zone and stop. The risk debate then moderated the trade itself: the Trader's single 1.25× size and $218 stop came out of the Portfolio Manager as ranges — 1.0×–1.25× and $215–$218 — the neutral analyst's compromise, adopted verbatim in spirit. The final decision is not the document any single agent proposed. That is the strongest evidence that the multi-agent structure is doing work a single prompt does not.

3. What did it cost? $0 — and a day's quota. On the free tier, one deep analysis can consume a model's entire daily allowance (20 requests for the deep model here). Budget accordingly: free is a planning exercise, paid is a per-run line item — and at 107 seconds of pipeline time, the paid version of this test would be cheap in wall-clock terms.

What is genuinely well-built: the install (clean, pinned, honest separation between browsing and spending); agents that disclose missing data instead of fabricating it (the sentiment desk's "we have no data, therefore neutral, low confidence" is the single most trustworthy paragraph in the report); vendor fallbacks that keep a run alive; release hygiene that patches look-ahead bias.

What is demo-grade, today: historical sentiment is effectively absent, so past-date tests — the honest kind — run with one desk blind; the news desk without optional data keys works from themes, not facts; checkpoint resume failed its one live test; and the flagship decision this framework produced was directionally wrong within a week, saved from embarrassment only by its own stop-loss. None of that makes it a toy. All of it makes it a research instrument whose output you verify — which is, to be fair, exactly what its authors claim.

Who should bother: developers and technically comfortable investors who want to see multi-agent orchestration do real work on a real problem, and who will treat the output as a structured second opinion to be checked — starting with its stop-loss. Who should not: anyone looking for a signal to trade on. The framework's own documentation told you that before I did.

Get the code

Companion code for this episode — the exact commands, environment notes, and run configuration used here, in the channel's public code repository: https://github.com/sajjad037/visual-studio-learn-code/tree/main/topic-06-tradingagents-tested
The project under test (credit: Tauric Research): https://github.com/TauricResearch/TradingAgents — star it there, not here, if the test convinces you.

Sources

TradingAgents repository (repo page: description, framework overview, installation and CLI documentation; star/fork/watcher counts as of October 31, 2026): https://github.com/TauricResearch/TradingAgents
TradingAgents releases page (v0.7.1 and v0.7.0 release notes — scoring on final closes, long-holiday settlement, model-date fix; ChatGPT-subscription provider, backtest scoring, release wheels): https://github.com/TauricResearch/TradingAgents/releases
This test's own install log and run logs (Python 3.12.3; pip install .; five run attempts with verbatim error text; the completed attempt's full report bundle), recorded October 31, 2026, summarised in the setup, run and errors sections above.
Post-run NVDA daily closing prices, Yahoo Finance chart data, fetched October 31, 2026.

Reminder, in the project's own spirit and this series' rules: TradingAgents is a research framework. This post is an engineering test report — not financial, investment, or trading advice.

Enjoying these tutorials?

Get new Visual Studio Learn posts by email — free, no spam:

Follow along: YouTube · Facebook · RSS

How Do I Deploy a FastAPI App to Azure App Service? Step by Step, From Zero

2026-10-29T16:27:21.679-04:00

Versions used in this post — read this first: Python 3.12.3 · Azure CLI 2.91.0 · fastapi 0.162.0 · uvicorn 0.54.0 · gunicorn 26.2.0 · uvicorn-worker 0.4.0 · App Service runtime PYTHON:3.12. Everything runs from one file, main.py, printed in full below — the exact file in the companion repo. Recorded October 2026; the free-tier limits and prices below are Microsoft's published figures as of that date.

The direct answer

Deploy a FastAPI app to Azure App Service, step by step, on the free tier: put the app in a folder with requirements.txt at the root, create a resource group, a free (F1) App Service plan, and a Python 3.12 web app, set two app settings, deploy a zip of the code, and — the step most tutorials skip — set the startup command. On Python 3.13 and earlier, App Service auto-detects Django and Flask only; a FastAPI app with no startup command doesn't error, it silently serves a built-in default page. The startup command is one line, and this post explains every piece of it. At the end your app answers at https://vsl-info-api.azurewebsites.net — for $0, with a delete command that removes everything when you're done.

The finished thing first

Before any setup, here is what the finished deployment looks like. One small FastAPI app — an “App Service Info API” — answering from Azure at https://vsl-info-api.azurewebsites.net:

https://vsl-info-api.azurewebsites.net/ — a hello message plus where the code is running: environment: "production", hostname: "vsl-info-api.azurewebsites.net". The same code on your own machine answers "local" — that before/after contrast is the whole demo.
https://vsl-info-api.azurewebsites.net/greet/YourName — a personalised greeting, proving routing and path parameters survived the trip.
https://vsl-info-api.azurewebsites.net/health — status: "ok" plus the Python version and current UTC time, the endpoint you hit to prove the app is really up.

The deploy itself took about 2 minutes 40 seconds from zip upload to live answers, on the free F1 plan. Now, rewind.

Azure portal overview of the vsl-info-api web app, status Running, on the free F1 plan.

What you will build

A deployment-check API — one file, main.py, three endpoints, no database, no secrets. Nothing to leak on a screenshot.
The deploy — resource group, free plan, web app, app settings, zip deploy, startup command, verification from the browser and the log stream.
The shortcut — az webapp up, the one command that does the whole creation-and-deploy in one go, shown after the long way so you know what it did.
The cleanup — one command that deletes everything, and the honest note that this post's own resources were deleted after filming.

Environment setup — do this first

Prerequisites: Python 3.12 (this post uses 3.12.3), a terminal, and an Azure account. The free account is enough; everything here runs on the free F1 tier and costs $0.

Create the Azure free account, click by click:

Go to azure.microsoft.com/free and choose Try Azure for free.
Sign in with a Microsoft account or a GitHub account (create one if you don't have one).
Fill in the profile details.
Identity verification: a phone number and a credit card or non-prepaid debit card. The card is only checked for identity — a ~$1 temporary authorization hold may appear and is removed. You are charged nothing unless you later choose pay-as-you-go pricing.
Accept the agreement and finish.

The offer, as Microsoft documents it: a US$200 credit for your first 30 days, plus amounts of popular services free for 12 months (and some always free). If you don't upgrade within 30 days, or when the credit runs out, the account and services are disabled until you do — nothing keeps billing in the background. This tutorial never needs the credit at all: the F1 plan is $0, and the free account exists here only as the door in.

Install the Azure CLI, then sign in:

Install the Azure CLI for your operating system from Microsoft's install page (learn.microsoft.com — “Install the Azure CLI”), then verify and sign in:

az --version        # expect azure-cli 2.91.0
az login            # opens a browser sign-in — complete it there
az account show     # read this output: it names the subscription
                    # you are actually about to deploy to

Two optional checks while you're here. The authoritative list of Python runtimes App Service currently offers is a command, not a page — run it and note that PYTHON:3.12 is in it:

az webapp list-runtimes --os-type linux --runtime python --output table

(At this post's production run, on October 28, 2026, the Python rows of that output were PYTHON|3.15, PYTHON|3.14, PYTHON|3.13, PYTHON|3.12, and PYTHON|3.11, all Active, plus PYTHON|3.10, marked Near end of life (support ends 2026-10-31). The list moves — run the command rather than trusting any printed copy, including this one.)

Create the Python environment and run the app locally first:

mkdir fastapi-info && cd fastapi-info
python3 -m venv .venv && source .venv/bin/activate
# Windows PowerShell: py -m venv .venv ; .venv\Scripts\Activate.ps1
pip install -r requirements.txt

(The code goes in this folder as main.py and requirements.txt — both printed in full below, and the companion repo has them as ready-made files.)

uvicorn main:app --reload

Open http://127.0.0.1:8000/ — it answers "environment": "local", "hostname": "localhost". Try /health and /greet/YourName too. Do not skip the local run: it separates “my code is broken” from “my deploy is broken” before Azure is involved. The local run for this post, real output:

{"app":"App Service Info API","message":"Hello from FastAPI","environment":"local","hostname":"localhost"}

Verify-it-works checkpoint: local app answers at http://127.0.0.1:8000/, and az account show names the subscription you intend to use. Both on screen before you touch Azure's portal.

The app — one file, three endpoints

"""App Service Info API: the smallest app that proves a deploy worked.

Companion code for the Visual Studio Learn post and video
"How Do I Deploy a FastAPI App to Azure App Service? Step by Step,
From Zero".

This one-file FastAPI app exists to make deployment concepts visible:

- GET /        reports where the code is running. It reads the
               APP_ENVIRONMENT app setting (which we set to
               "production" in Azure) and WEBSITE_HOSTNAME, a variable
               App Service defines automatically. Locally, with neither
               set, the same code answers "local" — the before/after
               contrast is the whole demo.
- GET /health  status, the Python version, and the current UTC time:
               the endpoint you hit to prove the app is really up.
- GET /greet/{name}
               a personalised greeting — proof that routing and path
               parameters survived the trip to the cloud.

Requires: Python 3.10 or newer and the packages in requirements.txt.
Run locally:  uvicorn main:app --reload
In Azure it is served by Gunicorn with the Uvicorn worker class — see
startup.txt, which holds the exact command the post sets in App
Service.
"""

import logging
import os
import platform
from datetime import datetime, timezone

from fastapi import FastAPI

logger = logging.getLogger("info_api")
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")

app = FastAPI(title="App Service Info API")


def environment() -> str:
    """Where this process believes it is running.

    APP_ENVIRONMENT is an ordinary app setting: unset locally (so the
    default "local" answers), set to "production" in Azure.
    """
    return os.environ.get("APP_ENVIRONMENT", "local")


def hostname() -> str:
    """The site's public hostname, when the platform provides one.

    App Service auto-defines WEBSITE_HOSTNAME for every web app.
    Locally it does not exist, so the honest answer is "localhost".
    """
    return os.environ.get("WEBSITE_HOSTNAME", "localhost")


@app.get("/")
def read_root() -> dict:
    """Say hello, and say where from — the deploy's proof page."""
    return {
        "app": "App Service Info API",
        "message": "Hello from FastAPI",
        "environment": environment(),
        "hostname": hostname(),
    }


@app.get("/health")
def health() -> dict:
    """Liveness plus runtime identity: status, Python version, UTC now."""
    return {
        "status": "ok",
        "python": platform.python_version(),
        "utc_time": datetime.now(timezone.utc).isoformat(),
    }


@app.get("/greet/{name}")
def greet(name: str) -> dict:
    """A greeting with the visitor's name — routing, proven live."""
    return {
        "greeting": f"Hello, {name}!",
        "environment": environment(),
        "hostname": hostname(),
    }

Two design choices to notice. The app reads app settings as ordinary environment variables — that is how App Service configuration reaches code, and it is why setting APP_ENVIRONMENT later flips the answer. And it has no database, no key, no secret: the demo's only moving parts are the deploy itself.

The two files Azure cares about

requirements.txt — at the project root, or the build fails:

fastapi==0.162.0
uvicorn==0.54.0
gunicorn==26.2.0
uvicorn-worker==0.4.0

App Service's build looks for the dependency file at the root of the project (or the zip). Without it, the build reports: “Could not find setup.py or requirements.txt; Not running pip install.” That error text, verbatim, is the giveaway that the file is in the wrong place.

startup.txt — the startup command, the step most tutorials skip:

gunicorn --bind=0.0.0.0:8000 --timeout 600 --workers 2 -k uvicorn_worker.UvicornWorker main:app --access-logfile '-' --error-logfile '-'

Piece by piece, because each one is a decision:

Why Gunicorn at all? App Service's built-in Python container already runs apps under Gunicorn, behind an Nginx reverse proxy. The startup command customises that, it doesn't replace the platform.
Why can't Gunicorn run FastAPI alone? Its default worker is a synchronous WSGI worker. Pointed at an ASGI app, it fails in the log stream with TypeError: FastAPI.__call__() missing 1 required positional argument: 'send'. The fix is the Uvicorn worker class, which speaks ASGI.
Why uvicorn_worker.UvicornWorker, not the uvicorn.workers class older tutorials show? In uvicorn 0.54.0 the uvicorn.workers module is deprecated — it still runs, but it logs a deprecation warning pointing at the new uvicorn-worker package. This post uses the new class; the old one is the fallback an older tutorial's command will show you.
Why port 8000? The built-in Python image exposes port 8000 by default. The app must listen there.
Why 2 workers, not the 4 many tutorials show? The free F1 plan has 1 GB of RAM shared across the plan. Two workers leave headroom; four would not teach you anything extra.
What is not in this command, deliberately: WEBSITES_PORT. That app setting is for custom containers, not the built-in images — it has no effect inside the container, and setting it is cargo-cult configuration this post corrects on sight.

And the callout that decides the whole walkthrough: on Python 3.14 and later, App Service auto-detects and runs FastAPI apps with no startup command at all. We pin Python 3.12 anyway, because 3.12 is a currently documented runtime (Microsoft's own PostgreSQL tutorials run on it) and because the startup command is the skill every existing app still needs. If you deploy on 3.14, skip the startup-command step — and know that skipping it is the platform's new behaviour, not a shortcut you invented.

Step 1 — Create the resources (portal and CLI, side by side)

The names below are the exact ones from this post's own run — resource group rg-vsl-topic05-cus, plan plan-vsl-topic05, app vsl-info-api. Pick your own equivalents; the app name in particular must be globally unique across Azure, because it becomes your public address.

Portal: Azure portal → Create a resource → Web App. Resource group: create new, rg-vsl-topic05-cus. Region: Central US — on a brand-new free account the region is not a free choice; see the quota note under the CLI commands below. Publishing model: Code. Runtime stack: Python 3.12. Operating system: Linux (Python on App Service runs on Linux only — Windows Python is no longer supported). Pricing plan: create new, and choose the Free (F1) tier. Review + create.

CLI — the same resources, in three commands:

# A resource group to hold everything (delete the group = delete all)
az group create --name rg-vsl-topic05-cus --location centralus

# The FREE plan — the --sku F1 part is what keeps this at $0
az appservice plan create --name plan-vsl-topic05 \
  --resource-group rg-vsl-topic05-cus --sku F1 --is-linux \
  --location centralus

# The web app on Python 3.12 (the name must be globally unique;
# the app's public address becomes <name>.azurewebsites.net)
az webapp create --name vsl-info-api --resource-group rg-vsl-topic05-cus \
  --plan plan-vsl-topic05 --runtime "PYTHON:3.12"

Confirm the runtime landed where you think it did:

az webapp config show --name vsl-info-api --resource-group rg-vsl-topic05-cus \
  --query linuxFxVersion

The region note, from this post's own run — read it before you pick a region. This walkthrough was produced on a brand-new free-trial account, and creating the F1 plan failed in Canada Central, East US, and West US 2: the account's free-tier quota there was 0, and the error said so. Central US had quota and accepted the plan immediately. If your region refuses the free plan, you have two free moves: switch regions (Central US worked here), or request the free quota increase for your subscription. What not to do is “fix” it by choosing a paid tier — the quota is an account-youth quirk, not a price of entry.

The rg-vsl-topic05-cus resource group holding the plan and the web app.

The plan-vsl-topic05 App Service plan page showing the Free F1 pricing tier.

Step 2 — App settings

Two settings, both set before the deploy:

az webapp config appsettings set --name vsl-info-api \
  --resource-group rg-vsl-topic05-cus \
  --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true APP_ENVIRONMENT=production

(Portal: your web app → Settings → Environment variables → App settings tab, add both, Save. Older portal versions called this Configuration → Application settings.)

SCM_DO_BUILD_DURING_DEPLOYMENT=true tells the deployment to run the Oryx build: activate a virtual environment and pip install requirements.txt. A raw zip deploy must set this itself — without it, the classic symptom is ModuleNotFoundError at startup, because the packages were never installed.
APP_ENVIRONMENT=production is the / endpoint's proof: it is what flips the local answer to the Azure one.

App settings showing APP_ENVIRONMENT set to production.

Step 3 — Deploy the zip

Build the zip with the dependency file at the archive root — and no .venv, no .git, no .env inside it. Deploying your local virtual environment is the most common self-inflicted deploy failure in this whole walkthrough:

zip deploy.zip main.py requirements.txt startup.txt
az webapp deploy --name vsl-info-api --resource-group rg-vsl-topic05-cus \
  --type zip --src-path deploy.zip

Deployment can take a few minutes; the production run for this post took about 2 minutes 40 seconds.

Deployment Center log showing the zip deployment succeeded.

Then set the startup command before you judge the result: portal → your web app → Configuration → Stack settings tab → Startup Command, paste the line from startup.txt, Save, then restart the app and wait ~20 seconds. (The General settings tab next to it holds platform and debugging options — the startup command is not there.)

Configuration, Stack settings tab, with the gunicorn startup command for FastAPI.

Step 4 — The staged failure (deliberate, and the point of the post)

Before the startup command was set, the first deploy of this exact app did not error. It served the platform's built-in default page — the generic one titled “Microsoft Azure App Service - Welcome” — because App Service auto-detects Django and Flask only, and a FastAPI app with no startup command falls through to the platform's read-only default app. We reproduced this on purpose during production, by clearing the startup command on the working app and restarting it: same deploy, same code, default page — then restored the command and watched the real app come back. If you see a default page after a deploy that reported success, you have not failed: you have reproduced the platform's documented behaviour, and the fix is the startup command plus a restart.

After the restart, the same URL answers the real app. Verify like an engineer — all three endpoints, in the browser:

https://vsl-info-api.azurewebsites.net/ now reports "environment": "production" and "hostname": "vsl-info-api.azurewebsites.net" — the local "local"/"localhost" answer, replaced by the Azure one, from the same code.
https://vsl-info-api.azurewebsites.net/greet/YourName — your greeting, from Azure.
https://vsl-info-api.azurewebsites.net/health — status: "ok", Python 3.12.15 (the patch level the PYTHON:3.12 image currently runs — your local 3.12.x and Azure's are the same 3.12 line, not necessarily the same patch), the current UTC time.

Then read the log stream while you hit the app, so the deploy stops being a black box:

az webapp log config --name vsl-info-api --resource-group rg-vsl-topic05-cus
az webapp log tail --name vsl-info-api --resource-group rg-vsl-topic05-cus

The shortcut — `az webapp up`

Everything above, in one command, for a fresh folder:

az webapp up

az webapp up is a current, generally available Azure CLI command: it creates the resource group, plan, and web app and deploys the code from your local folder, and Python apps are created as Linux apps. Use it when you already understand the steps — the long way above is the version that teaches you what the shortcut did, including which startup command and app settings it leaves you still needing to set yourself.

Errors you may hit

The site shows a default/placeholder page, not your app — the page titled “Microsoft Azure App Service - Welcome”. FastAPI wasn't detected (no startup command on Python 3.13 or earlier) and App Service ran its built-in default app. Fix: set the startup command, restart, wait ~20 seconds. One related trap, learned on this post's own run: az webapp config set --startup-file "" looks like it clears the startup command but silently leaves the old one in place — to actually clear it, use the portal's Configuration page or the management API.
TypeError: FastAPI.__call__() missing 1 required positional argument: 'send' in the log stream — Gunicorn's default sync worker met an ASGI app. Fix: the Uvicorn worker class in the startup command (Step: the two files Azure cares about). This exact error is why that class is in the command.
“Could not find setup.py or requirements.txt; Not running pip install.” — the dependency file is not at the project root / zip root. Fix: move it to the root and redeploy.
ModuleNotFoundError at startup — the packages were never installed, usually because the build never ran or a local venv was deployed with the code. Fix: set SCM_DO_BUILD_DURING_DEPLOYMENT=true and redeploy; never ship your venv.
“Service Unavailable” / the first hit hangs — two possible causes. The mild one is a cold start: F1 has no Always On, the app unloads when idle, and Microsoft's docs warn the app “might take longer to start up when you use free tiers… and become responsive after you refresh”. The serious one is Gunicorn up but the app not answering — check the log stream before changing anything (az webapp log tail).
The app stops responding part-way through the day — the F1 60-CPU-minutes-per-day quota is exhausted. It resets the next day. That is the free tier's ceiling working as designed; the first paid tier removes it.
A DeprecationWarning about uvicorn.workers in the logs — not a failure. You (or an older tutorial) used the class from the old location; uvicorn 0.54.0 says it moved to the uvicorn-worker package. Switch before a future uvicorn removes it.
The container perpetually restarts — the platform's warmup request must get some HTTP status back. An app that never answers (wrong port, crash on import) restarts forever. Slow starters get a lever: the WEBSITES_CONTAINER_START_TIME_LIMIT app setting (default 230 seconds, maximum 1800).

What it costs

F1 is $0 — and it is a real, currently listed plan, intended for trials, experimentation, and learning the service, with the limits to match:

F1 (Free) limits	Value
Compute	Shared, 60 CPU minutes per day (also capped at 3 minutes per 5 minutes)
Memory	1,024 MB per plan
Storage	1 GB per plan
Apps per plan	10
Bandwidth	165 MB per day
Custom domains	0 — the `*.azurewebsites.net` name only (its HTTPS certificate is included)
Always On	No — the app unloads when idle
SLA	None

The first paid step up, B1 in Central US, was US$0.018 per hour — about US$13.14 per month — when this post was prepared (Microsoft's Retail Prices API, October 2026); B1 gives you a dedicated core, 1.75 GB RAM, and 10 GB storage. (For contrast, Windows B1 in the same region was US$0.075/hour — the Linux/Windows gap is one reason this walkthrough is Linux-only, beside Linux being the only option for Python.)

One billing warning, quoted from Microsoft's pricing page FAQ because people learn it the expensive way: “Rates listed apply to apps in stopped state. Please delete apps that are not in use or update tier to Free to avoid charges.” App Service plans are charged while they exist, including stopped apps. Deleting is the reliable off switch — which is the next section.

Delete it when you're done (yes, really)

Everything in this walkthrough lives in one resource group, so one command removes all of it — the plan, the app, the settings, everything:

az group delete --name rg-vsl-topic05-cus --yes

Two honest notes to close the cost story. First: this post's own deployment was deleted this way after filming. The video's live site is gone by the time you watch it — that is the owner's rule for this channel (free tier only, and delete resources when you're not using them) applied to itself, not a gap in the tutorial. Second: nothing is lost by deleting. The companion repo folder plus the commands in this post redeploy the app from scratch any time you want it back, in the same sitting. Treat free-tier resources as disposable by default, and the cloud bill for learning stays exactly $0.

Where to go next

This same one-file app is the running example for the rest of the ship-and-run mini-series: containerise it with Docker (Topic #9), deploy it on every push with GitHub Actions through Deployment Center — which commits a workflow file to your repo and authenticates with a Microsoft Entra identity (Topic #13) — and watch it with Prometheus and Grafana (Topic #10). On App Service itself, the next steps in order: a custom domain and its certificate when you move to a Basic-or-higher plan (the free tier supports none), and the log stream as a daily habit rather than an emergency tool.

Get the code

The complete main.py, pinned requirements.txt, the startup.txt command file, and this post's setup as a README live in the companion repository:
https://github.com/sajjad037/visual-studio-learn-code/tree/main/topic-05-deploy-fastapi-azure

Sources

Python on Azure App Service: container characteristics, startup process, default page behaviour, troubleshooting — https://learn.microsoft.com/en-us/azure/app-service/configure-language-python
Deploy Python (FastAPI) — Microsoft's quickstart: zip deploy route, SCM_DO_BUILD_DURING_DEPLOYMENT, the Python 3.14 FastAPI auto-detection note — https://learn.microsoft.com/en-us/azure/app-service/quickstart-python
App Service on Linux FAQ (ports, WEBSITES_PORT, warmup and container start time limit) — https://learn.microsoft.com/en-us/azure/app-service/faq-app-service-linux
App Service limits, incl. the F1 quota rows — https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits
App Service (Linux) pricing, incl. the Free plan and the stopped-apps FAQ — https://azure.microsoft.com/en-us/pricing/details/app-service/linux/
B1 Central US prices (Linux US$0.018/hour, Windows US$0.075/hour) — Azure Retail Prices API, https://prices.azure.com/api/retail/prices (accessed October 28, 2026)
Azure free account offer and signup requirements — https://azure.microsoft.com/en-us/free/
az webapp up and the Azure CLI webapp command reference — https://learn.microsoft.com/en-us/cli/azure/webapp
Deploying a Python FastAPI app to App Service on Linux — Microsoft App Service support team blog, 2024-04-23 — https://azureossd.github.io/2024/04/23/Deploying-a-Python-FastAPI-app-to-App-Service-Linux/
FastAPI deployment: server workers — https://fastapi.tiangolo.com/deployment/server-workers/
Uvicorn worker deprecation — the uvicorn 0.54.0 package itself, and the replacement package — https://pypi.org/project/uvicorn-worker/
Package versions — https://pypi.org/project/fastapi/ (0.162.0), https://pypi.org/project/uvicorn/ (0.54.0), https://pypi.org/project/gunicorn/ (26.2.0), https://pypi.org/project/azure-cli releases via https://github.com/Azure/azure-cli/releases

Enjoying these tutorials?

Get new Visual Studio Learn posts by email — free, no spam:

Follow along: YouTube · Facebook · RSS

I Built an AI Agent That Reads Release Notes So I Don't Have To

2026-10-27T09:10:29.128-04:00

Versions used in this post — read this first: Python 3.12.3 · requests 2.34.2 · google-genai 2.33.0 · Model: gemini-3.6-flash. Everything runs from one file, digest_agent.py, printed in full below — the exact file in the companion repo.

The direct answer

Build an AI agent in Python, step by step, that reads release notes for you. One small Python file is enough to stop reading changelogs by hand. Think of the agent as the smallest useful harness — three steps with a strict contract between them: fetch, summarize, write. It fetches the newest GitHub release of each project it tracks from the project's public releases feed, sends the release notes to Gemini with an instruction to return three summary bullets plus any breaking changes as JSON, and writes one Markdown file: digest.md, with the breaking changes collected at the top. Schedule it for 7:15 every morning and yesterday's releases are a one-page read with your coffee. No GitHub account, no token, no framework — the only credential is a Gemini API key, and the free tier covers this easily.

What you will build

A feed fetcher — reads https://github.com/<owner>/<repo>/releases.atom for CPython, FastAPI, and the Azure CLI. The first entry in a releases feed is the newest published release. Feeds are public web pages, so nothing here touches the GitHub REST API and its 60-requests-per-hour unauthenticated limit.
A summariser — one function that strips the notes' HTML to text, truncates anything very long, and asks Gemini for exactly three bullets and a breaking-changes list, as JSON.
A digest writer — assembles digest.md: a dated header, a ⚠ Breaking changes section across all projects, one section per project (version, date, bullets, link), and a footer with the run's real token counts and estimated cost.
A schedule — the same script run daily by Windows Task Scheduler or cron (both shown below).

Two design choices are deliberate. The agent reads feeds, not the API: simpler, unauthenticated, and nothing to rate-limit at three projects a day. And it has no memory: it always summarises the newest release in each feed, whether or not you read yesterday's digest. Remembering where it left off is the first upgrade, listed at the end.

Environment setup — do this first

Prerequisites: Python 3.10 or newer (this post uses 3.12.3), a terminal, and a Gemini API key. The free tier is enough; no card is needed.

Get your Gemini API key, click by click:

Go to aistudio.google.com and sign in with a Google account.
Click Get API key in the left sidebar (the key icon).
Click Create API key, choose or create a Google Cloud project when asked, and click Create.
Copy the key that appears — it stays visible in that same key list.
Keep it secret like a password: never paste it into code, a screenshot, or a public repository. This agent reads it only from an environment variable.

Create the project and install the pinned dependencies:

mkdir release-digest && cd release-digest
python3 -m venv .venv && source .venv/bin/activate
# Windows PowerShell: py -m venv .venv ; .venv\Scripts\Activate.ps1
pip install requests==2.34.2 google-genai==2.33.0

(The code goes in this folder as digest_agent.py — it is printed in full in the steps below, and the companion repo has it as a ready-made file.)

Set the key, then verify the setup:

export GEMINI_API_KEY=<redacted>
# Windows PowerShell: $env:GEMINI_API_KEY=<redacted>
python -c "import requests, google.genai; print('setup ok')"

If that prints setup ok, the environment is ready. Every error the run itself can throw is listed in "Errors you may hit" near the end.

Step 1 — Config, data shapes, and stripping the HTML

The top of the file is everything you are allowed to tweak: the model name as one constant (you will see why in the errors section), the list of projects to watch, the feed URL pattern, and the published per-token rates the cost footer uses. Below that, two small dataclasses — Release (what a feed hands us) and Summary (what the model hands back) — and a minimal HTML-to-text converter, because feed content arrives as HTML and Gemini should read words, not markup.

"""Release-notes digest agent: read the changelogs so you don't have to.

Companion code for the Visual Studio Learn post and video
"I Built an AI Agent That Reads Release Notes So I Don't Have To".

Once a run, the agent fetches the latest GitHub release of each project
in PROJECTS below, asks Gemini to summarise the release notes in three
bullets and flag anything breaking, and writes one Markdown digest
(digest.md) with a breaking-changes section at the top.

Requires: Python 3.10 or newer, the packages in requirements.txt, and a
Gemini API key in the GEMINI_API_KEY environment variable. See README.md.
"""

import json
import logging
import os
import sys
import xml.etree.ElementTree as ET
from dataclasses import dataclass, field
from datetime import date
from html.parser import HTMLParser

import requests
from google import genai

logger = logging.getLogger("digest_agent")
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")

MODEL = "gemini-3.6-flash"

# The projects to watch: (display name, GitHub "owner/repo"). Add or
# remove lines here — nothing else in the file needs to change.
PROJECTS = [
    ("CPython", "python/cpython"),
    ("FastAPI", "tiangolo/fastapi"),
    ("Azure CLI", "Azure/azure-cli"),
]

FEED_URL = "https://github.com/{repo}/releases.atom"
USER_AGENT = "release-digest-agent/1.0 (Visual Studio Learn tutorial)"
FETCH_TIMEOUT_SECONDS = 30
MAX_NOTES_CHARS = 12_000  # truncate very long notes before the model call

# Published pay-as-you-go rates for gemini-3.6-flash, US$ per 1M tokens.
INPUT_RATE_PER_MILLION = 0.75
OUTPUT_RATE_PER_MILLION = 3.75

OUTPUT_FILE = "digest.md"

ATOM = {"a": "http://www.w3.org/2005/Atom"}
# Tags that mean "new line" when release-note HTML is flattened to text.
BLOCK_TAGS = {"p", "br", "div", "li", "ul", "ol", "h1", "h2", "h3", "h4", "pre", "tr"}

@dataclass
class Release:
    """The latest release of one project, as published in its feed."""

    project: str
    title: str  # feed title, e.g. "v3.13.18" or "Azure CLI 2.91.0"
    published: str  # ISO date from the feed, e.g. "2026-10-25"
    url: str
    notes: str  # release notes as plain text (HTML already stripped)


@dataclass
class Summary:
    """Gemini's reading of one release, plus what the call cost."""

    bullets: list[str] = field(default_factory=list)
    breaking: list[str] = field(default_factory=list)
    input_tokens: int = 0
    output_tokens: int = 0


class _TextExtractor(HTMLParser):
    """Minimal HTML-to-text: keep the words, drop the markup."""

    def __init__(self) -> None:
        super().__init__()
        self.parts: list[str] = []

    def handle_starttag(self, tag, attrs):
        if tag in BLOCK_TAGS:
            self.parts.append("\n")

    def handle_data(self, data):
        self.parts.append(data)


def html_to_text(html: str) -> str:
    """Flatten release-note HTML to readable plain text."""
    extractor = _TextExtractor()
    extractor.feed(html)
    lines = (line.strip() for line in "".join(extractor.parts).splitlines())
    return "\n".join(line for line in lines if line)

Step 2 — Fetch the newest release from the feed

One function per project: GET the feed with a polite user agent and a timeout, parse the XML, take the first entry, and flatten its HTML body to text. raise_for_status() means a dead or renamed repo fails loudly in the log instead of producing a quietly empty digest.

def fetch_latest_release(project: str, repo: str) -> Release:
    """Fetch the newest entry of a project's GitHub releases Atom feed.

    The feed lists the 10 most recently published releases; the first
    entry is the newest. No GitHub account or token is needed — the
    feed is a public web page, not the rate-limited REST API.
    """
    url = FEED_URL.format(repo=repo)
    logger.info("Fetching %s", url)
    response = requests.get(
        url, headers={"User-Agent": USER_AGENT}, timeout=FETCH_TIMEOUT_SECONDS
    )
    response.raise_for_status()

    root = ET.fromstring(response.content)
    entry = root.find("a:entry", ATOM)
    if entry is None:
        raise ValueError(f"{repo}: the releases feed has no entries")

    title = entry.findtext("a:title", default="", namespaces=ATOM).strip()
    updated = entry.findtext("a:updated", default="", namespaces=ATOM)
    link = entry.find("a:link", ATOM)
    content = entry.find("a:content", ATOM)
    notes_html = content.text if content is not None and content.text else ""

    return Release(
        project=project,
        title=title,
        published=updated[:10],
        url=link.get("href", "") if link is not None else "",
        notes=html_to_text(notes_html),
    )

Step 3 — Ask Gemini for bullets and breaking changes

This is the only function that talks to the model, and its contract is strict: work only from the notes text provided, return JSON and nothing else — exactly three summary bullets, plus a list of changes that could break existing code, config, or command lines. Two honesty guards live here. If a release ships with no notes at all, the function returns a line saying so without spending a model call. And if the model's answer is not the expected JSON, the code keeps the raw text as a single bullet and logs a warning, rather than crashing the morning run.

def summarize_release(client: genai.Client, release: Release) -> Summary:
    """Ask Gemini for three bullets and any breaking changes in a release.

    The model only ever sees the notes text fetched above — it is told
    to work from that text alone and to say so when the notes are thin.
    Its answer comes back as JSON and is parsed defensively.
    """
    if not release.notes.strip():
        # Nothing to summarise: don't spend a model call on an empty page.
        logger.info("%s: no release notes published — skipping the model call",
                    release.project)
        return Summary(bullets=["No release notes were published with this release."])

    prompt = f"""You are summarising a software release for a working developer.

Project: {release.project}
Release: {release.title} ({release.published})

Release notes (plain text, converted from the project's own feed):
---
{release.notes[:MAX_NOTES_CHARS]}
---

Answer with ONLY a JSON object, no markdown fences, in exactly this shape:
{{"summary": ["bullet", "bullet", "bullet"],
  "breaking": ["one line per breaking change, or empty list"]}}

Rules:
- "summary" is exactly 3 short bullets, based only on the notes above.
- If the notes contain no real change details, say that honestly in one
  bullet instead of inventing changes.
- "breaking" lists only changes that could break existing code, config,
  or command lines — behaviour changes count. Ignore download hashes,
  links, and housekeeping.
"""

    response = client.models.generate_content(model=MODEL, contents=prompt)
    usage = response.usage_metadata
    text = (response.text or "").strip()
    if text.startswith("```"):  # strip code fences if the model adds them
        text = text.strip("`")
        text = text[text.find("{"):]

    try:
        data = json.loads(text)
        bullets = [str(b) for b in data.get("summary", [])][:3]
        breaking = [str(b) for b in data.get("breaking", [])]
    except (json.JSONDecodeError, AttributeError):
        logger.warning("%s: model answer was not the expected JSON; "
                       "keeping the raw text as a single bullet", release.project)
        bullets = [text] if text else ["The model returned an empty answer."]
        breaking = []

    return Summary(
        bullets=bullets,
        breaking=breaking,
        input_tokens=usage.prompt_token_count or 0,
        output_tokens=usage.candidates_token_count or 0,
    )


def estimate_cost(input_tokens: int, output_tokens: int) -> float:
    """Estimated US$ cost of the run at the published per-token rates."""
    return (
        input_tokens * INPUT_RATE_PER_MILLION
        + output_tokens * OUTPUT_RATE_PER_MILLION
    ) / 1_000_000

Step 4 — Assemble the digest and run

build_digest puts the breaking changes first — across every project — because that is the section that decides whether today is a reading day or an upgrading day. main loops the projects, and a failure in one (a feed down, a repo renamed) is logged and skipped, not fatal: a digest with two of three projects beats no digest. Only if every project fails does the run exit without writing a file.

def build_digest(entries: list[tuple[Release, Summary]]) -> str:
    """Assemble the one-page Markdown digest from all summaries."""
    today = date.today().strftime("%A, %B %d, %Y")
    total_in = sum(s.input_tokens for _, s in entries)
    total_out = sum(s.output_tokens for _, s in entries)

    lines = [f"# Release Digest — {today}", ""]

    breaking_lines = [
        f"- **{release.project} {release.title}** — {item}"
        for release, summary in entries
        for item in summary.breaking
    ]
    lines += ["## ⚠ Breaking changes", ""]
    lines += breaking_lines or ["None flagged in this run."]
    lines.append("")

    for release, summary in entries:
        lines += [
            f"## {release.project} — {release.title}",
            "",
            f"Released: {release.published} · [Release notes]({release.url})",
            "",
        ]
        lines += [f"- {bullet}" for bullet in summary.bullets]
        lines.append("")

    lines += [
        "---",
        f"*Generated by digest_agent.py · Model: {MODEL} · "
        f"Tokens: {total_in:,} in / {total_out:,} out · "
        f"Estimated cost: ${estimate_cost(total_in, total_out):.6f}*",
    ]
    return "\n".join(lines) + "\n"

def main() -> int:
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        logger.error("GEMINI_API_KEY is not set. Get a key in Google AI "
                     "Studio and set it in the environment — see README.md.")
        return 1

    client = genai.Client(api_key=api_key)
    entries: list[tuple[Release, Summary]] = []
    failures = 0
    for project, repo in PROJECTS:
        try:
            release = fetch_latest_release(project, repo)
            entries.append((release, summarize_release(client, release)))
            logger.info("%s: %s (%s)", project, release.title, release.published)
        except Exception:
            failures += 1
            logger.exception("%s: fetch or summary failed — continuing "
                             "with the remaining projects", project)

    if not entries:
        logger.error("Every project failed; no digest written.")
        return 1

    with open(OUTPUT_FILE, "w", encoding="utf-8") as fh:
        fh.write(build_digest(entries))
    logger.info("Wrote %s (%d project(s), %d failure(s))",
                OUTPUT_FILE, len(entries), failures)
    return 0


if __name__ == "__main__":
    sys.exit(main())

Step 5 — Run it, and read the digest

python digest_agent.py

The log shows each feed fetched and each release found, and the run writes digest.md in the same folder. When this post was prepared (Sunday, October 25, 2026), the three feeds' newest releases were CPython v3.13.18 (published that same day), FastAPI 0.162.0 (October 23), and Azure CLI 2.91.0 (October 5) — the agent re-fetches on every run, so your digest always carries whatever is newest that morning.

Two of the three feeds teach an honest lesson about release notes. CPython's GitHub release body is a one-liner ("Python 3.15.2") — its real changelog lives on docs.python.org — and the Azure CLI's body is mostly a link to its full notes page plus download hashes. The prompt tells Gemini to say so instead of inventing changes, and to ignore hashes; the summaries for those two are thin because the notes are thin, and the digest does not pretend otherwise.

Here is the complete digest.md from the live production run of this exact file, made on Monday, October 26, 2026 — real Gemini bullets, a real breaking-change flag, and the run's real token counts in the footer. One change from prep is visible in it: the CPython feed's newest entry had advanced to v3.15.2 (published October 25, after the prep fetch), while FastAPI and Azure CLI stood still — the feed reports what was published last, and the digest prints it as-is:

# Release Digest — Monday, October 26, 2026

## ⚠ Breaking changes

- **FastAPI 0.162.0** — FastAPI no longer infers False for omitted boolean form fields; unsubmitted fields without a default will now raise a missing-field error instead of evaluating to False.

## CPython — v3.15.2

Released: 2026-10-25 · [Release notes](https://github.com/python/cpython/releases/tag/v3.15.2)

- Python 3.15.2 release announced on 2026-10-25.
- The provided release notes contain no detailed changelog or change descriptions.
- No specific features, bug fixes, or updates were documented in the notes.

## FastAPI — 0.162.0

Released: 2026-10-23 · [Release notes](https://github.com/fastapi/fastapi/releases/tag/0.162.0)

- Omitted bool and bool | None form fields now use declared defaults or raise missing-field errors instead of automatically inferring False.
- Applies across individual form parameters, form models, and form model unions, bringing behavior in line with standard Pydantic logic.
- Omitted boolean fields are now excluded from model_dump(exclude_unset=True) and no longer count as submitted fields during union selection.

## Azure CLI — Azure CLI 2.91.0

Released: 2026-10-05 · [Release notes](https://github.com/Azure/azure-cli/releases/tag/azure-cli-2.91.0)

- The release notes contain no detailed change log or feature notes.
- Checksums (SHA256) are provided for official Linux, macOS, and Windows release artifacts.
- Artifacts cover arm64 and x86_64 architectures along with MSI and ZIP packages.

---
*Generated by digest_agent.py · Model: gemini-3.6-flash · Tokens: 1,313 in / 252 out · Estimated cost: $0.001930*

Scheduling it daily

Windows — Task Scheduler: Create Basic Task → Daily, your morning time → Action: Start a program → Program: C:\path\to\release-digest\.venv\Scripts\python.exe, Arguments: digest_agent.py, Start in: C:\path\to\release-digest. Set GEMINI_API_KEY once as a user environment variable (Settings → Environment Variables) — the scheduled task does not inherit your open PowerShell window's variables.

macOS / Linux — cron:

15 7 * * * cd /path/to/release-digest && GEMINI_API_KEY=<redacted> .venv/bin/python digest_agent.py >> digest.log 2>&1

(On a shared machine, keep the key in a protected file or secret store rather than the crontab.)

Errors you may hit

GEMINI_API_KEY is not set — the agent stops before doing any work. The variable must exist in the same shell (or scheduled environment) that runs the script; setting it in one terminal does not set it in another, and Task Scheduler tasks never see your interactive shell's variables.
A 404 naming the model — "gemini-… is no longer available to new users" — Google retires model names for new API keys first: the model can be listed in the docs and still refuse a fresh key. This exact error is why the model is a single constant at the top of the file. Verified example: gemini-2.5-flash returned it to newly created keys in October 2026. Fix: open Google's models page, take the current Flash model it names, update MODEL. This post pins gemini-3.6-flash, verified current and stable in Google's docs on October 26, 2026 — the pin moved from gemini-3.8-flash during production, for the reason in the 503 entry below.
429 / quota errors from Gemini — the free tier has request limits; three small summaries a day sit far below them, but a brand-new key can be throttled and heavy same-day experimenting adds up. Wait for the daily reset, or enable billing.
503 UNAVAILABLE — "The model is currently experiencing high demand" — the model itself is temporarily overloaded; this is not your key, your code, or your quota. This exact error shaped this post: during production on October 26, 2026, gemini-3.8-flash returned 503s (and quota 429s under retry load) across ten runs of this exact file, completing only single-project digests. The fix applied is the one the file is designed for — the pin moved to gemini-3.6-flash, one constant, identical published rates — and the unchanged-everything-else file completed the full capture the same day. For a scheduled daily job the softer fix also works: wait, and let the next run try again.
One project logs "fetch or summary failed" but the run completes — that feed was unreachable, the repo was renamed, or the feed returned no entries. A renamed repo empties its old feed; update the path in PROJECTS.
The ⚠ section says "None flagged in this run" — that is a result, not an error: the model found nothing in the notes that could break existing code. Skim the bullets before trusting it.
Oddly thin bullets for CPython or the Azure CLI — expected (see Step 5): their GitHub bodies carry almost no prose. The agent summarises the feed it is given, no more.
Digest shows an older version line than you expected — feeds order by publish time, not version number. On October 25, 2026, CPython published several releases the same day — security fixes for older branches (v3.13.18 among them) and v3.15.2 on the current line; the digest's CPython line is whichever was published last — v3.15.2 — not the day's highest-profile release. The digest always prints the version and date so the ordering is visible, and for a "what shipped most recently" digest that ordering is the honest one.

Where to go next

Three upgrades, in the order a daily tool earns them: memory (a small state file recording the last release seen per project, so the agent only summarises what is actually new and can say "nothing new today"), delivery (mail or message the digest to yourself instead of leaving it as a file — the agent from Topic #1 has the tool-calling pattern for it), and more sources (any GitHub project is one line in PROJECTS; projects that publish proper changelogs — frameworks, CLIs, SDKs — digest best). Previous in this series of agent builds: Topic #1's tool-calling agent and Topic #2's MCP server; the PDF Q&A app (Small AI App #1) is the same Gemini pattern pointed at documents instead of feeds.

Get the code

The complete digest_agent.py, pinned requirements.txt, and this post's setup as a README live in the companion repository:
https://github.com/sajjad037/visual-studio-learn-code/tree/main/topic-04-release-digest

Sources

CPython releases feed — https://github.com/python/cpython/releases.atom (latest at prep: v3.13.18, 2026-10-25)
FastAPI releases feed — https://github.com/tiangolo/fastapi/releases.atom (latest at prep: 0.162.0, 2026-10-23)
Azure CLI releases feed — https://github.com/Azure/azure-cli/releases.atom (latest at prep: Azure CLI 2.91.0, 2026-10-05)
GitHub REST API rate limits (60 requests/hour unauthenticated, the reason this agent uses feeds) — https://api.github.com/rate_limit and GitHub's API docs
Gemini models (gemini-3.6-flash listed as Stable) — https://ai.google.dev/gemini-api/docs/models
Gemini API pricing ($0.75 / $3.75 per 1M tokens for gemini-3.6-flash through Dec 31, 2026) — https://ai.google.dev/gemini-api/docs/pricing
Package versions — https://pypi.org/project/requests/ (2.34.2), https://pypi.org/project/google-genai/ (2.33.0)

Enjoying these tutorials?

Get new Visual Studio Learn posts by email — free, no spam:

Follow along: YouTube · Facebook · RSS

Small AI App #1: Build a PDF Q&A App with FastAPI + Gemini (Upload a PDF, Ask It Questions)

2026-10-24T09:07:00.000-04:00

Versions used in this post — read this first: Python 3.12.3 · FastAPI 0.161.1 · uvicorn 0.54.0 · pypdf 6.21.2 · google-genai 2.33.0 · python-multipart 0.0.32 · Model: gemini-3.8-flash. Everything runs from one file, app.py, and the code below is the exact code that was run and tested for this post.

The direct answer

Yes — one small FastAPI file is enough. Upload a PDF and the server extracts its text with pypdf, splits it into overlapping chunks, and stores them in memory. Ask a question and it picks the chunks sharing the most words with it, sends only those to Gemini with a strict instruction to answer from them alone, and returns the answer with the token counts the API reported and what they cost. No vector database, nothing on top of FastAPI — and if no chunk matches, the app does not call the model at all.

This is the first episode of Small AI Apps: complete, runnable applications built with FastAPI and Gemini, each small enough to finish in under an hour and honest about what each run costs.

What you will build

POST /upload — accepts one PDF, extracts and chunks its text, returns a document id plus the real page, character, and chunk counts.
POST /ask — answers one question from the best-matching chunks and reports chunks used, input tokens, output tokens, and estimated cost.
GET / — a one-page web UI: pick a file, upload it, ask questions, read the cost line under every answer.
GET /health — a liveness check, because every app you run should have one.

Two design choices are deliberate. Retrieval is keyword overlap, not embeddings: simpler, free, and honest about its limits — it finds chunks that use your question's words and can miss a paraphrase. Storage is in memory: restart the server and uploads are gone. Both are right-sized for a first app, and both return at the end as the first production upgrades.

Get the code

All the code in this post lives in the companion GitHub repository, in the topic-03-pdf-qa-app folder — the exact app.py printed below, the pinned requirements file, and a README that covers prerequisites, environment setup including the key walkthrough, install, and how to run and use the app. If you would rather follow along here, every step is also written out below.

Environment setup — do this first

Prerequisites: Python 3.10 or newer (this post uses 3.12.3), a terminal, and a Gemini API key. The free tier is enough; no card is needed.

Get your Gemini API key, click by click:

Go to aistudio.google.com and sign in with a Google account.
Click Get API key in the left sidebar (the key icon).
Click Create API key, choose or create a Google Cloud project when asked, and click Create.
Copy the key that appears — it stays visible in that same key list.
Keep it secret like a password: never paste it into code, a screenshot, or a public repository. This app reads it only from an environment variable.

Create the project and install the pinned dependencies:

mkdir pdf-qa && cd pdf-qa
python3 -m venv .venv && source .venv/bin/activate
# Windows PowerShell: py -m venv .venv ; .venv\Scripts\Activate.ps1
pip install fastapi==0.161.1 "uvicorn[standard]==0.54.0" pypdf==6.21.2 google-genai==2.33.0 python-multipart==0.0.32

(python-multipart is easy to forget: without it, FastAPI cannot accept file uploads at all.)

Set the key, then verify the setup:

export GEMINI_API_KEY="paste-your-key-here"
# Windows PowerShell: $env:GEMINI_API_KEY = "paste-your-key-here"
python -c "import fastapi, pypdf, google.genai; print('setup ok')"

Step 1 — The document pipeline: extract, chunk, retrieve

Save the code in this step and the next two as one file, app.py. This first part turns an uploaded PDF into searchable chunks:

"""Small AI App #1: a PDF Q&A app built with FastAPI and Gemini.

Companion code for the Visual Studio Learn post and video
"Small AI App #1: Build a PDF Q&A App with FastAPI + Gemini".

Upload a PDF, the app extracts and chunks its text, and each question is
answered by Gemini using only the chunks that match the question — with
the token count and estimated cost of every answer reported back.

Requires: Python 3.12, the packages in requirements.txt, and a Gemini
API key in the GEMINI_API_KEY environment variable. See README.md.
"""

import logging
import os
import re
import uuid
from dataclasses import dataclass, field
from io import BytesIO

from fastapi import FastAPI, File, HTTPException, UploadFile
from fastapi.responses import HTMLResponse
from google import genai
from pydantic import BaseModel
from pypdf import PdfReader

logger = logging.getLogger("pdf_qa")
logging.basicConfig(level=logging.INFO)

MODEL = "gemini-3.8-flash"
MAX_FILE_BYTES = 10 * 1024 * 1024  # 10 MB upload limit
CHUNK_SIZE = 1000  # characters per chunk
CHUNK_OVERLAP = 150  # characters shared between neighbouring chunks
TOP_CHUNKS = 4  # chunks sent to the model with each question

# Published pay-as-you-go rates for gemini-3.8-flash, US$ per 1M tokens.
INPUT_RATE_PER_MILLION = 0.75
OUTPUT_RATE_PER_MILLION = 3.75


@dataclass
class StoredDocument:
    """One uploaded PDF: its name, page count, and text chunks."""

    filename: str
    pages: int
    chunks: list[str] = field(default_factory=list)


# In-memory store: doc_id -> document. Deliberately simple — restarting
# the server forgets every upload, which is fine for a learning app and
# is the first thing to replace (with real storage) in a production one.
DOCUMENTS: dict[str, StoredDocument] = {}

app = FastAPI(title="PDF Q&A — Small AI App #1")


def extract_text(pdf_bytes: bytes) -> tuple[str, int]:
    """Extract all text from PDF bytes. Returns (text, page_count).

    Raises ValueError when the file cannot be parsed as a PDF at all.
    A scanned, image-only PDF parses fine but yields almost no text —
    the caller treats that as its own, separate failure.
    """
    try:
        reader = PdfReader(BytesIO(pdf_bytes))
    except Exception as exc:
        raise ValueError(f"Could not read that file as a PDF: {exc}") from exc
    pages = [page.extract_text() or "" for page in reader.pages]
    return "\n".join(pages), len(pages)


def chunk_text(text: str, size: int = CHUNK_SIZE, overlap: int = CHUNK_OVERLAP) -> list[str]:
    """Split text into overlapping character chunks.

    Overlap exists so a sentence that straddles a chunk boundary still
    appears whole in at least one chunk the model can read.
    """
    cleaned = re.sub(r"\s+", " ", text).strip()
    chunks = []
    start = 0
    while start < len(cleaned):
        chunks.append(cleaned[start : start + size])
        start += size - overlap
    return [c for c in chunks if c.strip()]


STOPWORDS = {
    "the", "and", "for", "are", "was", "what", "when", "where", "which",
    "does", "did", "how", "why", "who", "this", "that", "with", "from",
    "have", "has", "can", "its", "it", "is", "in", "on", "of", "to", "a", "an",
}


def _meaningful_words(text: str) -> set[str]:
    """Lowercase word set with stopwords removed.

    Without this, a question like "What is the…" matches every chunk in
    the document on the words "what" and "the" alone, and the scoring
    below would measure grammar instead of topic.
    """
    return {
        w
        for w in re.findall(r"[a-z0-9]+", text.lower())
        if len(w) > 2 and w not in STOPWORDS
    }


def relevant_chunks(chunks: list[str], question: str, limit: int = TOP_CHUNKS) -> list[str]:
    """Pick the chunks that share the most words with the question.

    This is plain keyword overlap, not semantic search — no embeddings,
    no vector database. It is honest about its limits: it finds chunks
    that use the question's words, and misses paraphrases. That trade is
    the right size for a first app; embeddings are the upgrade path.
    """
    words = _meaningful_words(question)
    if not words:
        return []
    scored = []
    for index, chunk in enumerate(chunks):
        score = len(words & _meaningful_words(chunk))
        if score:
            scored.append((score, index, chunk))
    scored.sort(key=lambda item: (-item[0], item[1]))
    return [chunk for _, _, chunk in scored[:limit]]

Three details carry this section. Chunks overlap by 150 characters so a sentence that straddles a boundary still appears whole somewhere the model can read it. Stopwords are stripped before scoring — without that, “What is the watering schedule?” matches every chunk on what, is, and the, and the scoring measures grammar instead of topic; that bug appeared in the first test run of this exact code and was fixed before publication. And extraction and “no text found” are different failures: a corrupt file raises in extract_text, while a scanned PDF parses fine and yields no words — Step 2 gives that case its own, clearer error.

Step 2 — The two endpoints

class AskRequest(BaseModel):
    doc_id: str
    question: str


@app.get("/health")
def health() -> dict:
    """Tiny liveness check: confirms the server is up."""
    return {"status": "ok", "documents_loaded": len(DOCUMENTS)}


@app.post("/upload")
async def upload(file: UploadFile = File(...)) -> dict:
    """Accept one PDF, extract and chunk its text, and store it.

    Returns the document id the client must send with every question,
    plus the page and chunk counts so the reader can see the pipeline
    actually did the work.
    """
    if not (file.filename or "").lower().endswith(".pdf"):
        raise HTTPException(status_code=400, detail="Please upload a PDF file.")
    pdf_bytes = await file.read()
    if len(pdf_bytes) > MAX_FILE_BYTES:
        raise HTTPException(
            status_code=413,
            detail=f"That file is over the {MAX_FILE_BYTES // (1024 * 1024)} MB limit.",
        )
    try:
        text, page_count = extract_text(pdf_bytes)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    chunks = chunk_text(text)
    if not chunks:
        raise HTTPException(
            status_code=422,
            detail=(
                "No readable text was found in that PDF. Scanned or "
                "image-only PDFs need OCR before an app like this can "
                "read them."
            ),
        )
    doc_id = uuid.uuid4().hex[:8]
    DOCUMENTS[doc_id] = StoredDocument(
        filename=file.filename, pages=page_count, chunks=chunks
    )
    logger.info("stored %s: %d pages, %d chunks", file.filename, page_count, len(chunks))
    return {
        "doc_id": doc_id,
        "filename": file.filename,
        "pages": page_count,
        "characters": len(text),
        "chunks": len(chunks),
    }


@app.post("/ask")
def ask(request: AskRequest) -> dict:
    """Answer one question from the stored chunks of one document.

    Only the best-matching chunks are sent to Gemini — never the whole
    document — which is what keeps each question cheap and inside the
    model's context limits. The response carries the real token counts
    the API reported and the cost they work out to.
    """
    document = DOCUMENTS.get(request.doc_id)
    if document is None:
        raise HTTPException(
            status_code=404,
            detail="Unknown document. Upload a PDF first (uploads are forgotten when the server restarts).",
        )
    chunks = relevant_chunks(document.chunks, request.question)
    if not chunks:
        return {
            "answer": (
                "No passage in this document shares words with that "
                "question, so nothing was sent to the model. Try "
                "rephrasing with words the document itself uses."
            ),
            "chunks_used": 0,
            "input_tokens": 0,
            "output_tokens": 0,
            "estimated_cost_usd": 0.0,
        }

    context = "\n\n---\n\n".join(chunks)
    prompt = (
        "Answer the question using only the document passages below. "
        "If the passages do not contain the answer, say so plainly "
        "instead of guessing.\n\n"
        f"Passages:\n{context}\n\nQuestion: {request.question}"
    )
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise HTTPException(
            status_code=500,
            detail="GEMINI_API_KEY is not set on the server. See the setup steps in the README.",
        )
    try:
        client = genai.Client(api_key=api_key)
        response = client.models.generate_content(model=MODEL, contents=prompt)
    except Exception as exc:  # surface API failures as a clean 502, not a stack trace
        logger.exception("Gemini call failed")
        raise HTTPException(status_code=502, detail=f"Gemini API error: {exc}") from exc

    usage = response.usage_metadata
    input_tokens = usage.prompt_token_count or 0
    output_tokens = usage.candidates_token_count or 0
    cost = (
        input_tokens * INPUT_RATE_PER_MILLION
        + output_tokens * OUTPUT_RATE_PER_MILLION
    ) / 1_000_000
    logger.info(
        "ask on %s: %d chunks, %d in / %d out tokens",
        request.doc_id,
        len(chunks),
        input_tokens,
        output_tokens,
    )
    return {
        "answer": response.text,
        "chunks_used": len(chunks),
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "estimated_cost_usd": round(cost, 6),
    }

Read /ask closely, because it is where the money is spent — and saved. Only the four best-matching chunks ever reach the model, never the whole document, which keeps each question small whatever the PDF’s size. If no chunk matches, the endpoint answers without an API call: in testing, asking the sample handbook “What is the airspeed velocity of an unladen swallow?” returned exactly that no-passage answer with chunks_used: 0 and zero tokens — grounding enforced by code, not by hoping the prompt behaves. When a call does happen, the answer returns with the API’s own usage numbers, and the cost is simple arithmetic at the published gemini-3.8-flash rates (US$0.75 per million input tokens, US$3.75 per million output). In the live run for this post, the question “When is the lottery draw, and what does a plot cost?” came back with the handbook’s own facts — the draw takes place on March 30, 2026, and each plot costs 45 dollars for the season — answered from a single chunk at 277 input tokens and 35 output tokens: an estimated US$0.000339, roughly a thirtieth of a cent. The app prints the exact figure for your question. API failures return as a clean 502 carrying the API’s own error text, and a missing key returns a 500 that names exactly what to set — both quoted verbatim below.

Step 3 — The web page

@app.get("/", response_class=HTMLResponse)
def home() -> str:
    """Serve the one-page UI: upload a PDF, then ask it questions."""
    return """<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>PDF Q&amp;A — Small AI App #1</title>
<style>
  body { font-family: system-ui, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 16px; }
  h1 { font-size: 24px; }
  .box { border: 1px solid #ddd; border-radius: 8px; padding: 16px; margin: 16px 0; }
  #answer { white-space: pre-wrap; }
  .meta { color: #555; font-size: 14px; }
  button { padding: 8px 16px; cursor: pointer; }
  input[type=text] { width: 75%; padding: 8px; }
</style>
</head>
<body>
<h1>PDF Q&amp;A</h1>
<p>Upload a PDF, then ask it questions. Answers come only from the
document, and every answer shows what it cost.</p>

<div class="box">
  <input type="file" id="pdf" accept="application/pdf">
  <button onclick="uploadPdf()">Upload PDF</button>
  <p class="meta" id="uploadStatus">No document uploaded yet.</p>
</div>

<div class="box">
  <input type="text" id="question" placeholder="Ask a question about the document">
  <button onclick="askQuestion()">Ask</button>
  <p id="answer"></p>
  <p class="meta" id="askMeta"></p>
</div>

<script>
let docId = null;

async function uploadPdf() {
  const fileInput = document.getElementById('pdf');
  const status = document.getElementById('uploadStatus');
  if (!fileInput.files.length) { status.textContent = 'Choose a PDF first.'; return; }
  const form = new FormData();
  form.append('file', fileInput.files[0]);
  status.textContent = 'Uploading and reading…';
  const res = await fetch('/upload', { method: 'POST', body: form });
  const data = await res.json();
  if (!res.ok) { status.textContent = 'Upload failed: ' + data.detail; return; }
  docId = data.doc_id;
  status.textContent = 'Loaded "' + data.filename + '": ' + data.pages +
    ' pages, ' + data.characters + ' characters, split into ' +
    data.chunks + ' chunks. You can ask questions now.';
}

async function askQuestion() {
  const answer = document.getElementById('answer');
  const meta = document.getElementById('askMeta');
  if (!docId) { answer.textContent = 'Upload a PDF first.'; return; }
  const question = document.getElementById('question').value;
  answer.textContent = 'Thinking…';
  const res = await fetch('/ask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ doc_id: docId, question: question })
  });
  const data = await res.json();
  if (!res.ok) { answer.textContent = 'Error: ' + data.detail; meta.textContent = ''; return; }
  answer.textContent = data.answer;
  meta.textContent = 'Used ' + data.chunks_used + ' chunks · ' +
    data.input_tokens + ' input tokens · ' + data.output_tokens +
    ' output tokens · about $' + data.estimated_cost_usd.toFixed(6);
}
</script>
</body>
</html>"""

The page is deliberately plain: one file input, one question box, and a status line that repeats the server’s own counts back to you. That line is your first debugging tool — it proves the server read the file before you blame the model for a bad answer.

Step 4 — Run it and watch it work

uvicorn app:app --reload

Open http://127.0.0.1:8000. The test run behind this post uploaded a two-page community-garden handbook written as a sample document. The server’s real response:

{"doc_id": "979808d3", "filename": "sample.pdf", "pages": 2, "characters": 856, "chunks": 2}

Two pages became 856 characters became two chunks — small numbers, because the sample is small, but the pipeline is identical at 200 pages. The same flow works without the browser:

curl -F "file=@sample.pdf" http://127.0.0.1:8000/upload
curl -X POST http://127.0.0.1:8000/ask -H "Content-Type: application/json" \
  -d '{"doc_id": "YOUR_DOC_ID", "question": "When is the lottery draw?"}'

Errors you may hit

422 — “No readable text was found in that PDF.” The file parsed but has no text layer — the classic scanned or image-only PDF. This app does not OCR; run the document through an OCR tool first. (Verified: an image-only test PDF returns exactly this.)

413 — “That file is over the 10 MB limit.” The cap is a constant at the top of app.py. Raise it deliberately if needed — a bigger PDF means more chunks, and retrieval, not the context window, keeps questions cheap.

400 — “Please upload a PDF file.” The filename does not end in .pdf. A renamed text file fails here or in extraction, with “Could not read that file as a PDF”.

404 — “Unknown document.” The id is wrong, or the server restarted and forgot every upload — the in-memory store working as designed. Upload again.

500 — “GEMINI_API_KEY is not set on the server.” The key is missing from the server’s environment. Setting it in a different terminal does not count; set it in the window running uvicorn, then restart.

502 — “Gemini API error: …” The call failed — invalid key, exhausted free-tier quota, or a network problem. The text after the colon is the API’s own error; fix that, not the app.

A 404 inside that 502 — “This model … is no longer available to new users.” Google retires model names for new keys first. If your key is recent and the error names a replacement model, update the MODEL constant at the top of app.py to the one it names. This post pins gemini-3.8-flash for exactly this reason: the first test run pointed at gemini-2.5-flash, and a freshly created key could not reach it at all.

The answer misses your question’s meaning. Retrieval found chunks that share words but not intent, or the passage uses different words than your question. Rephrase with the document’s own vocabulary — or take it as the signal to build the embeddings upgrade below.

Where to go next

Three upgrades, in the order a production version needs them: persistent storage (a database or disk store instead of the in-memory dictionary), embeddings-based retrieval (semantic matching instead of word overlap), and authentication (this app trusts everyone who can reach the port).

Previous: MCP Servers Explained — Give Your AI Agent Real Tools. Next in Small AI Apps: decided by what readers actually run — tell us in the comments.

Enjoying these tutorials?

Get new Visual Studio Learn posts by email — free, no spam:

Follow along: YouTube · Facebook · RSS

MCP Servers Explained: Give Your AI Agent Real Tools

2026-10-22T09:07:00.000-04:00

Versions used in this post — read this first: Python 3.12 · MCP Python SDK mcp 2.3.0 (specification revision 2026-07-28) · Transport: stdio · No API key, no account. Version note that matters: SDK v2 renamed the class most older tutorials use — code importing FastMCP was written for v1 and will not run on v2. This post uses MCPServer throughout.

The direct answer

MCP — the Model Context Protocol — is a standard way for an AI application to discover and call tools that live outside the model. Instead of every framework inventing its own plugin format, a tool is packaged once as an MCP server, and any MCP-aware host can list its tools, read their input schemas, and call them over a defined protocol.

In the previous post, the tools lived inside the same file as the agent. That works for one program. MCP is for when a tool should outlive it — usable by a second agent, a different host, or next month's project.

Host, client, server — in plain words

Three roles appear in every MCP setup, and most confusion comes from mixing them up:

Host — the application the person uses: an AI coding assistant, a chat app with tool support, or your own agent program. It owns the model connection.
Client — the connector inside the host, one per server. It opens the connection, performs the handshake, and forwards tool calls.
Server — a separate program that offers tools and answers when called. It has no model of its own. Ours offers two tools over a local SQLite database. Client and server exchange JSON-RPC messages, here over stdio: the server is a subprocess, talking over its standard input and output. Streamable HTTP exists for shared servers; stdio is the right start — no port, no hosting, nothing exposed beyond your machine.

What you will build

A server named project-notes with two read-only tools over a tiny notes database the code creates and seeds itself — search_notes (finds notes containing a keyword) and recent_notes (lists the newest) — plus a small Python client that starts the server and calls both: the same handshake a full AI host performs, with no model in between.

Get the code

All the code in this post lives in the companion GitHub repository, in the topic-02-mcp-server folder — with a README that covers prerequisites, environment setup, install, and how to run and use it. If you would rather follow along here, every step is also written out below.

Step 1 — Set up (no key, no account, nothing to buy)

This build needs no API key and no account: an MCP server is ordinary local code, and testing it involves no model at all. If you later connect it to an AI host, signing in is the host's own setup.

Check you have Python 3.10 or newer (this post uses 3.12): run python --version. On Windows, if the Store opens instead, install Python from python.org and tick "Add python.exe to PATH".

Create a folder called mcp-notes, open a terminal in it, and create a virtual environment:

# macOS / Linux
python3 -m venv .venv && source .venv/bin/activate

# Windows PowerShell
py -m venv .venv ; .venv\Scripts\Activate.ps1

Install the SDK, pinned (the [cli] extra adds the mcp command Step 3 uses):
```
pip install "mcp[cli]==2.3.0"
```

Step 2 — Write the server

"""A tiny MCP server that searches a local project-notes database."""

import json
import sqlite3
from pathlib import Path

from mcp.server import MCPServer

DB_PATH = Path(__file__).with_name("notes.db")

SEED_NOTES = [
    ("Deploy checklist", "Build the image, run the tests, tag the release, then deploy.", "deploy"),
    ("Database backup", "Take a full backup before any schema change and verify the restore.", "database"),
    ("Grafana alert idea", "Alert when the error rate stays above two percent for ten minutes.", "monitoring"),
    ("FastAPI startup fix", "The startup error came from a missing environment variable, not the code.", "fastapi"),
]


def _connect() -> sqlite3.Connection:
    """Open the notes database, creating and seeding it on first use."""
    conn = sqlite3.connect(DB_PATH)
    conn.execute(
        "CREATE TABLE IF NOT EXISTS notes "
        "(id INTEGER PRIMARY KEY, title TEXT, body TEXT, tag TEXT)"
    )
    count = conn.execute("SELECT COUNT(*) FROM notes").fetchone()[0]
    if count == 0:
        conn.executemany(
            "INSERT INTO notes (title, body, tag) VALUES (?, ?, ?)", SEED_NOTES
        )
        conn.commit()
    return conn


mcp = MCPServer("project-notes")


@mcp.tool()
def search_notes(keyword: str, limit: int = 5) -> str:
    """Search project notes for a keyword in the title or body.

    Args:
        keyword: Word or phrase to look for, for example "backup".
        limit: Maximum number of notes to return, between 1 and 20.
    """
    limit = max(1, min(limit, 20))
    like = f"%{keyword}%"
    with _connect() as conn:
        rows = conn.execute(
            "SELECT id, title, body, tag FROM notes "
            "WHERE title LIKE ? OR body LIKE ? ORDER BY id LIMIT ?",
            (like, like, limit),
        ).fetchall()
    if not rows:
        return json.dumps({"matches": [], "message": f"No notes match '{keyword}'."})
    return json.dumps(
        {
            "matches": [
                {"id": r[0], "title": r[1], "body": r[2], "tag": r[3]} for r in rows
            ]
        }
    )


@mcp.tool()
def recent_notes(limit: int = 3) -> str:
    """List the most recently added project notes.

    Args:
        limit: How many recent notes to return, between 1 and 20.
    """
    limit = max(1, min(limit, 20))
    with _connect() as conn:
        rows = conn.execute(
            "SELECT id, title, tag FROM notes ORDER BY id DESC LIMIT ?", (limit,)
        ).fetchall()
    return json.dumps(
        {"notes": [{"id": r[0], "title": r[1], "tag": r[2]} for r in rows]}
    )


if __name__ == "__main__":
    mcp.run(transport="stdio")

Save it as server.py. Three things do more work than they appear to. The type hints are the contract: keyword: str and limit: int = 5 become the tool's JSON input schema automatically — no schema is written by hand. The docstring is the description the model reads, so write it as instructions to a careful colleague. And the SQL is parameterized: tool arguments are untrusted input — they may come from a model acting on text someone else wrote — and binding the keyword as a parameter keeps a hostile keyword from becoming hostile SQL. Both tools are read-only, and limit is clamped.

Step 3 — Look at your server in the Inspector

Before writing client code, inspect the server the way a host sees it:

mcp dev server.py

This starts the MCP Inspector, a local web page that connects as a client. Open the address it prints, choose List Tools, and you should see both tools with their generated schemas. Call search_notes with the keyword backup. If it works here, the server half is done — later failures live in the client or host configuration.

Running python server.py directly appears to do nothing. That is correct, not a hang: a stdio server waits silently for a client to speak first.

Step 4 — Connect a client and call a tool

Save this as client.py in the same folder:

"""A small MCP client that connects to server.py and calls its tools."""

import asyncio
import sys

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


async def main() -> None:
    params = StdioServerParameters(
        command=sys.executable,
        args=["server.py"],
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print("Tools:", [tool.name for tool in tools.tools])

            result = await session.call_tool(
                "search_notes", arguments={"keyword": "backup"}
            )
            print("search_notes ->", result.content[0].text)

            result = await session.call_tool(
                "recent_notes", arguments={"limit": 2}
            )
            print("recent_notes ->", result.content[0].text)


if __name__ == "__main__":
    asyncio.run(main())

Note command=sys.executable: the client starts the server with the same Python running the client, so the server inherits the venv where the SDK is installed. Pointing a host at a python that resolves elsewhere is the most common reason a working server "cannot connect."

Run it with python client.py. Actual output, run against SDK 2.3.0:

Tools: ['search_notes', 'recent_notes']
search_notes -> {"matches": [{"id": 2, "title": "Database backup", "body": "Take a full backup before any schema change and verify the restore.", "tag": "database"}]}
recent_notes -> {"notes": [{"id": 4, "title": "FastAPI startup fix", "tag": "fastapi"}, {"id": 3, "title": "Grafana alert idea", "tag": "monitoring"}]}

Read it as a conversation: subprocess started, handshake completed, two tools discovered, two calls answered with parseable JSON. Put a model in the host's seat and nothing about the server changes. That separation is the entire point of the protocol.

To use the server from a real host, give the host the same launch information in its configuration (file locations differ per host; use absolute paths):

{
  "mcpServers": {
    "project-notes": {
      "command": "C:\\path\\to\\mcp-notes\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\mcp-notes\\server.py"]
    }
  }
}

Save, fully restart the host, and the two tools should appear in its tool list.

Errors you may hit

ModuleNotFoundError: No module named 'mcp.server.fastmcp', with a note that FastMCP was renamed. You — or your tutorial — are running v1 code on SDK v2. Change the import to from mcp.server import MCPServer, as here, or pin the old line with pip install "mcp<2". The generations cannot be mixed.

The server "hangs" and prints nothing. It is waiting on stdio for a client; test it with mcp dev or client.py. The mirror-image mistake is worse: a debugging print() inside the server corrupts the JSON-RPC stream on stdout. Log to stderr, or not at all.

A validation error names the argument you got wrong. These are real outputs from this server: a missing argument returns Field required for keyword; passing "five" where an integer belongs returns Input should be a valid integer, unable to parse string as an integer. Both arrive as tool errors, not crashes, so the caller can retry corrected. An unregistered name returns Unknown tool: plus the name — print list_tools() first, as client.py does.

The host cannot start the server, or finds nothing. In order: the Python launched is not the venv's Python (use its full path); the server.py path is relative or wrong (use absolute paths, then restart the host — most read this configuration only at startup); or the SDK sits in a different environment. The Step 3 test separates these: if mcp dev works from your venv, the server is innocent and the launch line is at fault.

Where to go next

Grow this server as real work pulls it: swap the seed data for your own notes, add a third tool only when a real question needs it, and keep every tool narrow, read-only until a write is required, and honest in its docstring.

Previous: building the tool-calling loop by hand, in Python. Next: a complete small AI app — a PDF Q&A tool built with FastAPI.

Build Your First AI Agent in Python (Tool-Calling, Step by Step)

2026-10-20T09:07:00.000-04:00

Versions used in this post — read this first: Python 3.12 · google-genai 1.35.0 · model gemini-2.5-flash · No framework, no LangChain. Everything below runs from one file. If a newer SDK changes a method name, the loop in Step 4 stays the same — only the call syntax moves.

The direct answer

An AI agent is not a special kind of model. It is a normal program that does three things in a loop: it sends your question and a list of tools to a model, it runs whichever tool the model asks for, and it sends the tool result back so the model can answer — or ask for another tool. Execution stays with your program from start to finish — the model only ever asks.

This post builds that loop by hand, on purpose. Frameworks hide the loop, and the loop is the part you need when something breaks in production.

What you will build

A small command-line agent with two tools:

Weather lookup — gets the current temperature and wind for a city from the free Open-Meteo service, which needs no API key.
Calculator — evaluates arithmetic safely, without using Python's eval().

You can ask it a question that needs both, such as: "Is it warmer in Ottawa or Toronto right now, and what is the difference times two?" The agent should call the weather tool twice, call the calculator once, and then answer in plain language.

Get the code

All the code in this post lives in the companion GitHub repository, in the topic-01-first-ai-agent folder — with a README that covers prerequisites, environment setup, install, and how to run and use it. If you would rather follow along here, every step is also written out below.

Step 1 — Install and set your key

Create a folder, then install the single dependency:

pip install google-genai==1.35.0

Get a Gemini API key from Google AI Studio and set it as an environment variable. Never paste a key into source code that you might commit.

How to get your free Gemini API key (about 2 minutes, no card required):

Open Google AI Studio and sign in with your Google account. Accept the terms if it is your first visit.
Click Get API key (in the left sidebar, or on the dashboard).
Click Create API key, then choose Create API key in new project — the simplest option for a first key.
Google generates the key and shows it to you. Click Copy. A Gemini key starts with "AIza".
Treat the key like a password: anyone who has it can use your quota. Never post it publicly, never commit it to GitHub, and if it ever leaks, delete it on the same page and create a fresh one.
Now set it as the GEMINI_API_KEY environment variable with the commands below — the code reads it from there, so the key never lives in your source.

The free tier is enough for everything in this post. You only need billing if you outgrow the free rate limits — and the 429 error in the errors section below is how you will know.

# macOS / Linux
export GEMINI_API_KEY="your-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY="your-key-here"

Step 2 — Write the two tools

A tool is just a Python function with a clear name, typed arguments, and a short docstring. The docstring matters more than usual here: the model reads it to decide when the tool applies, so write it for the model, not only for humans.

import ast
import json
import operator
import urllib.parse
import urllib.request


def get_weather(city: str) -> dict:
    """Get the current weather for a city.

    Args:
        city: City name, for example "Ottawa" or "Toronto".
    Returns:
        Temperature in Celsius, wind speed, and a condition code.
    """
    query = urllib.parse.quote(city)
    geo_url = f"https://geocoding-api.open-meteo.com/v1/search?name={query}&count=1"
    with urllib.request.urlopen(geo_url, timeout=10) as response:
        places = json.load(response).get("results")
    if not places:
        return {"error": f"No location found for {city}"}

    place = places[0]
    weather_url = (
        "https://api.open-meteo.com/v1/forecast"
        f"?latitude={place['latitude']}&longitude={place['longitude']}"
        "&current=temperature_2m,wind_speed_10m,weather_code"
)
    with urllib.request.urlopen(weather_url, timeout=10) as response:
        current = json.load(response)["current"]
    return {
        "city": place["name"],
        "temperature_c": current["temperature_2m"],
        "wind_kmh": current["wind_speed_10m"],
        "weather_code": current["weather_code"],
}


_OPERATORS = {
    ast.Add: operator.add,
    ast.Sub: operator.sub,
    ast.Mult: operator.mul,
    ast.Div: operator.truediv,
    ast.USub: operator.neg,
}


def _eval_node(node):
    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
        return node.value
    if isinstance(node, ast.BinOp) and type(node.op) in _OPERATORS:
        return _OPERATORS[type(node.op)](_eval_node(node.left), _eval_node(node.right))
    if isinstance(node, ast.UnaryOp) and type(node.op) in _OPERATORS:
        return _OPERATORS[type(node.op)](_eval_node(node.operand))
    raise ValueError("Expression contains something the calculator does not allow")


def calculate(expression: str) -> dict:
    """Calculate a basic arithmetic expression.

    Args:
        expression: Arithmetic only, for example "18.5 - 16.0" or "(4 + 6) * 2".
    Returns:
        The numeric result, or an error message if the expression is not allowed.
    """
    try:
        tree = ast.parse(expression, mode="eval")
        return {"expression": expression, "result": _eval_node(tree.body)}
    except Exception as exc:
        return {"error": f"Could not calculate '{expression}': {exc}"}

Notice the calculator's design: it parses the expression into a tree and allows only numbers and five operators. Passing a model's output into eval() would let a bad prompt become arbitrary code execution. Treat every tool argument as untrusted input, because it is.

Step 3 — Write the agent loop

This is the whole agent. Automatic function calling is switched off deliberately, so you can watch each round trip instead of having the SDK hide it.

import os

from google import genai
from google.genai import types

TOOLS = {"get_weather": get_weather, "calculate": calculate}
MAX_STEPS = 6


def run_agent(question: str) -> str:
    client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
    config = types.GenerateContentConfig(
        tools=list(TOOLS.values()),
        automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
        system_instruction=(
            "Use the tools when you need live weather or arithmetic. "
            "Do not guess temperatures or do maths in your head."
),
)
    contents = [question]

    for step in range(1, MAX_STEPS + 1):
        response = client.models.generate_content(
            model="gemini-2.5-flash",
            contents=contents,
            config=config,
)
        if not response.function_calls:
            return response.text

        contents.append(response.candidates[0].content)
        for call in response.function_calls:
            tool = TOOLS.get(call.name)
            if tool is None:
                result = {"error": f"Unknown tool: {call.name}"}
            else:
                result = tool(**call.args)
            print(f" step {step}: {call.name}({call.args}) -> {result}")
            contents.append(
                types.Part.from_function_response(name=call.name, response=result)
)

    return "Stopped: the agent used all of its steps without finishing."


if __name__ == "__main__":
    answer = run_agent(
        "Is it warmer in Ottawa or Toronto right now, "
        "and what is the temperature difference times two?"
)
    print("\nAnswer:", answer)

Step 4 — How the loop works, round by round

You send the question plus the tool list. The model sees the function names, arguments, and docstrings — not the function bodies.
The model replies with a request, not an answer. For our question, the first reply asks for get_weather for Ottawa and Toronto. Nothing has run yet.
Your code validates and runs the tools. This is your security boundary. Check the tool name, check the arguments, and only then execute.
You send the results back. The results become new entries in contents, so the model can reason over real numbers instead of inventing them.
The loop repeats or ends. The model may ask for the calculator next. When a reply contains no function call, that reply is the final answer and the loop stops.
A step cap protects you. MAX_STEPS = 6 guarantees the program ends. An agent without a cap can loop — and bill you — for a very long time.

How to run it and what you should see

Save both parts in one file named first_agent.py, then run:

python first_agent.py

The exact temperatures will differ every run, but the shape should look like this:

 step 1: get_weather({'city': 'Ottawa'}) -> {'city': 'Ottawa', 'temperature_c': 9.4,...}
  step 1: get_weather({'city': 'Toronto'}) -> {'city': 'Toronto', 'temperature_c': 12.1,...}
  step 2: calculate({'expression': '(12.1 - 9.4) * 2'}) -> {'result': 5.4}

Answer: Toronto is warmer right now, at 12.1°C compared with 9.4°C in Ottawa — a difference of 2.7 degrees, which doubled is 5.4.

If the printed tool calls are missing, the model answered from memory instead of using the tools. Strengthen the system instruction rather than adding more code — wording is a real control surface here.

Errors you may hit

KeyError: 'GEMINI_API_KEY' or a 400 API key error. The variable is not set in the same terminal session that runs the script, or the key was copied with a trailing space. Check only whether the variable exists — never print the key — and restart the terminal after setting it system-wide.

The model asks for a tool that does not exist. Models occasionally invent a plausible function name. That is why the loop looks the name up in TOOLS and returns an error result instead of crashing. The model usually corrects itself on the next step.

Malformed or missing arguments. A call may arrive with a city missing or an expression that is not arithmetic. Both tools above return an {"error":...} dictionary rather than raising, so the agent gets a chance to recover and the conversation does not die on one bad call.

429 rate-limit or quota errors. Free-tier keys have per-minute and per-day limits, and a loop multiplies requests: one question here costs three or four model calls. Add a short pause and retry on 429, lower MAX_STEPS, and expect this error during busy testing rather than treating it as a code bug.

503 or a temporary model error. Transient failures happen on hosted models. Retry a few times with increasing waits before changing your code — and log which step failed, so you know whether the failure was the model call or your own tool.

What does one run actually cost?

Honest answer: very little — but not zero, and the loop is why. A two-city question typically uses roughly 1,000–1,500 input tokens and 150–250 output tokens across all its model calls. At the published gemini-2.5-flash paid rates of US$0.30 per million input tokens and US$2.50 per million output tokens, that is well under a tenth of a cent per question. On the free tier, the same run counts against your daily quota instead.

Do not trust my estimate for your own app. Every response carries usage data, so build the habit on day one of logging response.usage_metadata for each step. Cost surprises almost never come from one expensive call. They come from a loop that quietly ran forty cheap ones.

Where to go next

Add one tool that touches your own world — reading a folder of notes, querying a small database, or checking a calendar — and keep the same discipline: typed arguments, errors returned as data, a hard step cap, and a log line for every call. That pattern, not any framework, carries from this script to larger agent systems, including the Gemini integration behind my own AI Portfolio Manager app.

Next in this series: MCP servers — the standard way to package tools like these so more than one agent can use them.

Create Installer Projects in Visual Studio 2013

2016-07-20T23:30:00.000-04:00

After completing the development of your desktop Application. The next phase is to deployment or installation of that application.

For this you need to create a setup of your project, then you just need to give the setup file to the users or your client so they can install and use your application.

In Visual Studio 10 or prior edition, has built in functionality to create setup file using Installer Projects. But in Visual Studio 13 and next edition you need to install an extension first and then you can create.

Android Development Step by step

2016-07-18T23:30:00.000-04:00

Android is a mobile operating system developed by Google. It is primarily designed for Touchscreen mobile devices such as smartphone and tablets.
As we know, a large number of audience is using Android smartphone. So you have a huge market to publish your android apps on play store.

Online Base64 Encode and Decode

2016-07-16T23:30:00.000-04:00

In my previous post, I have shared the basic introduction of base64 encode and decode and it uses.

I have also shared the code How you can base64 encode and decode a string in C#, Java, and Object-c.

I have built a simple java script based tool, which online converts the string to Base64 encode and base64 decode. At the end of this post will get the source code of this tool and the code snippet to share this tool on your own site.

Base64 Encode and Decode

2016-07-14T23:30:00.000-04:00

Base64 is used for converting arbitrary binary data to ASCII text so, that it's become easier to transmitted the data over the network like e-mail and HTML form data.

In simple words, it turns binary data into plain ASCII text, so the data can travel safely through systems that only handle text, such as email or HTML forms. (Source: Wikipedia).

Auto Generate Classes from JSON or XML In Visual studio .Net

2016-07-13T00:00:00.000-04:00

It is very hard to convert the JSON or XML output of Web service or Web API to Model or Object Classes manually.

The best way to handle service response data is, to Deserialize the JSON or XML response into class Object.

For this, you need to create mapping classes for that JSON response. Today I will show you how you can easily and quickly create these classes which are auto-generated by a Visual studio.

jQuery Form Validation Sample Example

2014-06-30T15:00:00.000-04:00

jQuery is JavaScript library containing a lot of important and usable function which facilitate our Application. Java script is client side language and which run on client browser.

In most of web application we have to validate user input before submitting to Server. You can validate user input on Client side using Java script or jQuery and on Server Side using server side programming language like PHP, Asp.net, Java and etc.But when you validate input to server side then first request send to server with all user Inputs, then it check whether these input are correct or not the return to client to display error.

How to add hyperlink to table row <tr> ?

2014-06-28T14:30:00.000-04:00

If you having a table with its table row <tr> generating in a loop to form multiple rows.

If you want to give separate <a> link to each <tr>. Since in table we can add only add data to <td> only, you are not able to achieve that.

There is a way to achieve it which is following.

Free Host or Deploy Asp.net Web Application on somee

2014-06-26T15:00:00.000-04:00

During graduation we had created a lot of academics .net web application project which are small but interesting. We could not deploying these project to Asp.net hosting Server because it was very expensive and we just deploy it locally and presented it to our teacher.

But now there are a lot of site which allow us to freely deploy asp.net web application. somee.com is one of them.

Host JavaScript and CSS files for Blogger and How to use Google Code?

2014-06-25T15:00:00.000-04:00

Blogger and web designer know how much we should care about coding assets, JavaScript files and css etc where to host it ? and manage it.

Now in present user experience is more important if user feel bad experience form UI then it will effect site visit and ranking.

There are many widget JavaScript and CSS script that makes you site better.

But most off time we have to Upload or host some of these script file to a hosting server.

Google Search Tip and access site through FTP anonymously.

2014-06-24T15:00:00.000-04:00

Google is giant of Technologies. Google Search engine is now helping every one students, teachers etc to his respective search.Students use it for school, business people use it for research, and millions more use it for entertainment.

In this tutorial I will show widely use Google Search Tip and How to access site through FTP anonymously.

Did you know that you may not be using Google search to its full potential ?

There are few amazing tip by using you can access interesting and relevant data quickly and efficiently.

Howe to create site map for Blogger

2014-01-04T14:30:00.000-05:00

Today! I will discuss a tutorial about on How To Create A Sitemap For Blogger Blog. For those who don’t know, Why do we need to create sitemap to our blog?
Basically Sitemap is a list of pages (directory or table of content) of our blog site to easily navigate our blog post.

Actually this is not a sitemap in Google Webmaster Tool this is only a widget developed by Visual studio learn.
Site map get Attention of Search Engine Robot's in your Blogger Blog using Blogger Site Map And RSS/Atom Feed, Sitemap basically help to improving your Blog visibility to Search Engine, And also help to increasing your Tariff and Page ranking of Site/blog, here be describe a simple way to Create a visible Site map for Your Blogger Blog, and add to in menu Bar and any where you Want, and Get Fully optimization of Search Engine Robot's, Follow Some Below Steps to Create a Site Map For Blogger.

Java Script TRIM, LTRIM and RTRIM Function

2014-01-01T14:00:00.000-05:00

Today I will show you how to make TRIM Function in Java Script .
From this tutorial you can easily write RTRIM and LTRIM function.
This Function is very useful you can also make you own TRIM function to filtering user input, Preventing Basic SQL Injection and verify or correct user input.

Convert number to words

2013-12-19T14:00:00.000-05:00

Today I will show you how to Convert numbers or Amount in words.

This is simple but mostly used tool / function in many Applications.

It is also used in reporting to display amount in words form.

I am writing simple programs which converts numbers into word in Java but can also make it in other languages like C#, Php, JavaScript etc easily.

Send Email in Java

2013-12-04T14:00:00.000-05:00

Today I will share how to Send Email in java programming language.

In this post I use G mail SMTP to send Email.

Auto increment Column in Oracle

2013-08-25T15:00:00.000-04:00

To day I will show you how to create Auto increment column in oracle which may be use as Primary Key .

In My Sql and Sql Server Data bases it very easy to create auto increment column but in oracle you must have to follow some step to Create an Auto increment column.

Log/Audit Table in Oracle and SQL SERVER

2013-08-21T03:02:00.000-04:00

Today i will explain you Why we create Log/Audit table, How it helps us in various situations and How to create Log table and audit table.

In this tutorial we will Learn How to create Trigger in Oracle and Sql server.

In this article I use both databases Oracle and SQL Server.

By creating log tables, data base automatically logging of changes to several of our database tables.

Get Client IP Address, Host name and Current User in Oracle and SQL Server

2013-08-20T03:04:00.000-04:00

Today I show how to get Client IP Address, Host name and Current Data base user in Sql Server and Oracle.

It is very useful for security purposes and in case of any illegal or unauthorized activity is performed on your database so you can Track and Trace how, when and who performed that illegal or unauthorized activity.

Unrecognized attribute 'targetFramework'. Note that attribute names are case-sensitive

2013-05-28T03:00:00.000-04:00

This Error would be occurred due to wrong Framework settings in Web.config file or in IIS Server.
Following are cases Which will help you solving this error.

The requested page cannot be accessed because the related configuration data for the page is invalid

2013-05-26T23:29:00.000-04:00

This Error would be occurred by some of Following reasons.

Visual Studio Learn

Does the 118K-Star AI Trading Agent Actually Work? I Installed and Tested TradingAgents v0.7.1 — Open-Source Agent, Tested #1

The direct answer

What this test is (and is not)

Meet the framework: a firm, not a chatbot

Environment setup — do this first

How a run works

The test run

Errors you may hit

The verdict

Get the code

Sources

Enjoying these tutorials?

Get new posts by email:

How Do I Deploy a FastAPI App to Azure App Service? Step by Step, From Zero

The direct answer

The finished thing first

What you will build

Environment setup — do this first

The app — one file, three endpoints

The two files Azure cares about

Step 1 — Create the resources (portal and CLI, side by side)

Step 2 — App settings

Step 3 — Deploy the zip

Step 4 — The staged failure (deliberate, and the point of the post)

The shortcut — az webapp up

Errors you may hit

What it costs

Delete it when you're done (yes, really)

Where to go next

Get the code

Sources

Enjoying these tutorials?

Get new posts by email:

I Built an AI Agent That Reads Release Notes So I Don't Have To

The direct answer

What you will build

Environment setup — do this first

Step 1 — Config, data shapes, and stripping the HTML

Step 2 — Fetch the newest release from the feed

Step 3 — Ask Gemini for bullets and breaking changes

Step 4 — Assemble the digest and run

Step 5 — Run it, and read the digest

Scheduling it daily

Errors you may hit

Where to go next

Get the code

Sources

Enjoying these tutorials?

Get new posts by email:

Small AI App #1: Build a PDF Q&A App with FastAPI + Gemini (Upload a PDF, Ask It Questions)

The direct answer

What you will build

Get the code

Environment setup — do this first

Step 1 — The document pipeline: extract, chunk, retrieve

Step 2 — The two endpoints

Step 3 — The web page

Step 4 — Run it and watch it work

Errors you may hit

Where to go next

Enjoying these tutorials?

Get new posts by email:

MCP Servers Explained: Give Your AI Agent Real Tools

The direct answer

Host, client, server — in plain words

What you will build

Get the code

Step 1 — Set up (no key, no account, nothing to buy)

Step 2 — Write the server

Step 3 — Look at your server in the Inspector

Step 4 — Connect a client and call a tool

Errors you may hit

Where to go next

Build Your First AI Agent in Python (Tool-Calling, Step by Step)

The direct answer

What you will build

Get the code

Step 1 — Install and set your key

Step 2 — Write the two tools

The shortcut — `az webapp up`