xintongsong commented on code in PR #248:
URL: https://github.com/apache/flink-agents/pull/248#discussion_r2409591571
##########
docs/content/docs/development/tool_use.md:
##########
@@ -22,33 +22,157 @@ specific language governing permissions and limitations
under the License.
-->
+## Overview
+
+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.
## Local Function as Tool
-{{< hint warning >}}
-**TODO**: How to define and use a Local Function as Tool.
+Developer can define the tool as a local Python function, and use it in either
workflow agent or react agent.
+- 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.
+- 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.
+
+{{< hint info >}}
+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.
{{< /hint >}}
-## How to Integrate with MCP Server
+Below is an example of how to define the tool as a local Python function in
workflow agent:
-{{< hint warning >}}
-**TODO**: How to integrate with MCP Server.
-{{< /hint >}}
+```python
+class ReviewAnalysisAgent(Agent):
-### MCP Tools
+ @tool
+ @staticmethod
+ def notify_shipping_manager(id: str, review: str) -> None:
+ """Notify the shipping manager when product received a negative review
due to
+ shipping damage.
-{{< hint warning >}}
-**TODO**: How to use the tools provided by MCP Server.
-{{< /hint >}}
+ Parameters
+ ----------
+ id : str
+ The id of the product that received a negative review due to
shipping damage
+ review: str
+ The negative review content
+ """
+ notify_shipping_manager(id=id, review=review)
+
+ ...
+```
-### MCP Prompt
+Below is an example of how to define the tool as a local Python function in
react agent:
-{{< hint warning >}}
-**TODO**: How to use the prompts provided by MCP Server.
-{{< /hint >}}
+```python
+def notify_shipping_manager(id: str, review: str) -> None:
+ """Notify the shipping manager when product received a negative review due
to
+ shipping damage.
+
+ Parameters
+ ----------
+ id : str
+ The id of the product that received a negative review due to shipping
damage
+ review: str
+ The negative review content
+ """
+ ...
+
+...
+
+# Add notify shipping manager tool to the execution environment.
+agents_env.add_resource(
+ "notify_shipping_manager", Tool.from_callable(notify_shipping_manager)
+)
+
+...
+
+# Create react agent with notify shipping manager tool.
+review_analysis_react_agent = ReActAgent(
+ chat_model=ResourceDescriptor(
+ clazz=OllamaChatModelSetup,
+ tools=["notify_shipping_manager"],
+ ),
+ ...
+)
+```
+
+## Integrate with MCP Server
+
+Flink Agents supports integrating with a remote MCP server to use the
resources provided by the MCP server, including tools and prompts.
+
+To use MCP server in workflow agent, developer can use `@mcp_server`
annotation to declare the server.
+
+```python
+@mcp_server
+@staticmethod
+def my_mcp_server() -> MCPServer:
+ """Define MCP server connection."""
+ return MCPServer(endpoint=MCP_SERVER_ENDPOINT)
+```
+
+To use MCP server in react agent, developer can register the MCP server to the
execution environment.
+
+```python
+# Register MCP server to the execution environment.
+agents_env.add_resource("my_mcp_server",
MCPServer(endpoint=MCP_SERVER_ENDPOINT))
+```
+
+### Use MCP Tool and MCP Prompt
Review Comment:
I think we can only describe mcp tool here, and leave mcp prompt alone.
There should be not much duplication, just defining the mcp server.
You may take a look at mcp prompt documentation:
https://nightlies.apache.org/flink/flink-agents-docs-main/docs/development/prompts/#mcp-prompt-1
##########
docs/content/docs/development/tool_use.md:
##########
@@ -22,33 +22,157 @@ specific language governing permissions and limitations
under the License.
-->
+## Overview
+
+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.
## Local Function as Tool
-{{< hint warning >}}
-**TODO**: How to define and use a Local Function as Tool.
+Developer can define the tool as a local Python function, and use it in either
workflow agent or react agent.
+- 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.
+- 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.
+
+{{< hint info >}}
+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.
{{< /hint >}}
-## How to Integrate with MCP Server
+Below is an example of how to define the tool as a local Python function in
workflow agent:
-{{< hint warning >}}
-**TODO**: How to integrate with MCP Server.
-{{< /hint >}}
+```python
+class ReviewAnalysisAgent(Agent):
-### MCP Tools
+ @tool
+ @staticmethod
+ def notify_shipping_manager(id: str, review: str) -> None:
+ """Notify the shipping manager when product received a negative review
due to
+ shipping damage.
-{{< hint warning >}}
-**TODO**: How to use the tools provided by MCP Server.
-{{< /hint >}}
+ Parameters
+ ----------
+ id : str
+ The id of the product that received a negative review due to
shipping damage
+ review: str
+ The negative review content
+ """
+ notify_shipping_manager(id=id, review=review)
+
+ ...
+```
-### MCP Prompt
+Below is an example of how to define the tool as a local Python function in
react agent:
-{{< hint warning >}}
-**TODO**: How to use the prompts provided by MCP Server.
-{{< /hint >}}
+```python
+def notify_shipping_manager(id: str, review: str) -> None:
+ """Notify the shipping manager when product received a negative review due
to
+ shipping damage.
+
+ Parameters
+ ----------
+ id : str
+ The id of the product that received a negative review due to shipping
damage
+ review: str
+ The negative review content
+ """
+ ...
+
+...
+
+# Add notify shipping manager tool to the execution environment.
+agents_env.add_resource(
+ "notify_shipping_manager", Tool.from_callable(notify_shipping_manager)
+)
+
+...
+
+# Create react agent with notify shipping manager tool.
+review_analysis_react_agent = ReActAgent(
+ chat_model=ResourceDescriptor(
+ clazz=OllamaChatModelSetup,
+ tools=["notify_shipping_manager"],
+ ),
+ ...
+)
+```
+
+## Integrate with MCP Server
+
+Flink Agents supports integrating with a remote MCP server to use the
resources provided by the MCP server, including tools and prompts.
+
+To use MCP server in workflow agent, developer can use `@mcp_server`
annotation to declare the server.
+
+```python
+@mcp_server
+@staticmethod
+def my_mcp_server() -> MCPServer:
+ """Define MCP server connection."""
+ return MCPServer(endpoint=MCP_SERVER_ENDPOINT)
+```
+
+To use MCP server in react agent, developer can register the MCP server to the
execution environment.
+
+```python
+# Register MCP server to the execution environment.
+agents_env.add_resource("my_mcp_server",
MCPServer(endpoint=MCP_SERVER_ENDPOINT))
+```
+
+### Use MCP Tool and MCP Prompt
+
+The MCP tool and prompt can be used the in same way with local function tool
and local prompt.
+
+If developer define a MCP server providing tool `add` and prompt `ask_sum`,
they can use them when talking with chat model.
+
+```python
+@chat_model_setup
+@staticmethod
+def math_chat_model() -> ResourceDescriptor:
+ """ChatModel using MCP prompt and tool."""
+ return ResourceDescriptor(
+ clazz=OllamaChatModelSetup,
+ connection="ollama_connection",
+ model=OLLAMA_MODEL,
+ prompt="ask_sum", # MCP prompt registered from my_mcp_server
+ tools=["add"], # MCP tool registered from my_mcp_server
+ extract_reasoning=True,
+ )
+```
## Built-in Events for Tool
-{{< hint warning >}}
-**TODO**: How to use the built-in events for tool call request and tool call
response, such as ToolRequestEvent and ToolResponseEvent.
-{{< /hint >}}
\ No newline at end of file
+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.
Review Comment:
I think we should explain why users should use the built-in events, rather
than just call the tools directly. Or omit this if we don't recommend users to
use it.
##########
docs/content/docs/development/tool_use.md:
##########
@@ -22,33 +22,157 @@ specific language governing permissions and limitations
under the License.
-->
+## Overview
+
+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.
## Local Function as Tool
-{{< hint warning >}}
-**TODO**: How to define and use a Local Function as Tool.
+Developer can define the tool as a local Python function, and use it in either
workflow agent or react agent.
+- 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.
+- 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.
Review Comment:
This is inaccurate. You can also register the tool to the execution
environment when building a workflow agent. The difference is that, decorator
is for methods inside the agent class, and registration is for methods not from
the agent class. And for react, users don't have the chance to define a inner
method.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
