Heuristic:Microsoft Agent framework Declaration Only Tools Pattern
| Knowledge Sources | |
|---|---|
| Domains | AI_Agents, UI_Integration |
| Last Updated | 2026-02-11 16:45 GMT |
Overview
Set `func=None` when creating tools that should only be declared to the LLM but executed on the client side, enabling UI rendering tools and client-side actions.
Description
The AG-UI protocol supports a split execution model: some tools run on the server (normal tools with a `func` implementation) while others run on the client (UI tools). Declaration-only tools are created by setting `func=None`, which causes the `declaration_only` property to return `True`. The framework skips server-side execution for these tools and sends the tool call back to the client for handling. This pattern is critical for AG-UI frontends that render UI components, create files, or perform other client-side actions.
Usage
Apply this pattern when building AG-UI agents that need to expose tools to the frontend. Client-side tools (UI rendering, file operations, navigation) should use `func=None`. Server-side tools (API calls, database queries) should have normal function implementations. Never mix the two in a single tool list sent to the server.
The Insight (Rule of Thumb)
- Action: Set `func=None` on tools intended for client-side execution.
- Value: Enables split execution model where LLM can invoke both server and client tools.
- Trade-off: Requires careful separation of server and client tool lists. Sending a `func=None` tool to the server will result in a no-op.
Reasoning
From `python/packages/ag-ui/agent_framework_ag_ui/_utils.py`:
# CRITICAL: These tools MUST have func=None so that declaration_only returns True.
# When func=None, the declaration_only property returns True,
# which tells the framework to skip server-side execution
func=None, # CRITICAL: Makes declaration_only=True
From `python/packages/ag-ui/getting_started/server.py:112`:
# IMPORTANT: Do NOT include tools that the client provides!
The AG-UI getting started guide emphasizes this separation:
# IMPORTANT: When using AGUIChatClient directly (without Agent wrapper):
# - Tools are sent as DEFINITIONS only
# - No automatic client-side execution (no function invocation middleware)