Skip to content

Commit d6a38c4

Browse files
SxnanSxnan
authored
[docs] Update the tool use docs (#248)
1 parent b23644d commit d6a38c4

File tree

1 file changed

+146
-17
lines changed

1 file changed

+146
-17
lines changed

‎docs/content/docs/development/tool_use.md‎

Lines changed: 146 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,33 +22,162 @@ specific language governing permissions and limitations
2222
under the License.
2323
-->
2424

25+
## Overview
26+
27+
Flink Agents provides a flexible and extensible tool use mechanism. Developers can define the tool as a local Python function, or they can integrate with a remote MCP server to use the tools provided by the MCP server.
2528

2629
## Local Function as Tool
2730

28-
{{< hint warning >}}
29-
**TODO**: How to define and use a Local Function as Tool.
31+
Developer can define the tool as a local Python function, and there are two ways to define and register an local function as a tool:
32+
33+
{{< hint info >}}
34+
Flink Agents uses the docstring of the tool function to generate the tool metadata. The docstring of the python function should accurately describe the tool's purpose, parameters, and return value, so that the LLM can understand the tool and use it effectively.
3035
{{< /hint >}}
3136

32-
## How to Integrate with MCP Server
37+
### Define Tool as Static Method in Agent Class
3338

34-
{{< hint warning >}}
35-
**TODO**: How to integrate with MCP Server.
36-
{{< /hint >}}
39+
Developer can define the tool as a static method in the agent class while defining the workflow agent, and use the `@tool` annotation to mark the method as a tool. The tool can be referenced by its name in the `tools` list of the `ResourceDescriptor` when creating the chat model in the agent.
3740

38-
### MCP Tools
41+
```python
42+
class ReviewAnalysisAgent(Agent):
3943

40-
{{< hint warning >}}
41-
**TODO**: How to use the tools provided by MCP Server.
42-
{{< /hint >}}
44+
@tool
45+
@staticmethod
46+
def notify_shipping_manager(id: str, review: str) -> None:
47+
"""Notify the shipping manager when product received a negative review due to
48+
shipping damage.
49+
50+
Parameters
51+
----------
52+
id : str
53+
The id of the product that received a negative review due to shipping damage
54+
review: str
55+
The negative review content
56+
"""
57+
notify_shipping_manager(id=id, review=review)
58+
59+
@chat_model_setup
60+
@staticmethod
61+
def review_analysis_model() -> ResourceDescriptor:
62+
"""ChatModel which focus on review analysis."""
63+
return ResourceDescriptor(
64+
clazz=OllamaChatModelSetup,
65+
...,
66+
tools=["notify_shipping_manager"], # reference the tool by its name
67+
)
68+
69+
...
70+
```
71+
72+
**Key points:**
73+
- Use `@tool` decorator to define the tool
74+
- Reference the tool by its name in the `tools` list of the `ResourceDescriptor`
75+
76+
77+
### Register Tool to Execution Environment
78+
79+
Developer can register the tool to the execution environment, and then reference the tool by its name. This allows the tool to be reused by multiple agents.
80+
81+
```python
82+
def notify_shipping_manager(id: str, review: str) -> None:
83+
"""Notify the shipping manager when product received a negative review due to
84+
shipping damage.
85+
86+
Parameters
87+
----------
88+
id : str
89+
The id of the product that received a negative review due to shipping damage
90+
review: str
91+
The negative review content
92+
"""
93+
...
94+
95+
...
96+
97+
# Add notify shipping manager tool to the execution environment.
98+
agents_env.add_resource(
99+
"notify_shipping_manager", Tool.from_callable(notify_shipping_manager)
100+
)
101+
102+
...
43103

44-
### MCP Prompt
104+
# Create react agent with notify shipping manager tool.
105+
review_analysis_react_agent = ReActAgent(
106+
chat_model=ResourceDescriptor(
107+
clazz=OllamaChatModelSetup,
108+
tools=["notify_shipping_manager"], # reference the tool by its name
109+
),
110+
...
111+
)
112+
```
45113

46-
{{< hint warning >}}
47-
**TODO**: How to use the prompts provided by MCP Server.
114+
**Key points:**
115+
- Use `AgentsExecutionEnvironment.add_resource` to register the tool to the execution environment
116+
- Reference the tool by its name in the `tools` list of the `ResourceDescriptor`
117+
118+
## MCP Tool
119+
120+
{{< hint info >}}
121+
MCP (Model Context Protocol) is a standardized protocol for integrating AI applications with external data sources and tools. MCP tools allow dynamic tool retrieval from MCP servers.
48122
{{< /hint >}}
49123

50-
## Built-in Events for Tool
124+
MCP tools are managed by external MCP servers and automatically discovered when you define an MCP server connection in your agent.
125+
126+
### Define MCP Server with Tools
127+
128+
Create an MCP server that exposes tools using the `FastMCP` library:
129+
130+
```python
131+
# mcp_server.py
132+
mcp = FastMCP("ReviewServer")
133+
134+
@mcp.tool()
135+
async def notify_shipping_manager(id: str, review: str) -> None:
136+
"""Notify the shipping manager when product received a negative review due to
137+
shipping damage.
138+
139+
Parameters
140+
----------
141+
id : str
142+
The id of the product that received a negative review due to shipping damage
143+
review: str
144+
The negative review content
145+
"""
146+
...
147+
148+
mcp.run("streamable-http")
149+
```
150+
151+
**Key points:**
152+
- Use `@mcp.tool()` decorator to define tools
153+
- The function name becomes the tool identifier
154+
155+
### Use MCP Tools in Agent
156+
157+
Connect to the MCP server and use its tools in your agent:
158+
159+
```python
160+
class ReviewAnalysisAgent(Agent):
161+
...
162+
163+
@mcp_server
164+
@staticmethod
165+
def review_mcp_server() -> MCPServer:
166+
"""Connect to MCP server."""
167+
return MCPServer(endpoint="http://127.0.0.1:8000/mcp")
168+
169+
@chat_model_setup
170+
@staticmethod
171+
def review_model() -> ResourceDescriptor:
172+
return ResourceDescriptor(
173+
clazz=OllamaChatModelSetup,
174+
connection="ollama_server",
175+
model="qwen3:8b",
176+
tools=["notify_shipping_manager"], # Reference MCP tool by name
177+
)
178+
```
51179

52-
{{< hint warning >}}
53-
**TODO**: How to use the built-in events for tool call request and tool call response, such as ToolRequestEvent and ToolResponseEvent.
54-
{{< /hint >}}
180+
**Key points:**
181+
- Use `@mcp_server` decorator to define MCP server connection
182+
- Reference MCP tools by their function name (e.g., `"notify_shipping_manager"`)
183+
- All tools from the MCP server are automatically registered

0 commit comments

Comments
 (0)