Merge branch 'main' into context-token-docs

Signed-off-by: Matous Havlena <havlenma@gmail.com>

Author: matoushavlena

README.md

@@ -85,7 +85,7 @@ agentstack run example_agent "Alice"  # Test your agent
 You should see: "Ciao Alice!" 🎉
 
 > [!TIP]
-> Check out [Start Building Agents](https://agentstack.beeai.dev/introduction/start-building-agents) for a complete step-by-step guide to creating your first agent.
+> Check out [Building Agents](https://agentstack.beeai.dev/guides/building-agents) for a complete step-by-step guide to creating your first agent.
 
 ---
 
@@ -95,14 +95,15 @@ You should see: "Ciao Alice!" 🎉
 
 Reference implementations demonstrating core Agent Stack capabilities.
 
-- [BeeAI Showcase Agent](https://github.com/jenna-winkler/beeai-showcase-agent) - Full-featured chat assistant demonstrating RequirementAgent with conditional tool use, web search (DuckDuckGo), advanced reasoning (ThinkTool), file handling (PDF/CSV/JSON), streaming, UI feature toggles, trajectory logging, and citation extraction.
+- [Agent Stack Showcase](https://github.com/jenna-winkler/agentstack-showcase) - Full-featured chat assistant demonstrating RequirementAgent with conditional tool use, web search (DuckDuckGo), advanced reasoning (ThinkTool), file handling (PDF/CSV/JSON), streaming, UI feature toggles, trajectory logging, and citation extraction.
 - [Serper Search Agent](https://github.com/jenna-winkler/serper-search-agent) - Web search agent showing runtime secrets management (Secrets Extension), custom tool creation (SerperSearchTool), automatic query term extraction, and structured results with citations.
-- [GitHub Issue Writer](https://github.com/jenna-winkler/github_issue_writer) - Single-turn workflow using the Form Extension for multi-field input, AI-enhanced issue drafting with ThinkTool, and professional Markdown formatting.
+- [GitHub Issue Writer](https://github.com/jenna-winkler/github_issue_writer) - Single-turn workflow using the Form Extension for multi-field input, AI-enhanced issue drafting with ThinkTool, and Markdown formatting.
 - [Chat Agent](https://github.com/i-am-bee/agentstack/tree/main/agents/chat) - Multi-turn conversational agent using RequirementAgent, ActTool for reasoning sequences, and ClarificationTool for ambiguous queries. Integrates DuckDuckGo, Wikipedia, OpenMeteo, and file tools with UnconstrainedMemory, streaming, citation extraction, and OpenTelemetry instrumentation.
 - [Form Agent](https://github.com/i-am-bee/agentstack/tree/main/agents/form) - Single-turn form interaction using Form Extension with multiple field types, customizable layouts, file uploads, validation, and structured output.
 - [RAG Agent](https://github.com/i-am-bee/agentstack/tree/main/agents/rag) - Retrieval-Augmented Generation agent supporting 12+ file formats, dynamic vector stores, semantic search (VectorSearchTool), document summaries (FileReaderTool), intelligent tool selection, and citation tracking with document URLs.
 - [OAuth Agent](https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/examples/oauth.py) - OAuth Extension demo with MCP integration, browser-based authorization, secure token management, and Stripe MCP server access.
 - [Dynamic Form Request Agent](https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/examples/request_form_agent.py) - Multi-step form workflow showing both static and dynamic form generation, where the agent conditionally requests additional input mid-conversation.
+- [Flight Search 	and Visualization Agent](https://github.com/jezekra1/agentstack-workshop) - Agent that queries the Kiwi.com MCP API for flight results, requests missing parameters through the Form Extension, and optionally generates PNG or HTML route visualizations using geospatial helpers. It uses RequirementAgent to orchestrate tool calls (data validation and visualization) and streams a final answer with any generated files and citations.
 
 ### Community Agents
 

agents/chat/pyproject.toml

@@ -7,7 +7,7 @@ authors = [
 ]
 requires-python = ">=3.13,<3.14"
 dependencies = [
-    "beeai-framework[duckduckgo,wikipedia]>=0.1.60",
+    "beeai-framework[duckduckgo,wikipedia]>=0.1.67",
     "tiktoken>=0.12.0",  # constraint for beeai-framework dependency (first version with musl arm64 wheel)
     "fastuuid>=0.14.0",  # constraint for beeai-framework dependency (first version with musl arm64 wheel)
     "openai>=1.107.1",

agents/chat/src/chat/tools/general/act.py

@@ -3,13 +3,13 @@
 
 from typing import Literal
 
-from beeai_framework.agents.experimental import (
+from beeai_framework.agents.requirement import (
     RequirementAgent,
     RequirementAgentRunState,
 )
-from beeai_framework.agents.experimental.events import RequirementAgentStartEvent
-from beeai_framework.agents.experimental.requirements import Requirement, Rule
-from beeai_framework.agents.experimental.requirements.requirement import (
+from beeai_framework.agents.requirement.events import RequirementAgentStartEvent
+from beeai_framework.agents.requirement.requirements import Requirement, Rule
+from beeai_framework.agents.requirement.requirements.requirement import (
     run_with_context,
 )
 from beeai_framework.context import RunContext
@@ -29,11 +29,15 @@ class ActToolInput(BaseModel):
         ...,
         description="Provide a clear explanation of why you want to use the selected tool and what you expect to achieve.",
     )
-    selected_tool: str = Field(..., description="The name of the tool you want to execute next.")
+    selected_tool: str = Field(
+        ..., description="The name of the tool you want to execute next."
+    )
 
 
 class ActToolResult(BaseModel):
-    selected_tool: str = Field(..., description="The name of the tool that has been selected for execution.")
+    selected_tool: str = Field(
+        ..., description="The name of the tool that has been selected for execution."
+    )
 
 
 class ActToolOutput(JSONToolOutput[ActToolResult]):
@@ -98,7 +102,9 @@ def allowed_tools_names(self, allowed_tools_names: list[str]) -> None:
     def input_schema(self):
         return self._input_schema
 
-    async def _run(self, input: ActToolInput, options: ToolRunOptions | None, context: RunContext) -> ActToolOutput:
+    async def _run(
+        self, input: ActToolInput, options: ToolRunOptions | None, context: RunContext
+    ) -> ActToolOutput:
         if not input.selected_tool:
             raise ToolInputValidationError(
                 f"You must always select one of the provided tools: {self._allowed_tools_names}."
@@ -147,21 +153,53 @@ async def run(self, state: RequirementAgentRunState, ctx: RunContext) -> list[Ru
         if last_step and last_step.tool and last_step.tool.name == "act":
             assert isinstance(last_step.tool, ActTool)
             if last_step.error is not None:
-                return [Rule(target="act", forced=True, allowed=True, prevent_stop=False, hidden=False)]
-
-            if last_step.output is None or not isinstance(last_step.output, ActToolOutput):
-                raise ValueError("Last step output must be an instance of ActToolOutput.")
+                return [
+                    Rule(
+                        target="act",
+                        forced=True,
+                        allowed=True,
+                        prevent_stop=False,
+                        hidden=False,
+                    )
+                ]
+
+            if last_step.output is None or not isinstance(
+                last_step.output, ActToolOutput
+            ):
+                raise ValueError(
+                    "Last step output must be an instance of ActToolOutput."
+                )
             selected_tool = last_step.output.result.selected_tool
-            return [Rule(target=selected_tool, forced=True, allowed=True, prevent_stop=False, hidden=False)]
+            return [
+                Rule(
+                    target=selected_tool,
+                    forced=True,
+                    allowed=True,
+                    prevent_stop=False,
+                    hidden=False,
+                )
+            ]
 
         # Hide all tools except ActTool on the first step
         rules = [
-            Rule(target=t.name, hidden=True, allowed=False, prevent_stop=False, forced=False)
+            Rule(
+                target=t.name,
+                hidden=True,
+                allowed=False,
+                prevent_stop=False,
+                forced=False,
+            )
             for t in self.tools
             if not isinstance(t, ActTool)
         ]
         return [
-            Rule(target="act", forced=True, allowed=True, prevent_stop=False, hidden=False),
+            Rule(
+                target="act",
+                forced=True,
+                allowed=True,
+                prevent_stop=False,
+                hidden=False,
+            ),
             *rules,
         ]
 

agents/chat/src/chat/tools/general/clarification.py

@@ -1,11 +1,11 @@
 # Copyright 2025 © BeeAI a Series of LF Projects, LLC
 # SPDX-License-Identifier: Apache-2.0
 
-from beeai_framework.agents.experimental import (
+from beeai_framework.agents.requirement import (
     RequirementAgent,
     RequirementAgentRunState,
 )
-from beeai_framework.agents.experimental.events import RequirementAgentStartEvent
+from beeai_framework.agents.requirement.events import RequirementAgentStartEvent
 from beeai_framework.backend import AssistantMessage
 from beeai_framework.context import RunContext
 from beeai_framework.emitter import Emitter, EventMeta
@@ -20,10 +20,13 @@
 
 class ClarificationSchema(BaseModel):
     thoughts: str = Field(
-        ..., description="Your reasoning process and analysis of what information is needed from the user."
+        ...,
+        description="Your reasoning process and analysis of what information is needed from the user.",
     )
     question_to_user: str = Field(
-        ..., description="The specific question or clarification request to ask the user.", min_length=1
+        ...,
+        description="The specific question or clarification request to ask the user.",
+        min_length=1,
     )
 
 
@@ -63,7 +66,9 @@ async def _run(
         context: RunContext,
     ) -> StringToolOutput:
         if not self._state:
-            raise ToolInputValidationError("State is not set for the ClarificationTool.")
+            raise ToolInputValidationError(
+                "State is not set for the ClarificationTool."
+            )
 
         # Store the clarification request in the agent state
         self._state.result = input
@@ -85,7 +90,9 @@ def clarification_tool_middleware(ctx: RunContext) -> None:
     """
     assert isinstance(ctx.instance, RequirementAgent)
 
-    clarification_tool = next((t for t in ctx.instance._tools if isinstance(t, ClarificationTool)), None)
+    clarification_tool = next(
+        (t for t in ctx.instance._tools if isinstance(t, ClarificationTool)), None
+    )
     if clarification_tool is None:
         raise ValueError("ClarificationTool is not found in the agent's tools.")