Skip to content

Commit 378c127

Browse files
SxnanSxnan
committed
address comments
1 parent 03dac4f commit 378c127

File tree

1 file changed

+75
-70
lines changed

1 file changed

+75
-70
lines changed

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

Lines changed: 75 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ Flink Agents provides a flexible and extensible tool use mechanism. Developers c
2828

2929
## Local Function as Tool
3030

31-
Developer can define the tool as a local Python function, and use it in either workflow agent or react agent.
32-
- For workflow agent, developer defines the tool as a static method in the agent class, and use the `@tool` annotation to mark the method as a tool.
33-
- For react agent, you have to register the tool to the execution environment, and then pass the tool name to the chat model descriptor when creating the ReAct agent.
31+
Developer can define the tool as a local Python function, and there are two way to define and register an local function as a tool:
3432

3533
{{< hint info >}}
3634
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.
3735
{{< /hint >}}
3836

39-
Below is an example of how to define the tool as a local Python function in workflow agent:
37+
### Define Tool as Static Method in Agent Class
38+
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.
4040

4141
```python
4242
class ReviewAnalysisAgent(Agent):
@@ -55,11 +55,28 @@ class ReviewAnalysisAgent(Agent):
5555
The negative review content
5656
"""
5757
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+
)
5868

5969
...
6070
```
6171

62-
Below is an example of how to define the tool as a local Python function in react agent:
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.
6380

6481
```python
6582
def notify_shipping_manager(id: str, review: str) -> None:
@@ -88,91 +105,79 @@ agents_env.add_resource(
88105
review_analysis_react_agent = ReActAgent(
89106
chat_model=ResourceDescriptor(
90107
clazz=OllamaChatModelSetup,
91-
tools=["notify_shipping_manager"],
108+
tools=["notify_shipping_manager"], # reference the tool by its name
92109
),
93110
...
94111
)
95112
```
96113

97-
## Integrate with 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`
98117

99-
Flink Agents supports integrating with a remote MCP server to use the resources provided by the MCP server, including tools and prompts.
118+
## MCP Tool
100119

101-
To use MCP server in workflow agent, developer can use `@mcp_server` annotation to declare the server.
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.
122+
{{< /hint >}}
102123

103-
```python
104-
@mcp_server
105-
@staticmethod
106-
def my_mcp_server() -> MCPServer:
107-
"""Define MCP server connection."""
108-
return MCPServer(endpoint=MCP_SERVER_ENDPOINT)
109-
```
124+
MCP tools are managed by external MCP servers and automatically discovered when you define an MCP server connection in your agent.
110125

111-
To use MCP server in react agent, developer can register the MCP server to the execution environment.
126+
### Define MCP Server with Tools
112127

113-
```python
114-
# Register MCP server to the execution environment.
115-
agents_env.add_resource("my_mcp_server", MCPServer(endpoint=MCP_SERVER_ENDPOINT))
116-
```
128+
Create an MCP server that exposes tools using the `FastMCP` library:
117129

118-
### Use MCP Tool and MCP Prompt
130+
```python
131+
# mcp_server.py
132+
mcp = FastMCP("ReviewServer")
119133

120-
The MCP tool and prompt can be used the in same way with local function tool and local prompt.
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.
121138
122-
If developer define a MCP server providing tool `add` and prompt `ask_sum`, they can use them when talking with chat model.
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+
...
123147

124-
```python
125-
@chat_model_setup
126-
@staticmethod
127-
def math_chat_model() -> ResourceDescriptor:
128-
"""ChatModel using MCP prompt and tool."""
129-
return ResourceDescriptor(
130-
clazz=OllamaChatModelSetup,
131-
connection="ollama_connection",
132-
model=OLLAMA_MODEL,
133-
prompt="ask_sum", # MCP prompt registered from my_mcp_server
134-
tools=["add"], # MCP tool registered from my_mcp_server
135-
extract_reasoning=True,
136-
)
148+
mcp.run("streamable-http")
137149
```
138150

139-
## Built-in Events for Tool
151+
**Key points:**
152+
- Use `@mcp.tool()` decorator to define tools
153+
- The function name becomes the tool identifier
140154

141-
Flink Agents provides built-in events for tool call request and tool call response, specifically `ToolRequestEvent` and `ToolResponseEvent`. By default, Flink Agents built-in action will listen to these events and handle the tool call request and tool call response automatically. If you have special needs, you can also define your own action to listen to these events and handle the `ToolRequestEvent` and `ToolResponseEvent` accordingly.
155+
### Use MCP Tools in Agent
142156

143-
Here is the definition of the `ToolRequestEvent` and `ToolResponseEvent`:
157+
Connect to the MCP server and use its tools in your agent:
144158

145159
```python
146-
class ToolRequestEvent(Event):
147-
"""Event representing a tool call request.
148-
149-
Attributes:
150-
----------
151-
model: str
152-
name of the model that generated the tool request.
153-
tool_calls : List[Dict[str, Any]]
154-
tool calls that should be executed in batch.
155-
"""
156-
157-
model: str
158-
tool_calls: List[Dict[str, Any]]
159-
160-
161-
class ToolResponseEvent(Event):
162-
"""Event representing a result from tool call.
160+
class ReviewAnalysisAgent(Agent):
161+
...
163162

164-
Attributes:
165-
----------
166-
request_id : UUID
167-
The id of the request event.
168-
responses : Dict[UUID, Any]
169-
The dict maps tool call id to result.
170-
external_ids : Dict[UUID, str]
171-
Optional identifier for storing original tool call IDs from external systems
172-
(e.g., Anthropic tool_use_id).
173-
"""
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")
174168

175-
request_id: UUID
176-
responses: Dict[UUID, Any]
177-
external_ids: Dict[UUID, str | None]
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+
)
178178
```
179+
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)