mirror of https://github.com/agno-agi/agno.git synced 2026-10-12 02:10:54 +00:00

Files

T

Ashpreet c7c5adcc60 cookbook: overhaul agent quickstart for Gemini 3.6 Flash (#9136 )

## Summary

Overhauls `cookbook/00_quickstart` into a coherent capability ladder:
build one useful agent, add context and learning, introduce safety and
human approval, then scale to teams, workflows, and AgentOS.

- Upgrades every active quickstart model to the stable
`gemini-3.6-flash` ID.
- Repositions the README around **Build an Agent That Can Act, Remember,
and Improve**, with a minimal first success and clear Core → Context →
Trust → Scale → Ship progression.
- Replaces the hand-built self-learning demo with the canonical
`LearningMachine` and shared learned knowledge.
- Fixes misleading guardrail status handling, structured-output truth
claims, optional-value handling, and cross-session memory behavior.
- Gives each stateful example isolated SQLite/Chroma storage and stable
session IDs.
- Makes knowledge deterministic with a versioned local fixture.
- Reworks human approval to verify both approve and reject paths.
- Narrows tool exposure, refreshes AgentOS prompts/registration, and
regenerates a lean Agno 2.8 dependency lock.
- Adds a repeatable live test plan and preserves the historical Gemini
3.5 verification record.

This makes the folder useful as both a newcomer journey and a set of
standalone, copyable agent patterns.

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [x] Improvement
- [x] Model update
- [ ] Other:

---

## Checklist

- [x] Code complies with style guidelines
- [x] Ran format/validation scripts (`./scripts/format.sh` and
`./scripts/validate.sh`)
- [x] Self-review completed
- [x] Documentation updated (comments, docstrings)
- [x] Examples and guides: Relevant cookbook examples have been included
or updated (if applicable)
- [x] Tested in clean environment
- [x] Tests added/updated (if applicable)

### Duplicate and AI-Generated PR Check

- [x] I have searched existing [open pull requests](../../pulls) and
confirmed that no other PR already addresses this issue
- [x] If a similar PR exists, I have explained below why this PR is a
better approach
- [x] Check if this PR was entirely AI-generated (by Copilot, Claude
Code, Cursor, etc.)

---

## Additional Notes

Validation completed against Agno `2.8.0`, `google-genai==2.14.0`, and
Gemini 3.6 Flash:

- 12/12 quickstart cookbooks passed live behavioral checks.
- AgentOS passed with 10 agents, 1 team, and 1 workflow; `/health` and
`/config` returned successfully.
- Approval/rejection, guardrail failure paths, cross-session memory, and
process-restart persistence passed.
- Focused unit suite: 82 passed, 1 skipped.
- `./scripts/format.sh`, `./scripts/validate.sh`, `compileall`, cookbook
pattern checks, and `git diff --check` passed.
- An independent final diff review found no remaining correctness
issues.

The global Gemini framework default is intentionally unchanged; this PR
only updates the quickstart folder. Historical Gemini 3.5 results remain
in `TEST_LOG.md` under a clearly labeled historical section.

Prepared with Codex under user direction and validated with live model
calls plus repository gates.

2026-07-23 23:22:18 +01:00

3.6 KiB

Raw Permalink Blame History

Quickstart Live Test Plan

Use this plan when the model, Agno version, dependencies, or quickstart code changes. Record the result in TEST_LOG.md; do not replace historical runs.

Test Contract

Run live examples from the repository root against the quickstart environment:

source .venvs/quickstart/bin/activate
export GOOGLE_API_KEY=your-google-api-key

Record:

Date and timezone
Git commit
Python version
Installed Agno version
Model ID
Whether tmp/quickstart/ started empty

Do not use transient stock prices as the pass condition. Verify behavior and artifacts instead.

Preflight

Use the repository development environment for static checks:

.venv/bin/python cookbook/scripts/check_cookbook_pattern.py \
  --base-dir cookbook/00_quickstart
.venv/bin/python -m compileall -q cookbook/00_quickstart
.venv/bin/ruff check cookbook/00_quickstart

Expected: all commands exit 0.

Live Matrix

Cookbook	Acceptance Condition
`agent_with_tools.py`	Gemini calls at least one enabled Yahoo Finance tool and returns a concise brief
`agent_with_structured_output.py`	`response.content` is `StockAnalysis`; enum and numeric constraints validate
`agent_with_typed_input_output.py`	Dict and Pydantic inputs both work; invalid input fails before a model call
`agent_with_storage.py`	A fixed session connects the follow-up to prior context; rerunning the process restores it
`agent_with_memory.py`	A durable preference is stored and recalled for the same `user_id` in a different explicit session
`agent_with_state_management.py`	Tools update the watchlist; the fixed session restores it after a process restart
`agent_search_over_knowledge.py`	The document loads, the knowledge-search tool runs, and the answer is grounded in retrieved content
`agent_with_learning.py`	The teaching run saves learned knowledge; a different user receives the reusable rule
`agent_with_guardrails.py`	Normal input completes; PII, injection, and spam return `RunStatus.error` without a model call
`human_in_the_loop.py`	The run pauses on `publish_research_brief`; approval executes it; rejection does not
`multi_agent_team.py`	Both members run and the leader synthesizes their disagreement
`sequential_workflow.py`	Data Gathering, Analysis, and Report Writing complete in order

Run live examples individually. human_in_the_loop.py is interactive and run.py starts a server, so neither belongs in an unattended folder runner.

Failure Paths

Test these explicitly:

Run agent_with_guardrails.py and confirm blocked inputs are labeled [BLOCKED], never [OK].
Run human_in_the_loop.py once with y and once with n.
Pass malformed JSON and an invalid ticker to the typed-input agent; both must fail validation before Gemini is called.
Stop and restart the storage and state scripts; use the same session IDs and confirm the persisted data is restored.

AgentOS

Start the runtime:

python cookbook/00_quickstart/run.py

In another terminal:

curl -fsS http://localhost:7777/health
curl -fsS http://localhost:7777/config

Expected:

/health returns status ok
/config lists 10 agents, 1 team, and 1 workflow
Every ID in config.yaml resolves to a registered component
A normal agent run succeeds through the API
The human-approval agent surfaces a pending confirmation

Final Gates

.venv/bin/ruff format --check cookbook/00_quickstart
.venv/bin/ruff check cookbook/00_quickstart
git diff --check

Update TEST_LOG.md with behavioral evidence, known limitations, and any failure that required a retry.

3.6 KiB Raw Permalink Blame History