diff --git a/README.md b/README.md
index 0d39b11..b3b5b10 100644
--- a/README.md
+++ b/README.md
@@ -74,7 +74,7 @@ This repository provides a comprehensive, hands-on comparison of modern AI agent
-
3.0.9 |
+ 3.1.10 |
diff --git a/agno/22_conversation_compaction.py b/agno/22_conversation_compaction.py
new file mode 100644
index 0000000..77d52bb
--- /dev/null
+++ b/agno/22_conversation_compaction.py
@@ -0,0 +1,95 @@
+import os
+
+from dotenv import load_dotenv
+
+from agno.agent import Agent
+from agno.compaction import Compaction
+from agno.db.sqlite import SqliteDb
+from agno.models.openai import OpenAIChat
+
+from settings import settings
+
+load_dotenv()
+
+"""
+-------------------------------------------------------
+In this example, we explore Agno with the following features:
+- Conversation compaction, added in Agno v3.1.2
+- agent.compact() to fold older turns into a summary on demand
+- The archived transcript and the search_compacted_history tool
+
+A long session eventually outgrows the context window. With compaction, older
+turns are replaced in the model's context by a short summary, while the
+original messages are archived in the database. Because the archive is
+searchable, the summary acts as an index rather than a lossy replacement: when
+a question needs a detail the summary dropped, the agent searches the archive.
+
+For more details, visit:
+https://github.com/agno-agi/agno/blob/v3.1.2/cookbook/02_agents/03_context_management/compaction/compaction_searchable_archive.py
+-------------------------------------------------------
+"""
+
+DB_FILE = "/tmp/agno_compaction_example.db"
+SESSION_ID = "inventory-session-001"
+OWNERS = ["ana", "rui", "ines", "joao", "marta"]
+
+if os.path.exists(DB_FILE):
+ os.remove(DB_FILE)
+
+
+# --- 1. Mock data with values a model cannot guess ---
+def port_for(index: int) -> int:
+ return 10_000 + index * 7919 % 50_000
+
+
+inventory = "\n".join(
+ f"service-{i:02d}: port {port_for(i)}, owner {OWNERS[i % 5]}" for i in range(1, 26)
+)
+
+# --- 2. Configure compaction ---
+compaction = Compaction(
+ # Fold only when agent.compact() is called, so every run folds at the same point.
+ compact_at_tokens=None,
+ uncompacted_runs=1,
+ # Too small to carry a 25-row inventory, so the rows can only come back from the archive.
+ compacted_token_budget=150,
+ search_compacted_messages=True,
+)
+
+agent = Agent(
+ model=OpenAIChat(id=settings.OPENAI_MODEL_NAME),
+ db=SqliteDb(db_file=DB_FILE),
+ session_id=SESSION_ID,
+ add_history_to_context=True,
+ compaction=compaction,
+ instructions="Keep replies to one short sentence.",
+)
+
+# --- 3. Build up history worth compacting ---
+print("=== Turn 1: share a 25-row service inventory ===")
+response = agent.run(f"Here is our service inventory for later. Just say noted.\n{inventory}")
+print(f"Agent: {response.content}\n")
+
+print("=== Turn 2: an unrelated question ===")
+response = agent.run("What is a service mesh?")
+print(f"Agent: {response.content}\n")
+
+# --- 4. Fold everything before the last turn into a summary ---
+print("=== Compacting the session ===")
+result = agent.compact(session_id=SESSION_ID)
+print(f"Status: {result.status.value}")
+if result.record is not None:
+ record = result.record
+ summary = " ".join(record.summary.split())
+ print(f"Messages folded: {record.messages_compacted}")
+ print(f"Context tokens: {record.tokens_before} -> {record.tokens_after}")
+ print(f"Summary: {summary[:160]}…")
+ print(f"Summary holds service-17's port: {str(port_for(17)) in record.summary}\n")
+
+# --- 5. Ask for a detail the summary could not keep ---
+print("=== Turn 3: recall a single row ===")
+response = agent.run("What port does service-17 use, and who owns it?")
+for tool in response.tools or []:
+ print(f"Tool call: {tool.tool_name}({tool.tool_args})")
+print(f"Agent: {response.content}")
+print(f"Expected: port {port_for(17)}, owner {OWNERS[17 % 5]}")
diff --git a/agno/23_hyde_query_transform.py b/agno/23_hyde_query_transform.py
new file mode 100644
index 0000000..acd8fc4
--- /dev/null
+++ b/agno/23_hyde_query_transform.py
@@ -0,0 +1,88 @@
+import shutil
+
+from dotenv import load_dotenv
+
+from agno.knowledge import Knowledge
+from agno.knowledge.embedder.openai import OpenAIEmbedder
+from agno.knowledge.query_transformer.hyde import HyDE
+from agno.models.openai import OpenAIChat
+from agno.vectordb.lancedb import LanceDb
+
+from settings import settings
+
+load_dotenv()
+
+"""
+-------------------------------------------------------
+In this example, we explore Agno with the following features:
+- Query transformation on Knowledge, added in Agno v3.1.2
+- HyDE (Hypothetical Document Embeddings) as the query transformer
+- Plain search vs HyDE search over the same LanceDb table
+
+A question and the passage that answers it rarely share wording, so the
+question's embedding can land closer to documents that merely repeat its
+words. HyDE asks an LLM to write a hypothetical answer first and searches with
+that instead. The invented answer is never shown to the user and does not need
+to be correct; it only has to look like the documents being searched for.
+
+For more details, visit:
+https://docs.agno.com/knowledge/concepts/search-and-retrieval/query-transformation
+-------------------------------------------------------
+"""
+
+LANCE_URI = "/tmp/agno_hyde_example"
+QUESTION = "Why did our sales numbers fall?"
+
+shutil.rmtree(LANCE_URI, ignore_errors=True)
+
+# --- 1. One vector table, shared by both knowledge bases ---
+vector_db = LanceDb(
+ uri=LANCE_URI,
+ table_name="company_wiki",
+ embedder=OpenAIEmbedder(
+ id="text-embedding-3-small",
+ api_key=settings.OPENAI_API_KEY.get_secret_value(),
+ ),
+)
+
+plain_knowledge = Knowledge(vector_db=vector_db)
+hyde_knowledge = Knowledge(
+ vector_db=vector_db,
+ query_transformer=HyDE(model=OpenAIChat(id=settings.OPENAI_MODEL_NAME)),
+)
+
+# --- 2. Add mock wiki pages ---
+# Only the first page answers the question, and it shares none of its words.
+documents = [
+ (
+ "Q3 business review",
+ "Three enterprise accounts postponed their contract renewals to next year, and two mid-market customers churned to a cheaper competitor after the price increase.",
+ ),
+ (
+ "Sales dashboard guide",
+ "The sales dashboard shows numbers for each region. If the numbers fall to zero, the nightly data sync failed; press Refresh to reload them.",
+ ),
+ (
+ "Sales team offsite",
+ "The sales team offsite is in Lisbon in October. Numbers are limited, so register early.",
+ ),
+ (
+ "Expense policy",
+ "Expenses above 500 EUR need manager approval before purchase.",
+ ),
+]
+for name, text in documents:
+ plain_knowledge.insert(name=name, text_content=text)
+
+
+# --- 3. Search the same question both ways ---
+def show_results(label: str, knowledge: Knowledge) -> None:
+ print(f"=== {label} ===")
+ for rank, document in enumerate(knowledge.search(QUESTION, max_results=2), start=1):
+ print(f" {rank}. {document.name}: {document.content[:60]}…")
+ print()
+
+
+print(f"Question: {QUESTION}\n")
+show_results("Plain search (embeds the question)", plain_knowledge)
+show_results("HyDE search (embeds a hypothetical answer)", hyde_knowledge)
diff --git a/agno/24_multi_turn_eval.py b/agno/24_multi_turn_eval.py
new file mode 100644
index 0000000..15f79de
--- /dev/null
+++ b/agno/24_multi_turn_eval.py
@@ -0,0 +1,157 @@
+from dotenv import load_dotenv
+
+from agno.agent import Agent
+from agno.db.in_memory import InMemoryDb
+from agno.eval import Case, run_cases
+from agno.models.message import Message
+from agno.models.openai import OpenAIChat
+from agno.run import RunContext
+from agno.scorer import CodeScorer, Score
+
+from settings import settings
+
+load_dotenv()
+
+"""
+-------------------------------------------------------
+In this example, we explore Agno with the following features:
+- Eval Case run arguments: session_id, user_id, session_state
+- Multi-turn evals: cases that share a session_id run as consecutive turns
+- A Message (not just a str) as the case input
+
+A Case without a session_id runs in a fresh, generated session, so it can only
+grade a single-shot answer. Two cases with the same session_id become turns of
+one conversation, so the second case grades whether the agent used what it
+learned in the first — here, booking a call for a caller whose name was only
+given one turn earlier.
+
+For more details, visit:
+https://docs.agno.com/evals/suite/overview
+-------------------------------------------------------
+"""
+
+SESSION_ID = "booking-session-001"
+USER_ID = "lead-42"
+CALENDAR = {"calendar_id": "cal-7", "timezone": "Europe/Lisbon"}
+
+
+# --- 1. Mock tools that read the run's session_state and user_id ---
+def get_open_slots(run_context: RunContext) -> str:
+ """Return the open appointment slots on the caller's calendar."""
+ session_state = run_context.session_state
+ if not session_state.get("calendar_id"):
+ return "No calendar is configured for this caller."
+ return f"Open slots ({session_state['timezone']}): Tuesday 10:00, Wednesday 15:00"
+
+
+def create_appointment(run_context: RunContext, slot: str, name: str) -> str:
+ """Book the given slot for the caller.
+
+ Args:
+ slot: The slot to book, as returned by get_open_slots.
+ name: The caller's name.
+ """
+ run_context.session_state["appointment"] = {"slot": slot, "name": name}
+ calendar_id = run_context.session_state.get("calendar_id")
+ return f"Booked {slot} for {name} (user {run_context.user_id}) on calendar {calendar_id}."
+
+
+# --- 2. Create the agent under test ---
+# db + add_history_to_context let a turn read the earlier turns of its session.
+agent = Agent(
+ id="booking-agent",
+ model=OpenAIChat(id=settings.OPENAI_MODEL_NAME),
+ db=InMemoryDb(),
+ add_history_to_context=True,
+ tools=[get_open_slots, create_appointment],
+ instructions=[
+ "You book sales calls. Use get_open_slots to offer times.",
+ "Once the caller has given their name and picked a slot, call create_appointment.",
+ "Reply in one short sentence.",
+ ],
+)
+
+
+# --- 3. Deterministic scorers ---
+def offers_both_slots(run, expected) -> bool:
+ return "Tuesday" in run.content and "Wednesday" in run.content
+
+
+def books_from_history(run, expected) -> Score:
+ """Pass when create_appointment ran with the name from turn 1 and the picked slot."""
+ calls = [tool.tool_args for tool in run.tools or [] if tool.tool_name == "create_appointment"]
+ if not calls:
+ return Score(value=0.0, passed=False, reason="create_appointment was not called")
+ args = calls[0]
+ passed = args.get("name") == expected["name"] and expected["day"] in args.get("slot", "")
+ reason = f"booked name={args.get('name')!r}, slot={args.get('slot')!r}; expected {expected['name']!r} on {expected['day']}"
+ return Score(value=1.0 if passed else 0.0, passed=passed, reason=reason)
+
+
+def offers_no_slots(run, expected) -> bool:
+ return "Tuesday" not in run.content and "Wednesday" not in run.content
+
+
+# --- 4. Declare the cases ---
+cases = [
+ # Turn 1: the caller's calendar arrives through session_state.
+ Case(
+ name="turn 1: offers open slots",
+ input="Hi, I'm Priya. I'd like to book a call. What times do you have?",
+ agent=agent,
+ expected_tool_calls=("get_open_slots",),
+ scorer=CodeScorer(offers_both_slots),
+ session_id=SESSION_ID,
+ user_id=USER_ID,
+ session_state=CALENDAR,
+ ),
+ # Turn 2: same session_id, so the agent sees turn 1. The name and the calendar
+ # are not repeated — they can only come from the history and the stored session.
+ Case(
+ name="turn 2: books the slot using turn-1 context",
+ input="Wednesday works for me, please book it.",
+ agent=agent,
+ scorer=CodeScorer(books_from_history),
+ expected={"name": "Priya", "day": "Wednesday"},
+ session_id=SESSION_ID,
+ user_id=USER_ID,
+ ),
+ # Control: no session_id means a fresh session with no history and no calendar.
+ # The input is a Message, which is how a case would attach images or files.
+ Case(
+ name="fresh session: no calendar, no slots",
+ input=Message(role="user", content="What times do you have for a call?"),
+ agent=agent,
+ scorer=CodeScorer(offers_no_slots),
+ ),
+]
+
+# --- 5. Run the suite ---
+print("=== Running multi-turn eval suite ===\n")
+suite_result = run_cases(cases)
+
+# --- 6. Report each case ---
+for result in suite_result.results:
+ verdict = "PASS" if result.passed else "FAIL"
+ print(f"[{verdict}] {result.name}")
+ origin = "shared" if result.session_id == SESSION_ID else "generated per case"
+ print(f" session: {result.session_id} ({origin})")
+ tools = result.response.tools if result.response else None
+ for tool in tools or []:
+ print(f" tool: {tool.tool_name}({tool.tool_args}) -> {tool.result}")
+ print(f" reply: {result.output}")
+ if result.score and result.score.reason:
+ print(f" score: {result.score.reason}")
+ if result.error:
+ print(f" error: {result.error}")
+ print()
+
+# --- 7. Inspect the shared session the two turns ran in ---
+session = agent.get_session(session_id=SESSION_ID)
+print(f"=== Stored session '{SESSION_ID}' ===")
+print(f"Runs in session: {len(session.runs or [])} (turn 1 + turn 2)")
+print(f"Session state: {agent.get_session_state(session_id=SESSION_ID)}")
+
+print(f"\nSuite: {suite_result.status} — {suite_result.passed}/{suite_result.total} cases passed")
+if suite_result.status != "PASS":
+ raise SystemExit(1)
diff --git a/agno/OUTPUTS.md b/agno/OUTPUTS.md
index cde42e0..e3b2699 100644
--- a/agno/OUTPUTS.md
+++ b/agno/OUTPUTS.md
@@ -1,6 +1,6 @@
# Agno Example Outputs
-Captured outputs from running all 22 examples against agno v3.0.9 with `gpt-4o-mini`.
+Captured outputs from running all 25 examples against agno v3.1.10 with `gpt-4o-mini`.
> These outputs may vary between runs due to LLM non-determinism. The structure and tool invocations should remain consistent.
@@ -830,3 +830,81 @@ Answer: The error reported in the payments service is:
> shows it reaching for both on its own; neither is declared by the example.
---
+
+## 22_conversation_compaction.py
+
+```
+=== Turn 1: share a 25-row service inventory ===
+Agent: Noted.
+
+=== Turn 2: an unrelated question ===
+Agent: A service mesh is an infrastructure layer that manages communication between microservices in a distributed application, providing features like traffic management, security, and observability.
+
+=== Compacting the session ===
+WARNING tokenizers not installed. Please install it using `pip install tokenizers`.: No module named 'tokenizers'
+WARNING tiktoken not installed. Please install it using `pip install tiktoken`.: No module named 'tiktoken'
+Status: compacted
+Messages folded: 2
+Context tokens: 285 -> 213
+Summary: ## Goal To maintain a record of services and their corresponding ports and owners for future reference. Not covered here: specifics regarding the nature or func…
+Summary holds service-17's port: False
+
+=== Turn 3: recall a single row ===
+Tool call: search_compacted_history({'pattern': 'service-17', 'context_lines': 10})
+Agent: Service-17 uses port 44623 and is owned by ines.
+Expected: port 44623, owner ines
+```
+
+> `agent.compact()` folds turn 1 — the 25-row inventory — into a summary cut to the 150-token budget, and the summary does not carry service-17's port. The correct answer can only have come from the archived transcript, which is what the `search_compacted_history` call shows. The two warnings are expected: without the optional `agno[tokenizers]` extra, agno counts tokens with a character-based estimate, which is where the before/after figures come from.
+
+---
+
+## 23_hyde_query_transform.py
+
+```
+Question: Why did our sales numbers fall?
+
+=== Plain search (embeds the question) ===
+ 1. Sales dashboard guide: The sales dashboard shows numbers for each region. If the nu…
+ 2. Q3 business review: Three enterprise accounts postponed their contract renewals …
+
+=== HyDE search (embeds a hypothetical answer) ===
+ 1. Q3 business review: Three enterprise accounts postponed their contract renewals …
+ 2. Sales dashboard guide: The sales dashboard shows numbers for each region. If the nu…
+```
+
+> Both searches run against the same LanceDb table. The plain search ranks the dashboard guide first because it repeats the question's words ("sales", "numbers", "fall"); the Q3 review answers the question but shares none of them. HyDE embeds an LLM-written hypothetical answer instead, which lands next to the real answer and puts the Q3 review on top.
+
+---
+
+## 24_multi_turn_eval.py
+
+```
+=== Running multi-turn eval suite ===
+
+[PASS] turn 1: offers open slots
+ session: booking-session-001 (shared)
+ tool: get_open_slots({}) -> Open slots (Europe/Lisbon): Tuesday 10:00, Wednesday 15:00
+ reply: I have available slots on Tuesday at 10:00 and Wednesday at 15:00; which one works for you?
+
+[PASS] turn 2: books the slot using turn-1 context
+ session: booking-session-001 (shared)
+ tool: create_appointment({'slot': 'Wednesday 15:00', 'name': 'Priya'}) -> Booked Wednesday 15:00 for Priya (user lead-42) on calendar cal-7.
+ reply: Your appointment has been booked for Wednesday at 15:00, Priya.
+ score: booked name='Priya', slot='Wednesday 15:00'; expected 'Priya' on Wednesday
+
+[PASS] fresh session: no calendar, no slots
+ session: eval-fresh session: no calendar, no slots-bc4efca6 (generated per case)
+ tool: get_open_slots({}) -> No calendar is configured for this caller.
+ reply: It seems there is no calendar configured; please provide your name so we can assist you further.
+
+=== Stored session 'booking-session-001' ===
+Runs in session: 2 (turn 1 + turn 2)
+Session state: {'calendar_id': 'cal-7', 'timezone': 'Europe/Lisbon', 'appointment': {'slot': 'Wednesday 15:00', 'name': 'Priya'}}
+
+Suite: PASS — 3/3 cases passed
+```
+
+> The first two cases share `session_id`, so the suite runs them as consecutive turns of one conversation. Turn 2 only says "Wednesday works for me" — the name `Priya` in the `create_appointment` call and `calendar cal-7` in its result can only come from turn 1's history and the session_state turn 1 passed. The third case has no `session_id`, gets a generated session with no history or calendar, and correctly offers no slots. The stored session holds both turns and the booked appointment.
+
+---
diff --git a/agno/README.md b/agno/README.md
index 4573000..a8609de 100644
--- a/agno/README.md
+++ b/agno/README.md
@@ -2,7 +2,7 @@
- Repo: https://github.com/agno-agi/agno
- Documentation: https://docs.agno.com
-- Version: **3.0.9**
+- Version: **3.1.10**
## Agno Examples
@@ -65,6 +65,9 @@ cp .env.example .env
| 19 | `19_eval_suite.py` | Evals | `Case` + `run_cases()` graded by `CodeScorer` and `ToolCallScorer` |
| 20 | `20_runs_table.py` | Runs Table | `agno_runs` rows, `db.get_runs()`/`get_run()`, `MigrationManager` |
| 21 | `21_tool_result_offloading.py` | Tool Result Offloading | `offload_tool_results=ResultStore(...)`, `read_result`/`search_result` |
+| 22 | `22_conversation_compaction.py` | Compaction | `Compaction(...)`, `agent.compact()` and the `search_compacted_history` archive search |
+| 23 | `23_hyde_query_transform.py` | Query Transformation | Plain vs `HyDE` search with `Knowledge(query_transformer=...)` |
+| 24 | `24_multi_turn_eval.py` | Multi-Turn Evals | `Case` run arguments (`session_id`, `user_id`, `session_state`) and cases sharing a session as turns |
### Running examples
@@ -77,6 +80,9 @@ python 18_filesystem.py
python 19_eval_suite.py
python 20_runs_table.py
python 21_tool_result_offloading.py
+python 22_conversation_compaction.py
+python 23_hyde_query_transform.py
+python 24_multi_turn_eval.py
```
> **Note:** Example `14_mcp_tools.py` requires Node.js (npx) for the MCP filesystem server, and
diff --git a/agno/pyproject.toml b/agno/pyproject.toml
index e41446f..93f4991 100644
--- a/agno/pyproject.toml
+++ b/agno/pyproject.toml
@@ -4,7 +4,7 @@ version = "0.1.0"
description = "Agno framework examples"
requires-python = ">=3.12"
dependencies = [
- "agno>=2.8.2",
+ "agno>=3.1.10",
"ddgs",
"fastapi",
"fastmcp>=4.0.0,<5",
diff --git a/agno/uv.lock b/agno/uv.lock
index 123dcf5..014f232 100644
--- a/agno/uv.lock
+++ b/agno/uv.lock
@@ -8,7 +8,7 @@ resolution-markers = [
[[package]]
name = "agno"
-version = "3.0.9"
+version = "3.1.10"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "agnoctl" },
@@ -22,9 +22,9 @@ dependencies = [
{ name = "rich" },
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/ba/88/64f8ca8e5e590d4c637732e76faf8aa9521363951f3503995b5f220a8095/agno-3.0.9.tar.gz", hash = "sha256:046540cee29aa1e24fb00a87bc8a7e749291c22c1c02a16a8e3e7c7df24162d0", size = 3475772, upload-time = "2026-09-08T22:54:49.771Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ad/f7/002d37fab96dff126b56879578e745d6ceb2a99834342415c4ec5d9c1016/agno-3.1.10.tar.gz", hash = "sha256:1830567bd35ea0a178a5c213d6a93dde84d21caae147e4dd285351c3686a41c8", size = 4108774, upload-time = "2026-10-23T13:11:25.529Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/6e/86/75a7b4f0598d372c3823672aa1f80f88eb260fce8ca44e9f0981e0a75914/agno-3.0.9-py3-none-any.whl", hash = "sha256:21b5b8694089140db8bd8c5105b4b19546f99d6a9f61216220523066ddeb1a73", size = 3955783, upload-time = "2026-09-08T22:54:46.553Z" },
+ { url = "https://files.pythonhosted.org/packages/1c/38/0ca8cd1d0f29ee850566ebb15f4d4fdb4a2c78fc958903bcec398eaf9ba7/agno-3.1.10-py3-none-any.whl", hash = "sha256:ea1d0d2f8f7e8d0c413c2a1df57b4c784dac2f70ceac1f69b935fd8d2ef68c7e", size = 4657166, upload-time = "2026-10-23T13:11:21.745Z" },
]
[[package]]
@@ -49,7 +49,7 @@ dependencies = [
[package.metadata]
requires-dist = [
- { name = "agno", specifier = ">=2.8.2" },
+ { name = "agno", specifier = ">=3.1.10" },
{ name = "ddgs" },
{ name = "fastapi" },
{ name = "fastmcp", specifier = ">=4.0.0,<5" },
|