Skip to content

docs: document callable agent factories #619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Coda-slack-bot wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document callable agent factories #619

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 5 additions & 18 deletions _snippets/concept-callable-factories-caching.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
18 changes: 12 additions & 6 deletions agents/building-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

<Snippet file="concept-callable-factories-caching.mdx" />

Expand Down
7 changes: 5 additions & 2 deletions reference/agents/agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand Down
Loading