diff --git a/_snippets/concept-callable-factories-caching.mdx b/_snippets/concept-callable-factories-caching.mdx index 126122e4d..ebe9185d3 100644 --- a/_snippets/concept-callable-factories-caching.mdx +++ b/_snippets/concept-callable-factories-caching.mdx @@ -1,22 +1,9 @@ -Factory results are cached by default. The cache key is resolved in this order: custom key function > `user_id` > `session_id`. If none are available, caching is skipped and the factory runs every time. +Factory results are cached by default. The cache key is resolved in this order: custom key function, `user_id`, then `session_id`. If none are available, caching is skipped and the factory runs on every call. | Setting | Default | Description | |---------|---------|-------------| -| `cache_callables` | `True` | Enable or disable caching for all callable factories | -| `callable_tools_cache_key` | `None` | Custom cache key function for tools factory | -| `callable_knowledge_cache_key` | `None` | Custom cache key function for knowledge factory | -| `callable_members_cache_key` | `None` | Custom cache key function for members factory (Team only) | +| `cache_callables` | `True` | Enable or disable caching for callable `tools` and `knowledge` factories | +| `callable_tools_cache_key` | `None` | Custom cache key function for the `tools` factory | +| `callable_knowledge_cache_key` | `None` | Custom cache key function for the `knowledge` factory | -Set `cache_callables=False` when `session_state` changes between runs and the factory should re-evaluate each time. - -Clear cached results programmatically: - -```python -from agno.utils.callables import clear_callable_cache - -clear_callable_cache(team) # Clear all caches -clear_callable_cache(team, kind="tools") # Clear tools cache only -clear_callable_cache(team, kind="tools", close=True) # Clear and call .close() on cached resources -``` - -Use `aclear_callable_cache()` in async code. +Set `cache_callables=False` when the factory depends on changing `session_state` and should re-evaluate on every run. diff --git a/agents/building-agents.mdx b/agents/building-agents.mdx index 6fc96a3ec..172b12bb8 100644 --- a/agents/building-agents.mdx +++ b/agents/building-agents.mdx @@ -49,10 +49,11 @@ for chunk in stream: ## Callable Factories -Pass a function instead of a static list for `tools` or `knowledge`. The function is called at the start of each run, so the toolset or knowledge base can vary per user or session. +Pass a function for `tools` or `knowledge` when they should be resolved at run start. -```python callable_tools.py +```python callable_factories.py from agno.agent import Agent +from agno.knowledge.text import TextKnowledgeBase from agno.models.openai import OpenAIResponses from agno.run import RunContext from agno.tools.duckduckgo import DuckDuckGoTools @@ -66,16 +67,21 @@ def get_tools(run_context: RunContext): return [DuckDuckGoTools()] +def get_knowledge(run_context: RunContext): + tenant = (run_context.session_state or {}).get("tenant", "default") + return TextKnowledgeBase(path=f"./data/{tenant}.txt") + + agent = Agent( model=OpenAIResponses(id="gpt-5-mini"), tools=get_tools, + knowledge=get_knowledge, ) - -agent.print_response("AAPL stock price?", session_state={"role": "finance"}, stream=True) -agent.print_response("Latest AI news?", session_state={"role": "general"}, stream=True) ``` -### Callable Caching Settings +Factories can declare `run_context`, `session_state`, or `agent`. Agno injects matching arguments by name. + +### Callable caching diff --git a/reference/agents/agent.mdx b/reference/agents/agent.mdx index a9c99ecf2..d52fbf650 100644 --- a/reference/agents/agent.mdx +++ b/reference/agents/agent.mdx @@ -35,14 +35,14 @@ mode: wide | `add_history_to_context` | `bool` | `False` | Add the chat history of the current session to the messages sent to the Model | | `num_history_runs` | `Optional[int]` | `None` | Number of historical runs to include in the messages. | | `num_history_messages` | `Optional[int]` | `None` | Number of historical messages to include messages list sent to the Model. | -| `knowledge` | `Optional[Knowledge]` | `None` | Agent Knowledge | +| `knowledge` | `Optional[Union[Knowledge, Callable[..., Knowledge]]]` | `None` | Agent knowledge instance or a callable factory resolved at run start | | `knowledge_filters` | `Optional[Dict[str, Any]]` | `None` | Knowledge filters to apply to the knowledge base | | `enable_agentic_knowledge_filters` | `Optional[bool]` | `None` | Let the agent choose the knowledge filters | | `add_knowledge_to_context` | `bool` | `False` | Enable RAG by adding references from Knowledge to the user prompt | | `knowledge_retriever` | `Optional[Callable[..., Optional[List[Union[Dict, str]]]]]` | `None` | Function to get references to add to the user_message | | `references_format` | `Literal["json", "yaml"]` | `"json"` | Format of the references | | `metadata` | `Optional[Dict[str, Any]]` | `None` | Metadata stored with this agent | -| `tools` | `Optional[List[Union[Toolkit, Callable, Function, Dict]]]` | `None` | A list of tools provided to the Model | +| `tools` | `Optional[Union[List[Union[Toolkit, Callable, Function, Dict]], Callable[..., List]]]` | `None` | Tool list or a callable factory resolved at run start | | `tool_call_limit` | `Optional[int]` | `None` | Maximum number of tool calls allowed for a single run | | `tool_choice` | `Optional[Union[str, Dict[str, Any]]]` | `None` | Controls which (if any) tool is called by the model | | `max_tool_calls_from_history` | `Optional[int]` | `None` | Maximum number of tool calls from history to keep in context. If None, all tool calls from history are included. If set to N, only the last N tool calls from history are added to the context for memory management | @@ -101,6 +101,9 @@ mode: wide | `debug_mode` | `bool` | `False` | Enable debug logs | | `debug_level` | `Literal[1, 2]` | `1` | Debug level for logging | | `telemetry` | `bool` | `True` | Log minimal telemetry for analytics | +| `cache_callables` | `bool` | `True` | Cache callable `tools` and `knowledge` factory results across runs | +| `callable_tools_cache_key` | `Optional[Callable[..., Optional[str]]]` | `None` | Custom cache key function for callable `tools` factories | +| `callable_knowledge_cache_key` | `Optional[Callable[..., Optional[str]]]` | `None` | Custom cache key function for callable `knowledge` factories | ## Functions