This is an automated email from the ASF dual-hosted git repository.
xtsong pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new f231b62 [docs] Update react agent development doc. (#236)
f231b62 is described below
commit f231b62ad915ff8c0ec4a9cdd3b323c2a6fa5428
Author: Wenjin Xie <[email protected]>
AuthorDate: Tue Sep 30 18:45:11 2025 +0800
[docs] Update react agent development doc. (#236)
---
docs/content/docs/development/react_agent.md | 92 ++++++++++++++++++++--
.../agents/custom_types_and_resources.py | 6 +-
2 files changed, 89 insertions(+), 9 deletions(-)
diff --git a/docs/content/docs/development/react_agent.md
b/docs/content/docs/development/react_agent.md
index 980aa8c..7a2773a 100644
--- a/docs/content/docs/development/react_agent.md
+++ b/docs/content/docs/development/react_agent.md
@@ -24,12 +24,92 @@ under the License.
## Overview
-{{< hint warning >}}
-**TODO**: What is ReAct agent. When to use it.
-{{< /hint >}}
+ReAct Agent is a general paradigm that combines reasoning and action
capabilities to solve complex tasks. Leveraging this paradigm, the user only
needs to specify the goal with prompt and provide available tools, and the LLM
will decide how to achieve the goal and take actions autonomously
## ReAct Agent Example
-{{< hint warning >}}
-**TODO**: Add the quickstart example code here. And briefly explain the code
component by component. Link to the detailed documentation for each component,
such as ChatModel, Prompt, Tool, etc.
-{{< /hint >}}
+```python
+my_react_agent = ReActAgent(
+ chat_model=chat_model_descriptor,
+ prompt=my_prompt,
+ output_schema=MyBaseModelDataType, # or output_schema=my_row_type_info
+)
+```
+## Initialize Arguments
+### Chat Model
+User should specify the chat model used in the ReAct Agent.
+
+We use `ResourceDescriptor` to describe the chat model, includes chat model
type and chat model arguments. See [Chat Model]({{< ref
"docs/development/chat_with_llm#chatmodel" >}}) for more details.
+```python
+chat_model_descriptor = ResourceDescriptor(
+ clazz=OllamaChatModelSetup,
+ connection="my_ollama_connection",
+ model="qwen3:8b",
+ tools=["my_tool1, my_tool2"],
+)
+```
+
+### Prompt
+User can provide prompt to instruct agent.
+
+The prompt should contain two messages. The first message tells the agent what
to do, and gives the input and output example. The second message tells how to
convert input element to text string.
+```python
+system_prompt_str = """
+ Analyze
+ ...
+
+ Example input format:
+ ...
+
+ Ensure your response can be parsed by Python JSON, using this format as an
example:
+ ...
+ """
+
+# Prompt for review analysis react agent.
+my_prompt = Prompt.from_messages(
+ messages=[
+ ChatMessage(
+ role=MessageRole.SYSTEM,
+ content=system_prompt_str,
+ ),
+ # For react agent, if the input element is not primitive types,
+ # framework will deserialize input element to dict and fill the prompt.
+ # Note, the input element should be primitive types, BaseModel or Row.
+ ChatMessage(
+ role=MessageRole.USER,
+ content="""
+ "id": {id},
+ "review": {review}
+ """,
+ ),
+ ],
+)
+
+```
+If the input element is primitive types, like `int`, `str` and so on, the
second message should be
+```python
+ChatMessage(
+ role=MessageRole.USER,
+ content="{input}"
+)
+```
+
+See [Prompt]({{< ref "docs/development/chat_with_llm#prompt" >}}) for more
details.
+
+### Output Schema
+User can set output schema to configure the ReAct Agent output type. If output
schema is set, the ReAct Agent will deserialize the llm response to expected
type.
+
+The output schema should be `BaseModel` or `RowTypeInfo`.
+```python
+class MyBaseModelDataType(BaseModel):
+ id: str
+ score: int
+ reasons: list[str]
+
+# Currently, for RowTypeInfo, only support BasicType fields.
+my_row_type_info = RowTypeInfo(
+ [BasicTypeInfo.STRING_TYPE_INFO(), BasicTypeInfo.INT_TYPE_INFO()],
+ ["id", "score"],
+ )
+```
+
diff --git
a/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py
b/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py
index 98f1c9f..fc23f7b 100644
---
a/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py
+++
b/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py
@@ -77,9 +77,9 @@ review_analysis_react_prompt = Prompt.from_messages(
role=MessageRole.SYSTEM,
content=review_analysis_system_prompt_str,
),
- # For react agent, framework will deserialize input element
- # to dict and fill the prompt.
- # Note, the input element should be BaseModel or Row.
+ # For react agent, if the input element is not primitive types,
+ # framework will deserialize input element to dict and fill the prompt.
+ # Note, the input element should be primitive types, BaseModel or Row.
ChatMessage(
role=MessageRole.USER,
content="""
