# -*- coding: utf-8 -*-
-"""A dict dialog agent that using `parse_func` and `fault_handler` to
-parse the model response."""
-import json
-from typing import Any , Optional , Callable
-from loguru import logger
+"""An agent that replies in a dictionary format."""
+from typing import Optional
from ..message import Msg
from .agent import AgentBase
-from ..models import ModelResponse
-from ..prompt import PromptType
-from ..utils.tools import _convert_to_str
-
-
-
-
[docs]
-
def parse_dict ( response : ModelResponse ) -> ModelResponse :
-
"""Parse function for DictDialogAgent"""
-
try :
-
if response . text is not None :
-
response_dict = json . loads ( response . text )
-
else :
-
raise ValueError (
-
f "The text field of the response s None: { response } " ,
-
)
-
except json . decoder . JSONDecodeError :
-
# Sometimes LLM may return a response with single quotes, which is not
-
# a valid JSON format. We replace single quotes with double quotes and
-
# try to load it again.
-
# TODO: maybe using a more robust json library to handle this case
-
response_dict = json . loads ( response . text . replace ( "'" , '"' ))
-
-
return ModelResponse ( raw = response_dict )
-
[docs]
-
def default_response ( response : ModelResponse ) -> ModelResponse :
-
"""The default response of fault_handler"""
-
return ModelResponse ( raw = { "speak" : response . text }) from ..parsers import ParserBase
[docs]
class DictDialogAgent ( AgentBase ):
"""An agent that generates response in a dict format, where user can
-
specify the required fields in the response via prompt, e.g.
-
-
.. code-block:: python
+
specify the required fields in the response via specifying the parser
-
prompt = "... Response in the following format that can be loaded by
-
python json.loads()
-
{
-
"thought": "thought",
-
"speak": "thoughts summary to say to others",
-
# ...
-
}"
-
-
This agent class is an example for using `parse_func` and `fault_handler`
-
to parse the output from the model, and handling the fault when parsing
-
fails. We take "speak" as a required field in the response, and print
-
the speak field as the output response.
+
About parser, please refer to our
+
[tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html)
For usage example, please refer to the example of werewolf in
`examples/game_werewolf`"""
@@ -174,10 +127,7 @@
Source code for agentscope.agents.dict_dialog_agent model_config_name
: str ,
use_memory : bool = True ,
memory_config : Optional [ dict ] = None ,
-
parse_func : Optional [ Callable [ ... , Any ]] = parse_dict ,
-
fault_handler : Optional [ Callable [ ... , Any ]] = default_response ,
max_retries : Optional [ int ] = 3 ,
-
prompt_type : Optional [ PromptType ] = None ,
) -> None :
"""Initialize the dict dialog agent.
@@ -194,19 +144,9 @@
Source code for agentscope.agents.dict_dialog_agent Whether the agent has memory.
memory_config (`Optional[dict]`, defaults to `None`):
The config of memory.
-
parse_func (`Optional[Callable[..., Any]]`, defaults to `parse_dict`):
-
The function used to parse the model output,
-
e.g. `json.loads`, which is used to extract json from the
-
output.
-
fault_handler (`Optional[Callable[..., Any]]`, defaults to `default_response`):
-
The function used to handle the fault when parse_func fails
-
to parse the model output.
max_retries (`Optional[int]`, defaults to `None`):
The maximum number of retries when failed to parse the model
output.
-
prompt_type (`Optional[PromptType]`, defaults to `PromptType.LIST`):
-
The type of the prompt organization, chosen from
-
`PromptType.LIST` or `PromptType.STRING`.
""" # noqa
super () . __init__ (
name = name ,
@@ -216,19 +156,21 @@
Source code for agentscope.agents.dict_dialog_agent memory_config= memory_config ,
)
- # record the func and handler for parsing and handling faults
- self . parse_func = parse_func
- self . fault_handler = fault_handler
- self . max_retries = max_retries
+ self . parser = None
+ self . max_retries = max_retries
-
if prompt_type is not None :
-
logger . warning (
-
"The argument `prompt_type` is deprecated and "
-
"will be removed in the future." ,
-
)
+
+
+
[docs]
+
def set_parser ( self , parser : ParserBase ) -> None :
+
"""Set response parser, which will provide 1) format instruction; 2)
+
response parsing; 3) filtering fields when returning message, storing
+
message in memory. So developers only need to change the
+
parser, and the agent will work as expected.
+
"""
+
self . parser = parser
-
# TODO change typing from dict to MSG
[docs]
def reply ( self , x : dict = None ) -> dict :
@@ -263,43 +205,30 @@
Source code for agentscope.agents.dict_dialog_agent self. memory
and self . memory . get_memory ()
or x , # type: ignore[arg-type]
+ Msg ( "system" , self . parser . format_instruction , "system" ),
)
# call llm
- response = self . model (
+ res = self . model (
prompt ,
- parse_func = self . parse_func ,
- fault_handler = self . fault_handler ,
+ parse_func = self . parser . parse ,
max_retries = self . max_retries ,
- ) . raw
-
- # logging raw messages in debug mode
- logger . debug ( json . dumps ( response , indent = 4 , ensure_ascii = False ))
-
- # In this agent, if the response is a dict, we treat "speak" as a
- # special key, which represents the text to be spoken
- if isinstance ( response , dict ) and "speak" in response :
- msg = Msg (
- self . name ,
- response [ "speak" ],
- role = "assistant" ,
- ** response ,
- )
- else :
- msg = Msg ( self . name , response , role = "assistant" )
-
- # Print/speak the message in this agent's voice
- self . speak ( msg )
+ )
- # record to memory
- if self . memory :
- # Convert the response dict into a string to store in memory
- msg_memory = Msg (
- name = self . name ,
- content = _convert_to_str ( response ),
- role = "assistant" ,
- )
- self . memory . add ( msg_memory )
+ # Filter the parsed response by keys for storing in memory, returning
+ # in the reply function, and feeding into the metadata field in the
+ # returned message object.
+ self . memory . add (
+ Msg ( self . name , self . parser . to_memory ( res . parsed ), "assistant" ),
+ )
+
+ msg = Msg (
+ self . name ,
+ content = self . parser . to_content ( res . parsed ),
+ role = "assistant" ,
+ metadata = self . parser . to_metadata ( res . parsed ),
+ )
+ self . speak ( msg )
return msg
diff --git a/en/_modules/agentscope/agents/react_agent.html b/en/_modules/agentscope/agents/react_agent.html
index edaba7490..f2f725d5a 100644
--- a/en/_modules/agentscope/agents/react_agent.html
+++ b/en/_modules/agentscope/agents/react_agent.html
@@ -239,6 +239,8 @@
Source code for agentscope.agents.react_agent "function": service_toolkit . tools_calling_format ,
},
required_keys = [ "thought" , "speak" , "function" ],
+ # Only print the speak field when verbose is False
+ keys_to_content = True if self . verbose else "speak" ,
)
@@ -261,9 +263,8 @@
Source code for agentscope.agents.react_agent "system",
self . parser . format_instruction ,
role = "system" ,
+ echo = self . verbose ,
)
- if self . verbose :
- self . speak ( hint_msg )
# Prepare prompt for the model
prompt = self . model . format ( self . memory . get_memory (), hint_msg )
@@ -277,16 +278,21 @@ Source code for agentscope.agents.react_agent )
# Record the response in memory
- msg_response = Msg ( self . name , res . text , "assistant" )
- self . memory . add ( msg_response )
+ self . memory . add (
+ Msg (
+ self . name ,
+ self . parser . to_memory ( res . parsed ),
+ "assistant" ,
+ ),
+ )
# Print out the response
- if self . verbose :
- self . speak ( msg_response )
- else :
- self . speak (
- Msg ( self . name , res . parsed [ "speak" ], "assistant" ),
- )
+ msg_returned = Msg (
+ self . name ,
+ self . parser . to_content ( res . parsed ),
+ "assistant" ,
+ )
+ self . speak ( msg_returned )
# Skip the next steps if no need to call tools
# The parsed field is a dictionary
@@ -298,7 +304,7 @@ Source code for agentscope.agents.react_agent and len ( arg_function ) == 0
):
# Only the speak field is exposed to users or other agents
- return Msg ( self . name , res . parsed [ "speak" ], "assistant" )
+ return msg_returned
# Only catch the response parsing error and expose runtime
# errors to developers for debugging
@@ -350,9 +356,8 @@ Source code for agentscope.agents.react_agent "iterations. Now generate a reply by summarizing the current "
"situation." ,
role = "system" ,
+ echo = self . verbose ,
)
- if self . verbose :
- self . speak ( hint_msg )
# Generate a reply by summarizing the current situation
prompt = self . model . format ( self . memory . get_memory (), hint_msg )
diff --git a/en/_modules/agentscope/message.html b/en/_modules/agentscope/message.html
index 6c45e8fbf..a253e1508 100644
--- a/en/_modules/agentscope/message.html
+++ b/en/_modules/agentscope/message.html
@@ -204,6 +204,28 @@ Source code for agentscope.message
class Msg ( MessageBase ):
"""The Message class."""
+ id : str
+ """The id of the message."""
+
+ name : str
+ """The name of who send the message."""
+
+ content : Any
+ """The content of the message."""
+
+ role : Literal [ "system" , "user" , "assistant" ]
+ """The role of the message sender."""
+
+ metadata : Optional [ dict ]
+ """Save the information for application's control flow, or other
+ purposes."""
+
+ url : Optional [ Union [ Sequence [ str ], str ]]
+ """A url to file, image, video, audio or website."""
+
+ timestamp : str
+ """The timestamp of the message."""
+
[docs]
def __init__ (
@@ -214,6 +236,7 @@
Source code for agentscope.message
url : Optional [ Union [ Sequence [ str ], str ]] = None ,
timestamp : Optional [ str ] = None ,
echo : bool = False ,
+ metadata : Optional [ Union [ dict , str ]] = None ,
** kwargs : Any ,
) -> None :
"""Initialize the message object
@@ -232,6 +255,11 @@ Source code for agentscope.message
timestamp (`Optional[str]`, defaults to `None`):
The timestamp of the message, if None, it will be set to
current time.
+ echo (`bool`, defaults to `False`):
+ Whether to print the message to the console.
+ metadata (`Optional[Union[dict, str]]`, defaults to `None`):
+ Save the information for application's control flow, or other
+ purposes.
**kwargs (`Any`):
Other attributes of the message.
"""
@@ -249,6 +277,7 @@ Source code for agentscope.message
role = role or "assistant" ,
url = url ,
timestamp = timestamp ,
+ metadata = metadata ,
** kwargs ,
)
if echo :
diff --git a/en/_modules/agentscope/parsers/code_block_parser.html b/en/_modules/agentscope/parsers/code_block_parser.html
index 0b9a7b61e..4c3c90c6d 100644
--- a/en/_modules/agentscope/parsers/code_block_parser.html
+++ b/en/_modules/agentscope/parsers/code_block_parser.html
@@ -99,6 +99,8 @@
Source code for agentscope.parsers.code_block_parser
# -*- coding: utf-8 -*-
"""Model response parser class for Markdown code block."""
+from typing import Optional
+
from agentscope.models import ModelResponse
from agentscope.parsers import ParserBase
@@ -123,17 +125,40 @@ Source code for agentscope.parsers.code_block_parser format_instruction
: str = (
"You should generate {language_name} code in a {language_name} fenced "
"code block as follows: \n ``` {language_name} \n "
-
"${{your_ {language_name} _code}} \n ```"
+
" {content_hint} \n ```"
)
"""The instruction for the format of the code block."""
[docs]
-
def __init__ ( self , language_name : str ) -> None :
+
def __init__ (
+
self ,
+
language_name : str ,
+
content_hint : Optional [ str ] = None ,
+
) -> None :
+
"""Initialize the parser with the language name and the optional
+
content hint.
+
+
Args:
+
language_name (`str`):
+
The name of the language, which will be used
+
in ```{language_name}
+
content_hint (`Optional[str]`, defaults to `None`):
+
The hint used to remind LLM what should be fill between the
+
tags. If not provided, the default content hint
+
"${{your_{language_name}_code}}" will be used.
+
"""
self . name = self . name . format ( language_name = language_name )
self . tag_begin = self . tag_begin . format ( language_name = language_name )
+
+
if content_hint is None :
+
self . content_hint = f "$ {{ your_ { language_name } _code }} "
+
else :
+
self . content_hint = content_hint
+
self . format_instruction = self . format_instruction . format (
language_name = language_name ,
+
content_hint = self . content_hint ,
) . strip ()
diff --git a/en/_modules/agentscope/parsers/json_object_parser.html b/en/_modules/agentscope/parsers/json_object_parser.html
index 14758356a..d15cab1dd 100644
--- a/en/_modules/agentscope/parsers/json_object_parser.html
+++ b/en/_modules/agentscope/parsers/json_object_parser.html
@@ -101,7 +101,7 @@
Source code for agentscope.parsers.json_object_parser """The parser for JSON object in the model response."""
import json
from copy import deepcopy
-
from typing import Optional , Any , List
+
from typing import Optional , Any , List , Sequence , Union
from loguru import logger
@@ -113,6 +113,7 @@
Source code for agentscope.parsers.json_object_parser )
from agentscope.models import ModelResponse
from agentscope.parsers import ParserBase
+
from agentscope.parsers.parser_base import DictFilterMixin
from agentscope.utils.tools import _join_str_with_comma_and
@@ -231,7 +232,7 @@
Source code for agentscope.parsers.json_object_parser
[docs]
-
class MarkdownJsonDictParser ( MarkdownJsonObjectParser ):
+
class MarkdownJsonDictParser ( MarkdownJsonObjectParser , DictFilterMixin ):
"""A class used to parse a JSON dictionary object in a markdown fenced
code"""
@@ -264,6 +265,9 @@
Source code for agentscope.parsers.json_object_parser self
,
content_hint : Optional [ Any ] = None ,
required_keys : List [ str ] = None ,
+
keys_to_memory : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_content : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_metadata : Optional [ Union [ str , bool , Sequence [ str ]]] = False ,
) -> None :
"""Initialize the parser with the content hint.
@@ -277,8 +281,42 @@
Source code for agentscope.parsers.json_object_parser A list of required keys in the JSON dictionary object. If the
response misses any of the required keys, it will raise a
RequiredFieldNotFoundError.
+ keys_to_memory (`Optional[Union[str, bool, Sequence[str]]]`,
+ defaults to `True`):
+ The key or keys to be filtered in `to_memory` method. If
+ it's
+ - `False`, `None` will be returned in the `to_memory` method
+ - `str`, the corresponding value will be returned
+ - `List[str]`, a filtered dictionary will be returned
+ - `True`, the whole dictionary will be returned
+ keys_to_content (`Optional[Union[str, bool, Sequence[str]]`,
+ defaults to `True`):
+ The key or keys to be filtered in `to_content` method. If
+ it's
+ - `False`, `None` will be returned in the `to_content` method
+ - `str`, the corresponding value will be returned
+ - `List[str]`, a filtered dictionary will be returned
+ - `True`, the whole dictionary will be returned
+ keys_to_metadata (`Optional[Union[str, bool, Sequence[str]]`,
+ defaults to `False`):
+ The key or keys to be filtered in `to_metadata` method. If
+ it's
+ - `False`, `None` will be returned in the `to_metadata` method
+ - `str`, the corresponding value will be returned
+ - `List[str]`, a filtered dictionary will be returned
+ - `True`, the whole dictionary will be returned
+
"""
- super () . __init__ ( content_hint )
+ # Initialize the markdown json object parser
+ MarkdownJsonObjectParser . __init__ ( self , content_hint )
+
+ # Initialize the mixin class to allow filtering the parsed response
+ DictFilterMixin . __init__ (
+ self ,
+ keys_to_memory = keys_to_memory ,
+ keys_to_content = keys_to_content ,
+ keys_to_metadata = keys_to_metadata ,
+ )
self . required_keys = required_keys or []
diff --git a/en/_modules/agentscope/parsers/parser_base.html b/en/_modules/agentscope/parsers/parser_base.html
index 04adf10a5..8a5d5cd9e 100644
--- a/en/_modules/agentscope/parsers/parser_base.html
+++ b/en/_modules/agentscope/parsers/parser_base.html
@@ -100,10 +100,17 @@
Source code for agentscope.parsers.parser_base # -*- coding: utf-8 -*-
"""The base class for model response parser."""
from abc import ABC , abstractmethod
+from typing import Union , Sequence
+
+from loguru import logger
from agentscope.exception import TagNotFoundError
from agentscope.models import ModelResponse
+# TODO: Support one-time warning in logger rather than setting global variable
+_FIRST_TIME_TO_REPORT_CONTENT = True
+_FIRST_TIME_TO_REPORT_MEMORY = True
+
[docs]
@@ -158,7 +165,7 @@
Source code for agentscope.parsers.parser_base raise TagNotFoundError (
f "Missing "
f "tag { '' if len ( missing_tags ) == 1 else 's' } "
- f " { ' and ' . join ( missing_tags ) } in response." ,
+ f " { ' and ' . join ( missing_tags ) } in response: { text } " ,
raw_response = text ,
missing_begin_tag = index_start == - 1 ,
missing_end_tag = index_end == - 1 ,
@@ -170,6 +177,155 @@
Source code for agentscope.parsers.parser_base
+
+
+
+
[docs]
+
class DictFilterMixin :
+
"""A mixin class to filter the parsed response by keys. It allows users
+
to set keys to be filtered during speaking, storing in memory, and
+
returning in the agent reply function.
+
"""
+
+
+
[docs]
+
def __init__ (
+
self ,
+
keys_to_memory : Union [ str , bool , Sequence [ str ]],
+
keys_to_content : Union [ str , bool , Sequence [ str ]],
+
keys_to_metadata : Union [ str , bool , Sequence [ str ]],
+
) -> None :
+
"""Initialize the mixin class with the keys to be filtered during
+
speaking, storing in memory, and returning in the agent reply function.
+
+
Args:
+
keys_to_memory (`Optional[Union[str, bool, Sequence[str]]]`):
+
The key or keys to be filtered in `to_memory` method. If
+
it's
+
- `False`, `None` will be returned in the `to_memory` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_content (`Optional[Union[str, bool, Sequence[str]]`):
+
The key or keys to be filtered in `to_content` method. If
+
it's
+
- `False`, `None` will be returned in the `to_content` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_metadata (`Optional[Union[str, bool, Sequence[str]]]`):
+
The key or keys to be filtered in `to_metadata` method. If
+
it's
+
- `False`, `None` will be returned in the `to_metadata` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
"""
+
self . keys_to_memory = keys_to_memory
+
self . keys_to_content = keys_to_content
+
self . keys_to_metadata = keys_to_metadata
+
+
+
+
[docs]
+
def to_memory (
+
self ,
+
parsed_response : dict ,
+
allow_missing : bool = False ,
+
) -> Union [ str , dict , None ]:
+
"""Filter the fields that will be stored in memory."""
+
return self . _filter_content_by_names (
+
parsed_response ,
+
self . keys_to_memory ,
+
allow_missing = allow_missing ,
+
)
+
+
+
+
[docs]
+
def to_content (
+
self ,
+
parsed_response : dict ,
+
allow_missing : bool = False ,
+
) -> Union [ str , dict , None ]:
+
"""Filter the fields that will be fed into the content field in the
+
returned message, which will be exposed to other agents.
+
"""
+
return self . _filter_content_by_names (
+
parsed_response ,
+
self . keys_to_content ,
+
allow_missing = allow_missing ,
+
)
+
+
+
+
+
+
def _filter_content_by_names (
+
self ,
+
parsed_response : dict ,
+
keys : Union [ str , bool , Sequence [ str ]],
+
allow_missing : bool = False ,
+
) -> Union [ str , dict , None ]:
+
"""Filter the parsed response by keys. If only one key is provided, the
+
returned content will be a single corresponding value. Otherwise,
+
the returned content will be a dictionary with the filtered keys and
+
their corresponding values.
+
+
Args:
+
keys (`Union[str, bool, Sequence[str]]`):
+
The key or keys to be filtered. If it's
+
- `False`, `None` will be returned in the `to_content` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
allow_missing (`bool`, defaults to `False`):
+
Whether to allow missing keys in the response. If set to
+
`True`, the method will skip the missing keys in the response.
+
Otherwise, it will raise a `ValueError` when a key is missing.
+
+
Returns:
+
`Union[str, dict]`: The filtered content.
+
"""
+
+
if isinstance ( keys , bool ):
+
if keys :
+
return parsed_response
+
else :
+
return None
+
+
if isinstance ( keys , str ):
+
return parsed_response [ keys ]
+
+
# check if the required names are in the response
+
for name in keys :
+
if name not in parsed_response :
+
if allow_missing :
+
logger . warning (
+
f "Content name { name } not found in the response. Skip "
+
f "it." ,
+
)
+
else :
+
raise ValueError ( f "Name { name } not found in the response." )
+
return {
+
name : parsed_response [ name ]
+
for name in keys
+
if name in parsed_response
+
}
+
diff --git a/en/_modules/agentscope/parsers/tagged_content_parser.html b/en/_modules/agentscope/parsers/tagged_content_parser.html
index fc3262d58..3f0371206 100644
--- a/en/_modules/agentscope/parsers/tagged_content_parser.html
+++ b/en/_modules/agentscope/parsers/tagged_content_parser.html
@@ -100,10 +100,12 @@
Source code for agentscope.parsers.tagged_content_parser # -*- coding: utf-8 -*-
"""The parser for tagged content in the model response."""
import json
+
from typing import Union , Sequence , Optional , List
-
from agentscope.exception import JsonParsingError
+
from agentscope.exception import JsonParsingError , TagNotFoundError
from agentscope.models import ModelResponse
from agentscope.parsers import ParserBase
+
from agentscope.parsers.parser_base import DictFilterMixin
@@ -113,7 +115,8 @@
Source code for agentscope.parsers.tagged_content_parser and tag end."""
name : str
-
"""The name of the tagged content."""
+
"""The name of the tagged content, which will be used as the key in
+
extracted dictionary."""
tag_begin : str
"""The beginning tag."""
@@ -167,7 +170,7 @@
Source code for agentscope.parsers.tagged_content_parser
[docs]
-
class MultiTaggedContentParser ( ParserBase ):
+
class MultiTaggedContentParser ( ParserBase , DictFilterMixin ):
"""Parse response text by multiple tags, and return a dict of their
content. Asking llm to generate JSON dictionary object directly maybe not a
good idea due to involving escape characters and other issues. So we can
@@ -188,14 +191,60 @@
Source code for agentscope.parsers.tagged_content_parser
[docs]
-
def __init__ ( self , * tagged_contents : TaggedContent ) -> None :
+
def __init__ (
+
self ,
+
* tagged_contents : TaggedContent ,
+
keys_to_memory : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_content : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_metadata : Optional [ Union [ str , bool , Sequence [ str ]]] = False ,
+
keys_allow_missing : Optional [ List [ str ]] = None ,
+
) -> None :
"""Initialize the parser with tags.
Args:
-
tags (`dict[str, Tuple[str, str]]`):
-
A dictionary of tags, the key is the tag name, and the value is
-
a tuple of starting tag and end tag.
+
*tagged_contents (`dict[str, Tuple[str, str]]`):
+
Multiple TaggedContent objects, each object contains the tag
+
name, tag begin, content hint and tag end. The name will be
+
used as the key in the extracted dictionary.
+
required_keys (`Optional[List[str]]`, defaults to `None`):
+
A list of required
+
keys_to_memory (`Optional[Union[str, bool, Sequence[str]]]`,
+
defaults to `True`):
+
The key or keys to be filtered in `to_memory` method. If
+
it's
+
- `False`, `None` will be returned in the `to_memory` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_content (`Optional[Union[str, bool, Sequence[str]]`,
+
defaults to `True`):
+
The key or keys to be filtered in `to_content` method. If
+
it's
+
- `False`, `None` will be returned in the `to_content` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_metadata (`Optional[Union[str, bool, Sequence[str]]]`,
+
defaults to `False`):
+
The key or keys to be filtered in `to_metadata` method. If
+
it's
+
- `False`, `None` will be returned in the `to_metadata` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_allow_missing (`Optional[List[str]]`, defaults to `None`):
+
A list of keys that are allowed to be missing in the response.
"""
+
# Initialize the mixin class
+
DictFilterMixin . __init__ (
+
self ,
+
keys_to_memory = keys_to_memory ,
+
keys_to_content = keys_to_content ,
+
keys_to_metadata = keys_to_metadata ,
+
)
+
+
self . keys_allow_missing = keys_allow_missing
+
self . tagged_contents = list ( tagged_contents )
# Prepare the format instruction according to the tagged contents
@@ -235,26 +284,38 @@
Source code for agentscope.parsers.tagged_content_parser tag_begin = tagged_content . tag_begin
tag_end = tagged_content . tag_end
- extract_content = self . _extract_first_content_by_tag (
- response ,
- tag_begin ,
- tag_end ,
- )
-
- if tagged_content . parse_json :
- try :
- extract_content = json . loads ( extract_content )
- except json . decoder . JSONDecodeError as e :
- raw_response = f " { tag_begin }{ extract_content }{ tag_end } "
- raise JsonParsingError (
- f "The content between { tagged_content . tag_begin } and "
- f " { tagged_content . tag_end } should be a JSON object."
- f 'When parsing " { raw_response } ", an error occurred: '
- f " { e } " ,
- raw_response = raw_response ,
- ) from None
-
- tag_to_content [ tagged_content . name ] = extract_content
+ try :
+ extract_content = self . _extract_first_content_by_tag (
+ response ,
+ tag_begin ,
+ tag_end ,
+ )
+
+ if tagged_content . parse_json :
+ try :
+ extract_content = json . loads ( extract_content )
+ except json . decoder . JSONDecodeError as e :
+ raw_response = f " { tag_begin }{ extract_content }{ tag_end } "
+ raise JsonParsingError (
+ f "The content between "
+ f " { tagged_content . tag_begin } and "
+ f " { tagged_content . tag_end } should be a JSON "
+ f 'object. An error " { e } " occurred when parsing: '
+ f " { raw_response } " ,
+ raw_response = raw_response ,
+ ) from None
+
+ tag_to_content [ tagged_content . name ] = extract_content
+
+ except TagNotFoundError as e :
+ # if the key is allowed to be missing, skip the error
+ if (
+ self . keys_allow_missing is not None
+ and tagged_content . name in self . keys_allow_missing
+ ):
+ continue
+
+ raise e from None
response . parsed = tag_to_content
return response
diff --git a/en/_sources/tutorial/203-parser.md.txt b/en/_sources/tutorial/203-parser.md.txt
new file mode 100644
index 000000000..1ce87be1a
--- /dev/null
+++ b/en/_sources/tutorial/203-parser.md.txt
@@ -0,0 +1,480 @@
+(203-parser-en)=
+
+# Model Response Parser
+
+## Table of Contents
+
+- [Background](#background)
+- [Parser Module](#parser-module)
+ - [Overview](#overview)
+ - [String Type](#string-type)
+ - [MarkdownCodeBlockParser](#markdowncodeblockparser)
+ - [Initialization](#initialization)
+ - [Format Instruction Template](#format-instruction-template)
+ - [Parse Function](#parse-function)
+ - [Dictionary Type](#dictionary-type)
+ - [MarkdownJsonDictParser](#markdownjsondictparser)
+ - [Initialization & Format Instruction Template](#initialization--format-instruction-template)
+ - [MultiTaggedContentParser](#multitaggedcontentparser)
+ - [Initialization & Format Instruction Template](#initialization--format-instruction-template-1)
+ - [Parse Function](#parse-function-1)
+ - [JSON / Python Object Type](#json--python-object-type)
+ - [MarkdownJsonObjectParser](#markdownjsonobjectparser)
+ - [Initialization & Format Instruction Template](#initialization--format-instruction-template-2)
+ - [Parse Function](#parse-function-2)
+- [Typical Use Cases](#typical-use-cases)
+ - [WereWolf Game](#werewolf-game)
+ - [ReAct Agent and Tool Usage](#react-agent-and-tool-usage)
+- [Customized Parser](#customized-parser)
+
+## Background
+
+In the process of building LLM-empowered application, parsing the LLM generated string into a specific format and extracting the required information is a very important step.
+However, due to the following reasons, this process is also a very complex process:
+
+1. **Diversity**: The target format of parsing is diverse, and the information to be extracted may be a specific text, a JSON object, or a complex data structure.
+2. **Complexity**: The result parsing is not only to convert the text generated by LLM into the target format, but also involves a series of issues such as prompt engineering (reminding LLM what format of output should be generated), error handling, etc.
+3. **Flexibility**: Even in the same application, different stages may also require the agent to generate output in different formats.
+
+For the convenience of developers, AgentScope provides a parser module to help developers parse LLM response into a specific format. By using the parser module, developers can easily parse the response into the target format by simple configuration, and switch the target format flexibly.
+
+In AgentScope, the parser module features
+1. **Flexibility**: Developers can flexibly set the required format, flexibly switch the parser without modifying the code of agent class. That is, the specific "target format" and the agent's `reply` function are decoupled.
+2. **Freedom**: The format instruction, result parsing and prompt engineering are all explicitly finished in the `reply` function. Developers and users can freely choose to use the parser or parse LLM response by their own code.
+3. **Transparency**: When using the parser, the process and results of prompt construction are completely visible and transparent to developers in the `reply` function, and developers can precisely debug their applications.
+
+## Parser Module
+
+### Overview
+
+The main functions of the parser module include:
+
+1. Provide "format instruction", that is, remind LLM where to generate what output, for example
+
+> You should generate python code in a fenced code block as follows
+>
+> \```python
+>
+> {your_python_code}
+>
+> \```
+
+2. Provide a parse function, which directly parses the text generated by LLM into the target data format,
+
+3. Post-processing for dictionary format. After parsing the text into a dictionary, different fields may have different uses.
+
+AgentScope provides multiple built-in parsers, and developers can choose according to their needs.
+
+| Target Format | Parser Class | Description |
+| --- | --- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| String | `MarkdownCodeBlockParser` | Requires LLM to generate specified text within a Markdown code block marked by ```. The result is a string. |
+| Dictionary | `MarkdownJsonDictParser` | Requires LLM to produce a specified dictionary within the code block marked by \```json and \```. The result is a Python dictionary. |
+| | `MultiTaggedContentParser` | Requires LLM to generate specified content within multiple tags. Contents from different tags will be parsed into a single Python dictionary with different key-value pairs. |
+| JSON / Python Object Type | `MarkdownJsonObjectParser` | Requires LLM to produce specified content within the code block marked by \```json and \```. The result will be converted into a Python object via json.loads. |
+
+> **NOTE**: Compared to `MarkdownJsonDictParser`, `MultiTaggedContentParser` is more suitable for weak LLMs and when the required format is too complex.
+> For example, when LLM is required to generate Python code, if the code is returned directly within a dictionary, LLM needs to be aware of escaping characters (\t, \n, ...), and the differences between double and single quotes when calling `json.loads`
+>
+> In contrast, `MultiTaggedContentParser` guides LLM to generate each key-value pair separately in individual tags and then combines them into a dictionary, thus reducing the difficulty.
+
+
+In the following sections, we will introduce the usage of these parsers based on different target formats.
+
+### String Type
+
+
+
+ MarkdownCodeBlockParser
+
+##### Initialization
+
+- `MarkdownCodeBlockParser` requires LLM to generate specific text within a specified code block in Markdown format. Different languages can be specified with the `language_name` parameter to utilize the large model's ability to produce corresponding outputs. For example, when asking the large model to produce Python code, initialize as follows:
+
+ ```python
+ from agentscope.parsers import MarkdownCodeBlockParser
+
+ parser = MarkdownCodeBlockParser(language_name="python")
+ ```
+
+##### Format Instruction Template
+
+- `MarkdownCodeBlockParser` provides the following format instruction template. When the user calls the `format_instruction` attribute, `{language_name}` will be replaced with the string entered at initialization:
+
+ > You should generate {language_name} code in a {language_name} fenced code block as follows:
+ >
+ > \```{language_name}
+ >
+ > ${your_{language_name}_code}
+ >
+ > \```
+
+- For the above initialization with `language_name` as `"python"`, when the `format_instruction` attribute is called, the following string will be returned:
+
+ ```python
+ print(parser.format_instruction)
+ ```
+
+ > You should generate python code in a python fenced code block as follows
+ >
+ > \```python
+ >
+ > ${your_python_code}
+ >
+ > \```
+
+##### Parse Function
+
+- `MarkdownCodeBlockParser` provides a `parse` method to parse the text generated by LLM。Its input and output are both `ModelResponse` objects, and the parsing result will be mounted on the `parsed` attribute of the output object.
+
+ ````python
+ res = parser.parse(
+ ModelResponse(
+ text="""The following is generated python code
+ ```python
+ print("Hello world!")
+ ```
+ """
+ )
+ )
+
+ print(res.parsed)
+ ````
+
+ > print("hello world!")
+
+
+
+### Dictionary Type
+
+Different from string and general JSON/Python object, as a powerful format in LLM applications, AgentScope provides additional post-processing functions for dictionary type.
+When initializing the parser, you can set the `keys_to_content`, `keys_to_memory`, and `keys_to_metadata` parameters to achieve filtering of key-value pairs when calling the parser's `to_content`, `to_memory`, and `to_metadata` methods.
+
+- `keys_to_content` specifies the key-value pairs that will be placed in the `content` field of the returned `Msg` object. The content field will be returned to other agents, participate in their prompt construction, and will also be called by the `self.speak` function for display.
+- `keys_to_memory` specifies the key-value pairs that will be stored in the memory of the agent.
+- `keys_to_metadata` specifies the key-value pairs that will be placed in the `metadata` field of the returned `Msg` object, which can be used for application control flow judgment, or mount some information that does not need to be returned to other agents.
+
+The three parameters receive bool values, string and a list of strings. The meaning of their values is as follows:
+- `False`: The corresponding filter function will return `None`.
+- `True`: The whole dictionary will be returned.
+- `str`: The corresponding value will be directly returned.
+- `List[str]`: A filtered dictionary will be returned according to the list of keys.
+
+By default, `keys_to_content` and `keys_to_memory` are `True`, that is, the whole dictionary will be returned. `keys_to_metadata` defaults to `False`, that is, the corresponding filter function will return `None`.
+
+For example, the dictionary generated by the werewolf in the daytime discussion in a werewolf game. In this example,
+- `"thought"` should not be returned to other agents, but should be stored in the agent's memory to ensure the continuity of the werewolf strategy;
+- `"speak"` should be returned to other agents and stored in the agent's memory;
+- `"finish_discussion"` is used in the application's control flow to determine whether the discussion has ended. To save tokens, this field should not be returned to other agents or stored in the agent's memory.
+
+ ```python
+ {
+ "thought": "The others didn't realize I was a werewolf. I should end the discussion soon.",
+ "speak": "I agree with you.",
+ "finish_discussion": True
+ }
+ ```
+
+In AgentScope, we achieve post-processing by calling the `to_content`, `to_memory`, and `to_metadata` methods, as shown in the following code:
+
+- The code for the application's control flow, create the corresponding parser object and load it
+
+ ```python
+ from agentscope.parsers import MarkdownJsonDictParser
+
+ # ...
+
+ agent = DictDialogAgent(...)
+
+ # Take MarkdownJsonDictParser as example
+ parser = MarkdownJsonDictParser(
+ content_hint={
+ "thought": "what you thought",
+ "speak": "what you speak",
+ "finish_discussion": "whether the discussion is finished"
+ },
+ keys_to_content="speak",
+ keys_to_memory=["thought", "speak"],
+ keys_to_metadata=["finish_discussion"]
+ )
+
+ # Load parser, which is equivalent to specifying the required format
+ agent.set_parser(parser)
+
+ # The discussion process
+ while True:
+ # ...
+ x = agent(x)
+ # Break the loop according to the finish_discussion field in metadata
+ if x.metadata["finish_discussion"]:
+ break
+ ```
+
+- Filter the dictionary in the agent's `reply` function
+
+ ```python
+ # ...
+ def reply(x: dict = None) -> None:
+
+ # ...
+ res = self.model(prompt, parse_func=self.parser.parse)
+
+ # Story the thought and speak fields into memory
+ self.memory.add(
+ Msg(
+ self.name,
+ content=self.parser.to_memory(res.parsed),
+ role="assistant",
+ )
+ )
+
+ # Store in content and metadata fields in the returned Msg object
+ msg = Msg(
+ self.name,
+ content=self.parser.to_content(res.parsed),
+ role="assistant",
+ metadata=self.parser.to_metadata(res.parsed),
+ )
+ self.speak(msg)
+
+ return msg
+ ```
+
+> **Note**: `keys_to_content`, `keys_to_memory`, and `keys_to_metadata` parameters can be a string, a list of strings, or a bool value.
+> - For `True`, the `to_content`, `to_memory`, and `to_metadata` methods will directly return the whole dictionary.
+> - For `False`, the `to_content`, `to_memory`, and `to_metadata` methods will directly return `None`.
+> - For a string, the `to_content`, `to_memory`, and `to_metadata` methods will directly extract the corresponding value. For example, if `keys_to_content="speak"`, the `to_content` method will put `res.parsed["speak"]` into the `content` field of the `Msg` object, and the `content` field will be a string rather than a dictionary.
+> - For a list of string, the `to_content`, `to_memory`, and `to_metadata` methods will filter the dictionary according to the list of keys.
+> ```python
+> parser = MarkdownJsonDictParser(
+> content_hint={
+> "thought": "what you thought",
+> "speak": "what you speak",
+> },
+> keys_to_content="speak",
+> keys_to_memory=["thought", "speak"],
+> )
+>
+> example_dict = {"thought": "abc", "speak": "def"}
+> print(parser.to_content(example_dict)) # def
+> print(parser.to_memory(example_dict)) # {"thought": "abc", "speak": "def"}
+> print(parser.to_metadata(example_dict)) # None
+> ```
+> > def
+> >
+> > {"thought": "abc", "speak": "def"}
+> >
+> > None
+
+
+Next we will introduce two parsers for dictionary type.
+
+
+
+ MarkdownJsonDictParser
+
+##### Initialization & Format Instruction Template
+
+- `MarkdownJsonDictParser` requires LLM to generate dictionary within a code block fenced by \```json and \``` tags.
+
+- Except `keys_to_content`, `keys_to_memory` and `keys_to_metadata`, the `content_hint` parameter can be provided to give an example and explanation of the response result, that is, to remind LLM where and what kind of dictionary should be generated.
+This parameter can be a string or a dictionary. For dictionary, it will be automatically converted to a string when constructing the format instruction.
+
+ ```python
+ from agentscope.parsers import MarkdownJsonDictParser
+
+ # dictionary as content_hint
+ MarkdownJsonDictParser(
+ content_hint={
+ "thought": "what you thought",
+ "speak": "what you speak",
+ }
+ )
+ # or string as content_hint
+ MarkdownJsonDictParser(
+ content_hint="""{
+ "thought": "what you thought",
+ "speak": "what you speak",
+ }"""
+ )
+ ```
+
+ - The corresponding `instruction_format` attribute
+
+ > You should respond a json object in a json fenced code block as follows:
+ >
+ > \```json
+ >
+ > {content_hint}
+ >
+ > \```
+
+
+
+
+
+ MultiTaggedContentParser
+
+`MultiTaggedContentParser` asks LLM to generate specific content within multiple tag pairs. The content from different tag pairs will be parsed into a single Python dictionary. Its usage is similar to `MarkdownJsonDictParser`, but the initialization method is different, and it is more suitable for weak LLMs or complex return content.
+
+##### Initialization & Format Instruction Template
+
+Within `MultiTaggedContentParser`, each tag pair will be specified by as `TaggedContent` object, which contains
+- Tag name (`name`), the key value in the returned dictionary
+- Start tag (`tag_begin`)
+- Hint for content (`content_hint`)
+- End tag (`tag_end`)
+- Content parsing indication (`parse_json`), default as `False`. When set to `True`, the parser will automatically add hint that requires JSON object between the tags, and its extracted content will be parsed into a Python object via `json.loads`
+
+```python
+from agentscope.parsers import MultiTaggedContentParser, TaggedContent
+parser = MultiTaggedContentParser(
+ TaggedContent(
+ name="thought",
+ tag_begin="[THOUGHT]",
+ content_hint="what you thought",
+ tag_end="[/THOUGHT]"
+ ),
+ TaggedContent(
+ name="speak",
+ tag_begin="[SPEAK]",
+ content_hint="what you speak",
+ tag_end="[/SPEAK]"
+ ),
+ TaggedContent(
+ name="finish_discussion",
+ tag_begin="[FINISH_DISCUSSION]",
+ content_hint="true/false, whether the discussion is finished",
+ tag_end="[/FINISH_DISCUSSION]",
+ parse_json=True, # we expect the content of this field to be parsed directly into a Python boolean value
+ )
+)
+
+print(parser.format_instruction)
+```
+
+> Respond with specific tags as outlined below, and the content between [FINISH_DISCUSSION] and [/FINISH_DISCUSSION] MUST be a JSON object:
+>
+> [THOUGHT]what you thought[/THOUGHT]
+>
+> [SPEAK]what you speak[/SPEAK]
+>
+> [FINISH_DISCUSSION]true/false, whether the discussion is finished[/FINISH_DISCUSSION]
+
+##### Parse Function
+
+- `MultiTaggedContentParser`'s parsing result is a dictionary, whose keys are the value of `name` in the `TaggedContent` objects.
+The following is an example of parsing the LLM response in the werewolf game:
+
+```python
+res_dict = parser.parse(
+ ModelResponse(
+ text="""As a werewolf, I should keep pretending to be a villager
+[THOUGHT]The others didn't realize I was a werewolf. I should end the discussion soon.[/THOUGHT]
+[SPEAK]I agree with you.[/SPEAK]
+[FINISH_DISCUSSION]true[/FINISH_DISCUSSION]"""
+ )
+)
+
+print(res_dict)
+```
+
+> {
+>
+> "thought": "The others didn't realize I was a werewolf. I should end the discussion soon.",
+>
+> "speak": "I agree with you.",
+>
+> "finish_discussion": true
+>
+> }
+
+
+
+### JSON / Python Object Type
+
+
+
+ MarkdownJsonObjectParser
+
+`MarkdownJsonObjectParser` also uses the \```json and \``` tags in Markdown, but does not limit the content type. It can be a list, dictionary, number, string, etc., which can be parsed into a Python object via `json.loads`.
+
+##### Initialization & Format Instruction Template
+
+```python
+from agentscope.parsers import MarkdownJsonObjectParser
+
+parser = MarkdownJsonObjectParser(
+ content_hint="{A list of numbers.}"
+)
+
+print(parser.format_instruction)
+```
+
+> You should respond a json object in a json fenced code block as follows:
+>
+> \```json
+>
+> {a list of numbers}
+>
+> \```
+
+##### Parse Function
+
+````python
+res = parser.parse(
+ ModelResponse(
+ text="""Yes, here is the generated list
+```json
+[1,2,3,4,5]
+```
+""")
+)
+
+print(type(res))
+print(res)
+````
+>
+>
+> [1, 2, 3, 4, 5]
+
+
+
+## Typical Use Cases
+
+### WereWolf Game
+
+Werewolf game is a classic use case of dictionary parser. In different stages of the game, the same agent needs to generate different identification fields in addition to `"thought"` and `"speak"`, such as whether the discussion is over, whether the seer uses its ability, whether the witch uses the antidote and poison, and voting.
+
+AgentScope has built-in examples of [werewolf game](https://github.com/modelscope/agentscope/tree/main/examples/game_werewolf), which uses `DictDialogAgent` class and different parsers to achieve flexible target format switching. By using the post-processing function of the parser, it separates "thought" and "speak", and controls the progress of the game successfully.
+More details can be found in the werewolf game [source code](https://github.com/modelscope/agentscope/tree/main/examples/game_werewolf).
+
+### ReAct Agent and Tool Usage
+
+`ReActAgent` is an agent class built for tool usage in AgentScope, based on the ReAct algorithm, and can be used with different tool functions. The tool call, format parsing, and implementation of `ReActAgent` are similar to the parser. For detailed implementation, please refer to the [source code](https://github.com/modelscope/agentscope/blob/main/src/agentscope/agents/react_agent.py).
+
+
+## Customized Parser
+
+AgentScope provides a base class `ParserBase` for parsers. Developers can inherit this base class, and implement the `format_instruction` attribute and `parse` method to create their own parser.
+
+For dictionary type parsing, you can also inherit the `agentscope.parser.DictFilterMixin` class to implement post-processing for dictionary type.
+
+```python
+from abc import ABC, abstractmethod
+
+from agentscope.models import ModelResponse
+
+
+class ParserBase(ABC):
+ """The base class for model response parser."""
+
+ format_instruction: str
+ """The instruction for the response format."""
+
+ @abstractmethod
+ def parse(self, response: ModelResponse) -> ModelResponse:
+ """Parse the response text to a specific object, and stored in the
+ parsed field of the response object."""
+
+ # ...
+```
diff --git a/en/_sources/tutorial/advance.rst.txt b/en/_sources/tutorial/advance.rst.txt
index ff483b9b2..64bd86508 100644
--- a/en/_sources/tutorial/advance.rst.txt
+++ b/en/_sources/tutorial/advance.rst.txt
@@ -7,6 +7,7 @@ Advanced Exploration
201-agent.md
202-pipeline.md
203-model.md
+ 203-parser.md
204-service.md
205-memory.md
206-prompt.md
diff --git a/en/agentscope.agents.dict_dialog_agent.html b/en/agentscope.agents.dict_dialog_agent.html
index 7c3e5ddbb..0d67c69cb 100644
--- a/en/agentscope.agents.dict_dialog_agent.html
+++ b/en/agentscope.agents.dict_dialog_agent.html
@@ -97,44 +97,20 @@
agentscope.agents.dict_dialog_agent
-A dict dialog agent that using parse_func and fault_handler to
-parse the model response.
-
-
-agentscope.agents.dict_dialog_agent. parse_dict ( response : ModelResponse ) → ModelResponse [source]
-Parse function for DictDialogAgent
-
-
-
-
-agentscope.agents.dict_dialog_agent. default_response ( response : ModelResponse ) → ModelResponse [source]
-The default response of fault_handler
-
-
+An agent that replies in a dictionary format.
class agentscope.agents.dict_dialog_agent. DictDialogAgent ( * args : tuple ** kwargs : dict ) [source]
Bases: AgentBase
An agent that generates response in a dict format, where user can
-specify the required fields in the response via prompt, e.g.
-prompt = "... Response in the following format that can be loaded by
-python json . loads ()
-{
- "thought" : "thought" ,
- "speak" : "thoughts summary to say to others" ,
- # ...
-} "
-
-
This agent class is an example for using parse_func and fault_handler
-to parse the output from the model, and handling the fault when parsing
-fails. We take “speak” as a required field in the response, and print
-the speak field as the output response.
+specify the required fields in the response via specifying the parser
+About parser, please refer to our
+[tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html )
For usage example, please refer to the example of werewolf in
examples/game_werewolf
-__init__ ( name: str, sys_prompt: str, model_config_name: str, use_memory: bool = True, memory_config: dict | None = None, parse_func: ~typing.Callable[[...], ~typing.Any] | None = <function parse_dict>, fault_handler: ~typing.Callable[[...], ~typing.Any] | None = <function default_response>, max_retries: int | None = 3, prompt_type: ~agentscope.prompt.PromptType | None = None ) → None [source]
+__init__ ( name : str sys_prompt : str model_config_name : str use_memory : bool = True memory_config : dict | None = None max_retries : int | None = 3 ) → None [source] Initialize the dict dialog agent.
Parameters:
@@ -146,20 +122,22 @@
configuration.
use_memory (bool , defaults to True ) – Whether the agent has memory.
memory_config (Optional[dict] , defaults to None ) – The config of memory.
parse_func (Optional[Callable[…, Any]] , defaults to parse_dict ) – The function used to parse the model output,
-e.g. json.loads , which is used to extract json from the
-output.
fault_handler (Optional[Callable[…, Any]] , defaults to default_response ) – The function used to handle the fault when parse_func fails
-to parse the model output.
max_retries (Optional[int] , defaults to None ) – The maximum number of retries when failed to parse the model
output.
prompt_type (Optional[PromptType] , defaults to PromptType.LIST ) – The type of the prompt organization, chosen from
-PromptType.LIST or PromptType.STRING .
+
+
+set_parser ( parser : ParserBase ) → None [source]
+Set response parser, which will provide 1) format instruction; 2)
+response parsing; 3) filtering fields when returning message, storing
+message in memory. So developers only need to change the
+parser, and the agent will work as expected.
+
+
reply ( x : dict | None = None ) → dict [source]
diff --git a/en/agentscope.agents.html b/en/agentscope.agents.html
index aa36980a0..2dd2fe7a7 100644
--- a/en/agentscope.agents.html
+++ b/en/agentscope.agents.html
@@ -397,25 +397,14 @@
class agentscope.agents. DictDialogAgent ( * args : tuple ** kwargs : dict ) [source] Bases: AgentBase
An agent that generates response in a dict format, where user can
-specify the required fields in the response via prompt, e.g.
-prompt = "... Response in the following format that can be loaded by
-python json . loads ()
-{
- "thought" : "thought" ,
- "speak" : "thoughts summary to say to others" ,
- # ...
-} "
-
-
This agent class is an example for using parse_func and fault_handler
-to parse the output from the model, and handling the fault when parsing
-fails. We take “speak” as a required field in the response, and print
-the speak field as the output response.
+specify the required fields in the response via specifying the parser
+About parser, please refer to our
+[tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html )
For usage example, please refer to the example of werewolf in
examples/game_werewolf
-__init__ ( name: str, sys_prompt: str, model_config_name: str, use_memory: bool = True, memory_config: dict | None = None, parse_func: ~typing.Callable[[...], ~typing.Any] | None = <function parse_dict>, fault_handler: ~typing.Callable[[...], ~typing.Any] | None = <function default_response>, max_retries: int | None = 3, prompt_type: ~agentscope.prompt.PromptType | None = None ) → None [source]
+__init__ ( name : str sys_prompt : str model_config_name : str use_memory : bool = True memory_config : dict | None = None max_retries : int | None = 3 ) → None [source] Initialize the dict dialog agent.
Parameters:
@@ -427,20 +416,22 @@
configuration.
use_memory (bool , defaults to True ) – Whether the agent has memory.
memory_config (Optional[dict] , defaults to None ) – The config of memory.
parse_func (Optional[Callable[…, Any]] , defaults to parse_dict ) – The function used to parse the model output,
-e.g. json.loads , which is used to extract json from the
-output.
fault_handler (Optional[Callable[…, Any]] , defaults to default_response ) – The function used to handle the fault when parse_func fails
-to parse the model output.
max_retries (Optional[int] , defaults to None ) – The maximum number of retries when failed to parse the model
output.
prompt_type (Optional[PromptType] , defaults to PromptType.LIST ) – The type of the prompt organization, chosen from
-PromptType.LIST or PromptType.STRING .
+
+
+set_parser ( parser : ParserBase ) → None [source]
+Set response parser, which will provide 1) format instruction; 2)
+response parsing; 3) filtering fields when returning message, storing
+message in memory. So developers only need to change the
+parser, and the agent will work as expected.
+
+
reply ( x : dict | None = None ) → dict [source]
diff --git a/en/agentscope.message.html b/en/agentscope.message.html
index b8da4938b..d8a944d51 100644
--- a/en/agentscope.message.html
+++ b/en/agentscope.message.html
@@ -152,12 +152,55 @@
-class agentscope.message. Msg ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False ** kwargs : Any ) [source]
+class agentscope.message. Msg ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False metadata : dict | str | None = None ** kwargs : Any ) [source] Bases: MessageBase
The Message class.
+
+
+id : str
+The id of the message.
+
+
+
+
+name : str
+The name of who send the message.
+
+
+
+
+content : Any
+The content of the message.
+
+
+
+
+role : Literal [ 'system' , 'user' , 'assistant' ]
+The role of the message sender.
+
+
+
+
+metadata : dict | None
+Save the information for application’s control flow, or other
+purposes.
+
+
+
+
+url : Sequence [ str ] | str | None
+A url to file, image, video, audio or website.
+
+
+
+
+timestamp : str
+The timestamp of the message.
+
+
-__init__ ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False ** kwargs : Any ) → None [source]
+__init__ ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False metadata : dict | str | None = None ** kwargs : Any ) → None [source] Initialize the message object
Parameters:
@@ -170,6 +213,9 @@
url (Optional[Union[list[str], str]] , defaults to None ) – A url to file, image, video, audio or website.
timestamp (Optional[str] , defaults to None ) – The timestamp of the message, if None, it will be set to
current time.
echo (bool , defaults to False ) – Whether to print the message to the console.
metadata (Optional[Union[dict, str]] , defaults to None ) – Save the information for application’s control flow, or other
+purposes.
**kwargs (Any ) – Other attributes of the message.
Model response parser class for Markdown code block.
-class agentscope.parsers.code_block_parser. MarkdownCodeBlockParser ( language_name : str ) [source]
+class agentscope.parsers.code_block_parser. MarkdownCodeBlockParser ( language_name : str content_hint : str | None = None ) [source] Bases: ParserBase
The base class for parsing the response text by fenced block.
-
-
-content_hint : str = '${{your_{language_name}_code}}'
-The hint of the content.
-
-
tag_end : str = '```'
@@ -117,8 +111,16 @@
-__init__ ( language_name : str ) → None [source]
-
+__init__ ( language_name : str content_hint : str | None = None ) → None [source] Initialize the parser with the language name and the optional
+content hint.
+
+Parameters:
+language_name – The name of the language, which will be used
+in `` `
+
+
@@ -132,9 +134,15 @@
The beginning tag.
+
+
+content_hint : str = '${{your_{language_name}_code}}'
+The hint of the content.
+
+
-format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n${{your_{language_name}_code}}\n```'
+format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n{content_hint}\n```' The instruction for the format of the code block.
diff --git a/en/agentscope.parsers.html b/en/agentscope.parsers.html
index 15d715e22..c880d5b9b 100644
--- a/en/agentscope.parsers.html
+++ b/en/agentscope.parsers.html
@@ -183,8 +183,8 @@
-class agentscope.parsers. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) [source]
-Bases: MarkdownJsonObjectParser
+class agentscope.parsers. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) [source] Bases: MarkdownJsonObjectParser DictFilterMixin
A class used to parse a JSON dictionary object in a markdown fenced
code
@@ -213,7 +213,7 @@
-__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) → None [source]
+__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) → None [source] Initialize the parser with the content hint.
Parameters:
@@ -225,9 +225,57 @@
required_keys (List[str] , defaults to [] ) – A list of required keys in the JSON dictionary object. If the
response misses any of the required keys, it will raise a
RequiredFieldNotFoundError.
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
@@ -250,15 +298,9 @@
-class agentscope.parsers. MarkdownCodeBlockParser ( language_name : str ) [source]
+class agentscope.parsers. MarkdownCodeBlockParser ( language_name : str content_hint : str | None = None ) [source] Bases: ParserBase
The base class for parsing the response text by fenced block.
-
-
-content_hint : str = '${{your_{language_name}_code}}'
-The hint of the content.
-
-
tag_end : str = '```'
@@ -267,8 +309,16 @@
-__init__ ( language_name : str ) → None [source]
-
+__init__ ( language_name : str content_hint : str | None = None ) → None [source] Initialize the parser with the language name and the optional
+content hint.
+
+Parameters:
+language_name – The name of the language, which will be used
+in `` `
+
+
@@ -282,9 +332,15 @@
The beginning tag.
+
+
+content_hint : str = '${{your_{language_name}_code}}'
+The hint of the content.
+
+
-format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n${{your_{language_name}_code}}\n```'
+format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n{content_hint}\n```' The instruction for the format of the code block.
@@ -323,7 +379,8 @@
name : str
-The name of the tagged content.
+The name of the tagged content, which will be used as the key in
+extracted dictionary.
@@ -354,8 +411,8 @@
-class agentscope.parsers. MultiTaggedContentParser ( * tagged_contents : TaggedContent ) [source]
-Bases: ParserBase
+class agentscope.parsers. MultiTaggedContentParser ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) [source] Bases: ParserBase DictFilterMixin
Parse response text by multiple tags, and return a dict of their
content. Asking llm to generate JSON dictionary object directly maybe not a
good idea due to involving escape characters and other issues. So we can
@@ -371,12 +428,69 @@
-__init__ ( * tagged_contents : TaggedContent ) → None [source]
+__init__ ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) → None [source] Initialize the parser with tags.
Parameters:
-tags (dict[str, Tuple[str, str]] ) – A dictionary of tags, the key is the tag name, and the value is
-a tuple of starting tag and end tag.
+
+*tagged_contents (dict[str, Tuple[str, str]] ) – Multiple TaggedContent objects, each object contains the tag
+name, tag begin, content hint and tag end. The name will be
+used as the key in the extracted dictionary.
required_keys (Optional[List[str]] , defaults to None ) – A list of required
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+keys_allow_missing (Optional[List[str]] , defaults to None ) – A list of keys that are allowed to be missing in the response.
diff --git a/en/agentscope.parsers.json_object_parser.html b/en/agentscope.parsers.json_object_parser.html
index a9def88c2..437e6bfa9 100644
--- a/en/agentscope.parsers.json_object_parser.html
+++ b/en/agentscope.parsers.json_object_parser.html
@@ -159,8 +159,8 @@
-class agentscope.parsers.json_object_parser. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) [source]
-Bases: MarkdownJsonObjectParser
+class agentscope.parsers.json_object_parser. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) [source] Bases: MarkdownJsonObjectParser DictFilterMixin
A class used to parse a JSON dictionary object in a markdown fenced
code
@@ -189,7 +189,7 @@
-__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) → None [source]
+__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) → None [source] Initialize the parser with the content hint.
Parameters:
@@ -201,9 +201,57 @@
required_keys (List[str] , defaults to [] ) – A list of required keys in the JSON dictionary object. If the
response misses any of the required keys, it will raise a
RequiredFieldNotFoundError.
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
diff --git a/en/agentscope.parsers.parser_base.html b/en/agentscope.parsers.parser_base.html
index d164370f4..0636fc046 100644
--- a/en/agentscope.parsers.parser_base.html
+++ b/en/agentscope.parsers.parser_base.html
@@ -112,6 +112,66 @@
+
+
+class agentscope.parsers.parser_base. DictFilterMixin ( keys_to_memory : str | bool | Sequence [ str ] keys_to_content : str | bool | Sequence [ str ] keys_to_metadata : str | bool | Sequence [ str ] ) [source]
+Bases: object
+A mixin class to filter the parsed response by keys. It allows users
+to set keys to be filtered during speaking, storing in memory, and
+returning in the agent reply function.
+
+
+__init__ ( keys_to_memory : str | bool | Sequence [ str ] keys_to_content : str | bool | Sequence [ str ] keys_to_metadata : str | bool | Sequence [ str ] ) → None [source]
+Initialize the mixin class with the keys to be filtered during
+speaking, storing in memory, and returning in the agent reply function.
+
+Parameters:
+
+keys_to_memory (Optional[Union[str, bool, Sequence[str]]] ) – The key or keys to be filtered in to_memory method. If
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
keys_to_content (Optional[Union[str, bool, Sequence[str]] ) – The key or keys to be filtered in to_content method. If
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
keys_to_metadata (Optional[Union[str, bool, Sequence[str]]] ) – The key or keys to be filtered in to_metadata method. If
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+
+
+
+to_memory ( parsed_response : dict allow_missing : bool = False ) → str | dict | None [source]
+Filter the fields that will be stored in memory.
+
+
+
+
+to_content ( parsed_response : dict allow_missing : bool = False ) → str | dict | None [source]
+Filter the fields that will be fed into the content field in the
+returned message, which will be exposed to other agents.
+
+
+
+
+to_metadata ( parsed_response : dict allow_missing : bool = False ) → str | dict | None [source]
+Filter the fields that will be fed into the returned message
+directly to control the application workflow.
+
+
+
+
diff --git a/en/agentscope.parsers.tagged_content_parser.html b/en/agentscope.parsers.tagged_content_parser.html
index cbad890d4..8ee2da16e 100644
--- a/en/agentscope.parsers.tagged_content_parser.html
+++ b/en/agentscope.parsers.tagged_content_parser.html
@@ -124,7 +124,8 @@
name : str
-The name of the tagged content.
+The name of the tagged content, which will be used as the key in
+extracted dictionary.
@@ -155,8 +156,8 @@
-class agentscope.parsers.tagged_content_parser. MultiTaggedContentParser ( * tagged_contents : TaggedContent ) [source]
-Bases: ParserBase
+class agentscope.parsers.tagged_content_parser. MultiTaggedContentParser ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) [source] Bases: ParserBase DictFilterMixin
Parse response text by multiple tags, and return a dict of their
content. Asking llm to generate JSON dictionary object directly maybe not a
good idea due to involving escape characters and other issues. So we can
@@ -172,12 +173,69 @@
-__init__ ( * tagged_contents : TaggedContent ) → None [source]
+__init__ ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) → None [source] Initialize the parser with tags.
Parameters:
-tags (dict[str, Tuple[str, str]] ) – A dictionary of tags, the key is the tag name, and the value is
-a tuple of starting tag and end tag.
+
+*tagged_contents (dict[str, Tuple[str, str]] ) – Multiple TaggedContent objects, each object contains the tag
+name, tag begin, content hint and tag end. The name will be
+used as the key in the extracted dictionary.
required_keys (Optional[List[str]] , defaults to None ) – A list of required
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+Parameters:
+keys_allow_missing (Optional[List[str]] , defaults to None ) – A list of keys that are allowed to be missing in the response.
diff --git a/en/genindex.html b/en/genindex.html
index 12b9c10ea..589453b53 100644
--- a/en/genindex.html
+++ b/en/genindex.html
@@ -233,6 +233,8 @@ _
(agentscope.parsers.MarkdownJsonObjectParser method)
(agentscope.parsers.MultiTaggedContentParser method)
+(agentscope.parsers.parser_base.DictFilterMixin method)
(agentscope.parsers.tagged_content_parser.MultiTaggedContentParser method)
C
(agentscope.models.zhipu_model.ZhipuAIEmbeddingWrapper attribute)
content (agentscope.message.Msg attribute)
+content_hint (agentscope.parsers.code_block_parser.MarkdownCodeBlockParser attribute)
default_response() (in module agentscope.agents.dict_dialog_agent)
-delete() (agentscope.memory.memory.MemoryBase method)
DictDialogAgentNode (class in agentscope.web.workstation.workflow_node)
+DictFilterMixin (class in agentscope.parsers.parser_base)
digest_webpage() (in module agentscope.service)
@@ -1715,6 +1719,8 @@ G
I
+ id (agentscope.message.Msg attribute)
+IfElsePipeline (class in agentscope.pipelines)
@@ -1912,6 +1918,8 @@ M
MESSAGE (agentscope.web.workstation.workflow_node.WorkflowNodeType attribute)
MessageBase (class in agentscope.message)
+metadata (agentscope.message.Msg attribute)
missing_begin_tag (agentscope.exception.TagNotFoundError attribute)
M
N
-
-
-
-
update_value() (agentscope.message.PlaceholderMessage method)
+url (agentscope.message.Msg attribute)
user_input() (in module agentscope.web.studio.utils)
Customizing Your Own Agent Pipeline and MsgHub Model Model Response Parser Service Memory Prompt Engineering Customizing Your Own Agent Pipeline and MsgHub Model Model Response Parser Service Memory Prompt Engineering Customizing Your Own Agent Pipeline and MsgHub Model Model Response Parser Service Memory Prompt Engineering Creat Your Own Model WrapperNext
+ Next
Model Response Parser — AgentScope documentation
+
+
+
+
+
+
+ AgentScope
+
+
+
+
+
+
+
+
+
+Model Response Parser
+
+
+Background
+In the process of building LLM-empowered application, parsing the LLM generated string into a specific format and extracting the required information is a very important step.
+However, due to the following reasons, this process is also a very complex process:
+
+Diversity : The target format of parsing is diverse, and the information to be extracted may be a specific text, a JSON object, or a complex data structure.
Complexity : The result parsing is not only to convert the text generated by LLM into the target format, but also involves a series of issues such as prompt engineering (reminding LLM what format of output should be generated), error handling, etc.
Flexibility : Even in the same application, different stages may also require the agent to generate output in different formats.
+For the convenience of developers, AgentScope provides a parser module to help developers parse LLM response into a specific format. By using the parser module, developers can easily parse the response into the target format by simple configuration, and switch the target format flexibly.
+In AgentScope, the parser module features
+
+Flexibility : Developers can flexibly set the required format, flexibly switch the parser without modifying the code of agent class. That is, the specific “target format” and the agent’s reply
Freedom : The format instruction, result parsing and prompt engineering are all explicitly finished in the reply
Transparency : When using the parser, the process and results of prompt construction are completely visible and transparent to developers in the reply
+
+
+Parser Module
+
+Overview
+The main functions of the parser module include:
+
+Provide “format instruction”, that is, remind LLM where to generate what output, for example
+
+You should generate python code in a fenced code block as follows
+
```python
+
{your_python_code}
+
```
+
+
+Provide a parse function, which directly parses the text generated by LLM into the target data format,
Post-processing for dictionary format. After parsing the text into a dictionary, different fields may have different uses.
+AgentScope provides multiple built-in parsers, and developers can choose according to their needs.
+
+
+Target Format
Parser Class
Description
+
+String
MarkdownCodeBlockParser
Requires LLM to generate specified text within a Markdown code block marked by ```. The result is a string.
Dictionary
MarkdownJsonDictParser
Requires LLM to produce a specified dictionary within the code block marked by ```json and ```. The result is a Python dictionary.
MultiTaggedContentParser
Requires LLM to generate specified content within multiple tags. Contents from different tags will be parsed into a single Python dictionary with different key-value pairs.
JSON / Python Object Type
MarkdownJsonObjectParser
Requires LLM to produce specified content within the code block marked by ```json and ```. The result will be converted into a Python object via json.loads.
+
+
+NOTE : Compared to MarkdownJsonDictParser MultiTaggedContentParser json.loads
+
In contrast, MultiTaggedContentParser
+
+In the following sections, we will introduce the usage of these parsers based on different target formats.
+
+
+String Type
+
+ MarkdownCodeBlockParser
+
+Initialization
+
+MarkdownCodeBlockParser language_name
+from agentscope.parsers import MarkdownCodeBlockParser
+
+parser = MarkdownCodeBlockParser ( language_name = "python" )
+
+
+
+
+
+
+
+
+Dictionary Type
+Different from string and general JSON/Python object, as a powerful format in LLM applications, AgentScope provides additional post-processing functions for dictionary type.
+When initializing the parser, you can set the keys_to_content keys_to_memory keys_to_metadata to_content to_memory to_metadata
+
+keys_to_content content Msg self.speak
keys_to_memory
keys_to_metadata metadata Msg
+The three parameters receive bool values, string and a list of strings. The meaning of their values is as follows:
+
+False None
True
str
List[str]
+By default, keys_to_content keys_to_memory True keys_to_metadata False None
+For example, the dictionary generated by the werewolf in the daytime discussion in a werewolf game. In this example,
+
+"thought"
"speak"
"finish_discussion"
+{
+ "thought" : "The others didn't realize I was a werewolf. I should end the discussion soon." ,
+ "speak" : "I agree with you." ,
+ "finish_discussion" : True
+}
+
+
+In AgentScope, we achieve post-processing by calling the to_content to_memory to_metadata
+
+The code for the application’s control flow, create the corresponding parser object and load it
+from agentscope.parsers import MarkdownJsonDictParser
+
+# ...
+
+agent = DictDialogAgent ( ... )
+
+# Take MarkdownJsonDictParser as example
+parser = MarkdownJsonDictParser (
+ content_hint = {
+ "thought" : "what you thought" ,
+ "speak" : "what you speak" ,
+ "finish_discussion" : "whether the discussion is finished"
+ },
+ keys_to_content = "speak" ,
+ keys_to_memory = [ "thought" , "speak" ],
+ keys_to_metadata = [ "finish_discussion" ]
+)
+
+# Load parser, which is equivalent to specifying the required format
+agent . set_parser ( parser )
+
+# The discussion process
+while True :
+ # ...
+ x = agent ( x )
+ # Break the loop according to the finish_discussion field in metadata
+ if x . metadata [ "finish_discussion" ]:
+ break
+
+
Filter the dictionary in the agent’s reply
+# ...
+ def reply ( x : dict = None ) -> None :
+
+ # ...
+ res = self . model ( prompt , parse_func = self . parser . parse )
+
+ # Story the thought and speak fields into memory
+ self . memory . add (
+ Msg (
+ self . name ,
+ content = self . parser . to_memory ( res . parsed ),
+ role = "assistant" ,
+ )
+ )
+
+ # Store in content and metadata fields in the returned Msg object
+ msg = Msg (
+ self . name ,
+ content = self . parser . to_content ( res . parsed ),
+ role = "assistant" ,
+ metadata = self . parser . to_metadata ( res . parsed ),
+ )
+ self . speak ( msg )
+
+ return msg
+
+
+
+Note : keys_to_content keys_to_memory keys_to_metadata
+
+For True to_content to_memory to_metadata
For False to_content to_memory to_metadata None
For a string, the to_content to_memory to_metadata keys_to_content="speak" to_content res.parsed["speak"] content Msg content
For a list of string, the to_content to_memory to_metadata
+parser = MarkdownJsonDictParser (
+ content_hint = {
+ "thought" : "what you thought" ,
+ "speak" : "what you speak" ,
+ },
+ keys_to_content = "speak" ,
+ keys_to_memory = [ "thought" , "speak" ],
+ )
+
+ example_dict = { "thought" : "abc" , "speak" : "def" }
+ print ( parser . to_content ( example_dict )) # def
+ print ( parser . to_memory ( example_dict )) # {"thought": "abc", "speak": "def"}
+ print ( parser . to_metadata ( example_dict )) # None
+
+
+def
+
{“thought”: “abc”, “speak”: “def”}
+
None
+
+
+
+Next we will introduce two parsers for dictionary type.
+
+ MarkdownJsonDictParser
+
+
+ MultiTaggedContentParser
+MultiTaggedContentParser MarkdownJsonDictParser
+
+
+Initialization & Format Instruction Template
+Within MultiTaggedContentParser TaggedContent
+
+Tag name (name
Start tag (tag_begin
Hint for content (content_hint
End tag (tag_end
Content parsing indication (parse_json False True json.loads
+from agentscope.parsers import MultiTaggedContentParser , TaggedContent
+parser = MultiTaggedContentParser (
+ TaggedContent (
+ name = "thought" ,
+ tag_begin = "[THOUGHT]" ,
+ content_hint = "what you thought" ,
+ tag_end = "[/THOUGHT]"
+ ),
+ TaggedContent (
+ name = "speak" ,
+ tag_begin = "[SPEAK]" ,
+ content_hint = "what you speak" ,
+ tag_end = "[/SPEAK]"
+ ),
+ TaggedContent (
+ name = "finish_discussion" ,
+ tag_begin = "[FINISH_DISCUSSION]" ,
+ content_hint = "true/false, whether the discussion is finished" ,
+ tag_end = "[/FINISH_DISCUSSION]" ,
+ parse_json = True , # we expect the content of this field to be parsed directly into a Python boolean value
+ )
+)
+
+print ( parser . format_instruction )
+
+
+Respond with specific tags as outlined below, and the content between [FINISH_DISCUSSION] and [/FINISH_DISCUSSION] MUST be a JSON object:
+
[THOUGHT]what you thought[/THOUGHT]
+
[SPEAK]what you speak[/SPEAK]
+
[FINISH_DISCUSSION]true/false, whether the discussion is finished[/FINISH_DISCUSSION]
+
+
+
+Parse Function
+
+res_dict = parser . parse (
+ ModelResponse (
+ text = """As a werewolf, I should keep pretending to be a villager
+[THOUGHT]The others didn't realize I was a werewolf. I should end the discussion soon.[/THOUGHT]
+[SPEAK]I agree with you.[/SPEAK]
+[FINISH_DISCUSSION]true[/FINISH_DISCUSSION]"""
+ )
+)
+
+print ( res_dict )
+
+
+{
+
“thought”: “The others didn’t realize I was a werewolf. I should end the discussion soon.”,
+
“speak”: “I agree with you.”,
+
“finish_discussion”: true
+
}
+
+
+
+
+
+JSON / Python Object Type
+
+ MarkdownJsonObjectParser
+MarkdownJsonObjectParser json.loads
+
+Initialization & Format Instruction Template
+from agentscope.parsers import MarkdownJsonObjectParser
+
+parser = MarkdownJsonObjectParser (
+ content_hint = "{A list of numbers.}"
+)
+
+print ( parser . format_instruction )
+
+
+You should respond a json object in a json fenced code block as follows:
+
```json
+
{a list of numbers}
+
```
+
+
+
+Parse Function
+res = parser . parse (
+ ModelResponse (
+ text = """Yes, here is the generated list
+```json
+[1,2,3,4,5]
+```
+""" )
+)
+
+print ( type ( res ))
+print ( res )
+
+
+<class ‘list’>
+
[1, 2, 3, 4, 5]
+
+
+
+
+
+
+Typical Use Cases
+
+WereWolf Game
+Werewolf game is a classic use case of dictionary parser. In different stages of the game, the same agent needs to generate different identification fields in addition to "thought" "speak"
+AgentScope has built-in examples of werewolf game , which uses DictDialogAgent source code .
+
+
+
+
+Customized Parser
+AgentScope provides a base class ParserBase format_instruction parse
+For dictionary type parsing, you can also inherit the agentscope.parser.DictFilterMixin
+from abc import ABC , abstractmethod
+
+from agentscope.models import ModelResponse
+
+
+class ParserBase ( ABC ):
+ """The base class for model response parser."""
+
+ format_instruction : str
+ """The instruction for the response format."""
+
+ @abstractmethod
+ def parse ( self , response : ModelResponse ) -> ModelResponse :
+ """Parse the response text to a specific object, and stored in the
+ parsed field of the response object."""
+
+ # ...
+
+
+
+
+
+
+
+
+
+
+
Customizing Your Own Agent Pipeline and MsgHub Model Model Response Parser Service Memory Prompt Engineering Example
+Model Response Parser
+Service
Built-in Service Functions How to use Service Functions agentscope.agents.dict_dialog_agent 源代码
# -*- coding: utf-8 -*-
-"""A dict dialog agent that using `parse_func` and `fault_handler` to
-parse the model response."""
-import json
-from typing import Any , Optional , Callable
-from loguru import logger
+"""An agent that replies in a dictionary format."""
+from typing import Optional
from ..message import Msg
from .agent import AgentBase
-from ..models import ModelResponse
-from ..prompt import PromptType
-from ..utils.tools import _convert_to_str
-
-
-
-
[文档]
-
def parse_dict ( response : ModelResponse ) -> ModelResponse :
-
"""Parse function for DictDialogAgent"""
-
try :
-
if response . text is not None :
-
response_dict = json . loads ( response . text )
-
else :
-
raise ValueError (
-
f "The text field of the response s None: { response } " ,
-
)
-
except json . decoder . JSONDecodeError :
-
# Sometimes LLM may return a response with single quotes, which is not
-
# a valid JSON format. We replace single quotes with double quotes and
-
# try to load it again.
-
# TODO: maybe using a more robust json library to handle this case
-
response_dict = json . loads ( response . text . replace ( "'" , '"' ))
-
-
return ModelResponse ( raw = response_dict )
-
[文档]
-
def default_response ( response : ModelResponse ) -> ModelResponse :
-
"""The default response of fault_handler"""
-
return ModelResponse ( raw = { "speak" : response . text }) from ..parsers import ParserBase
[文档]
class DictDialogAgent ( AgentBase ):
"""An agent that generates response in a dict format, where user can
-
specify the required fields in the response via prompt, e.g.
-
-
.. code-block:: python
+
specify the required fields in the response via specifying the parser
-
prompt = "... Response in the following format that can be loaded by
-
python json.loads()
-
{
-
"thought": "thought",
-
"speak": "thoughts summary to say to others",
-
# ...
-
}"
-
-
This agent class is an example for using `parse_func` and `fault_handler`
-
to parse the output from the model, and handling the fault when parsing
-
fails. We take "speak" as a required field in the response, and print
-
the speak field as the output response.
+
About parser, please refer to our
+
[tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html)
For usage example, please refer to the example of werewolf in
`examples/game_werewolf`"""
@@ -175,10 +128,7 @@
agentscope.agents.dict_dialog_agent 源代码 model_config_name: str ,
use_memory : bool = True ,
memory_config : Optional [ dict ] = None ,
- parse_func : Optional [ Callable [ ... , Any ]] = parse_dict ,
- fault_handler : Optional [ Callable [ ... , Any ]] = default_response ,
max_retries : Optional [ int ] = 3 ,
- prompt_type : Optional [ PromptType ] = None ,
) -> None :
"""Initialize the dict dialog agent.
@@ -195,19 +145,9 @@ agentscope.agents.dict_dialog_agent 源代码 Whether the agent has memory.
memory_config (`Optional[dict]`, defaults to `None`):
The config of memory.
- parse_func (`Optional[Callable[..., Any]]`, defaults to `parse_dict`):
- The function used to parse the model output,
- e.g. `json.loads`, which is used to extract json from the
- output.
- fault_handler (`Optional[Callable[..., Any]]`, defaults to `default_response`):
- The function used to handle the fault when parse_func fails
- to parse the model output.
max_retries (`Optional[int]`, defaults to `None`):
The maximum number of retries when failed to parse the model
output.
- prompt_type (`Optional[PromptType]`, defaults to `PromptType.LIST`):
- The type of the prompt organization, chosen from
- `PromptType.LIST` or `PromptType.STRING`.
""" # noqa
super () . __init__ (
name = name ,
@@ -217,19 +157,21 @@ agentscope.agents.dict_dialog_agent 源代码 memory_config= memory_config ,
)
- # record the func and handler for parsing and handling faults
- self . parse_func = parse_func
- self . fault_handler = fault_handler
- self . max_retries = max_retries
+ self . parser = None
+ self . max_retries = max_retries if prompt_type is not None :
- logger . warning (
- "The argument `prompt_type` is deprecated and "
- "will be removed in the future." ,
- )
+
[文档]
+
def set_parser ( self , parser : ParserBase ) -> None :
+
"""Set response parser, which will provide 1) format instruction; 2)
+
response parsing; 3) filtering fields when returning message, storing
+
message in memory. So developers only need to change the
+
parser, and the agent will work as expected.
+
"""
+
self . parser = parser # TODO change typing from dict to MSG
[文档]
def reply ( self , x : dict = None ) -> dict :
@@ -264,43 +206,30 @@
agentscope.agents.dict_dialog_agent 源代码 self. memory
and self . memory . get_memory ()
or x , # type: ignore[arg-type]
+ Msg ( "system" , self . parser . format_instruction , "system" ),
)
# call llm
- response = self . model (
+ res = self . model (
prompt ,
- parse_func = self . parse_func ,
- fault_handler = self . fault_handler ,
+ parse_func = self . parser . parse ,
max_retries = self . max_retries ,
- ) . raw
-
- # logging raw messages in debug mode
- logger . debug ( json . dumps ( response , indent = 4 , ensure_ascii = False ))
-
- # In this agent, if the response is a dict, we treat "speak" as a
- # special key, which represents the text to be spoken
- if isinstance ( response , dict ) and "speak" in response :
- msg = Msg (
- self . name ,
- response [ "speak" ],
- role = "assistant" ,
- ** response ,
- )
- else :
- msg = Msg ( self . name , response , role = "assistant" )
-
- # Print/speak the message in this agent's voice
- self . speak ( msg )
+ )
- # record to memory
- if self . memory :
- # Convert the response dict into a string to store in memory
- msg_memory = Msg (
- name = self . name ,
- content = _convert_to_str ( response ),
- role = "assistant" ,
- )
- self . memory . add ( msg_memory )
+ # Filter the parsed response by keys for storing in memory, returning
+ # in the reply function, and feeding into the metadata field in the
+ # returned message object.
+ self . memory . add (
+ Msg ( self . name , self . parser . to_memory ( res . parsed ), "assistant" ),
+ )
+
+ msg = Msg (
+ self . name ,
+ content = self . parser . to_content ( res . parsed ),
+ role = "assistant" ,
+ metadata = self . parser . to_metadata ( res . parsed ),
+ )
+ self . speak ( msg )
return msg
diff --git a/zh_CN/_modules/agentscope/agents/react_agent.html b/zh_CN/_modules/agentscope/agents/react_agent.html
index ced8e7b4f..0ad34e8c6 100644
--- a/zh_CN/_modules/agentscope/agents/react_agent.html
+++ b/zh_CN/_modules/agentscope/agents/react_agent.html
@@ -240,6 +240,8 @@ agentscope.agents.react_agent 源代码
"function" : service_toolkit . tools_calling_format ,
},
required_keys = [ "thought" , "speak" , "function" ],
+ # Only print the speak field when verbose is False
+ keys_to_content = True if self . verbose else "speak" ,
) agentscope.agents.react_agent 源代码
"system" ,
self . parser . format_instruction ,
role = "system" ,
+ echo = self . verbose ,
)
- if self . verbose :
- self . speak ( hint_msg )
# Prepare prompt for the model
prompt = self . model . format ( self . memory . get_memory (), hint_msg )
@@ -278,16 +279,21 @@ agentscope.agents.react_agent 源代码
)
# Record the response in memory
- msg_response = Msg ( self . name , res . text , "assistant" )
- self . memory . add ( msg_response )
+ self . memory . add (
+ Msg (
+ self . name ,
+ self . parser . to_memory ( res . parsed ),
+ "assistant" ,
+ ),
+ )
# Print out the response
- if self . verbose :
- self . speak ( msg_response )
- else :
- self . speak (
- Msg ( self . name , res . parsed [ "speak" ], "assistant" ),
- )
+ msg_returned = Msg (
+ self . name ,
+ self . parser . to_content ( res . parsed ),
+ "assistant" ,
+ )
+ self . speak ( msg_returned )
# Skip the next steps if no need to call tools
# The parsed field is a dictionary
@@ -299,7 +305,7 @@ agentscope.agents.react_agent 源代码
and len ( arg_function ) == 0
):
# Only the speak field is exposed to users or other agents
- return Msg ( self . name , res . parsed [ "speak" ], "assistant" )
+ return msg_returned
# Only catch the response parsing error and expose runtime
# errors to developers for debugging
@@ -351,9 +357,8 @@ agentscope.agents.react_agent 源代码
"iterations. Now generate a reply by summarizing the current "
"situation." ,
role = "system" ,
+ echo = self . verbose ,
)
- if self . verbose :
- self . speak ( hint_msg )
# Generate a reply by summarizing the current situation
prompt = self . model . format ( self . memory . get_memory (), hint_msg )
diff --git a/zh_CN/_modules/agentscope/message.html b/zh_CN/_modules/agentscope/message.html
index f10123aaf..30767dc65 100644
--- a/zh_CN/_modules/agentscope/message.html
+++ b/zh_CN/_modules/agentscope/message.html
@@ -205,6 +205,28 @@ agentscope.message 源代码
class Msg ( MessageBase ):
"""The Message class."""
+ id : str
+ """The id of the message."""
+
+ name : str
+ """The name of who send the message."""
+
+ content : Any
+ """The content of the message."""
+
+ role : Literal [ "system" , "user" , "assistant" ]
+ """The role of the message sender."""
+
+ metadata : Optional [ dict ]
+ """Save the information for application's control flow, or other
+ purposes."""
+
+ url : Optional [ Union [ Sequence [ str ], str ]]
+ """A url to file, image, video, audio or website."""
+
+ timestamp : str
+ """The timestamp of the message."""
+
[文档]
def __init__ (
@@ -215,6 +237,7 @@
agentscope.message 源代码
url : Optional [ Union [ Sequence [ str ], str ]] = None ,
timestamp : Optional [ str ] = None ,
echo : bool = False ,
+ metadata : Optional [ Union [ dict , str ]] = None ,
** kwargs : Any ,
) -> None :
"""Initialize the message object
@@ -233,6 +256,11 @@ agentscope.message 源代码
timestamp (`Optional[str]`, defaults to `None`):
The timestamp of the message, if None, it will be set to
current time.
+ echo (`bool`, defaults to `False`):
+ Whether to print the message to the console.
+ metadata (`Optional[Union[dict, str]]`, defaults to `None`):
+ Save the information for application's control flow, or other
+ purposes.
**kwargs (`Any`):
Other attributes of the message.
"""
@@ -250,6 +278,7 @@ agentscope.message 源代码
role = role or "assistant" ,
url = url ,
timestamp = timestamp ,
+ metadata = metadata ,
** kwargs ,
)
if echo :
diff --git a/zh_CN/_modules/agentscope/parsers/code_block_parser.html b/zh_CN/_modules/agentscope/parsers/code_block_parser.html
index 39a248cdb..081334890 100644
--- a/zh_CN/_modules/agentscope/parsers/code_block_parser.html
+++ b/zh_CN/_modules/agentscope/parsers/code_block_parser.html
@@ -100,6 +100,8 @@
agentscope.parsers.code_block_parser 源代码
# -*- coding: utf-8 -*-
"""Model response parser class for Markdown code block."""
+from typing import Optional
+
from agentscope.models import ModelResponse
from agentscope.parsers import ParserBase
@@ -124,17 +126,40 @@ agentscope.parsers.code_block_parser 源代码 format_instruction: str = (
"You should generate {language_name} code in a {language_name} fenced "
"code block as follows: \n ``` {language_name} \n "
- "${{your_ {language_name} _code}} \n ```"
+ " {content_hint} \n ```"
)
"""The instruction for the format of the code block."""
[文档]
-
def __init__ ( self , language_name : str ) -> None :
+
def __init__ (
+
self ,
+
language_name : str ,
+
content_hint : Optional [ str ] = None ,
+
) -> None :
+
"""Initialize the parser with the language name and the optional
+
content hint.
+
+
Args:
+
language_name (`str`):
+
The name of the language, which will be used
+
in ```{language_name}
+
content_hint (`Optional[str]`, defaults to `None`):
+
The hint used to remind LLM what should be fill between the
+
tags. If not provided, the default content hint
+
"${{your_{language_name}_code}}" will be used.
+
"""
self . name = self . name . format ( language_name = language_name )
self . tag_begin = self . tag_begin . format ( language_name = language_name )
+
+
if content_hint is None :
+
self . content_hint = f "$ {{ your_ { language_name } _code }} "
+
else :
+
self . content_hint = content_hint
+
self . format_instruction = self . format_instruction . format (
language_name = language_name ,
+
content_hint = self . content_hint ,
) . strip ()
diff --git a/zh_CN/_modules/agentscope/parsers/json_object_parser.html b/zh_CN/_modules/agentscope/parsers/json_object_parser.html
index 519005805..34ea99845 100644
--- a/zh_CN/_modules/agentscope/parsers/json_object_parser.html
+++ b/zh_CN/_modules/agentscope/parsers/json_object_parser.html
@@ -102,7 +102,7 @@
agentscope.parsers.json_object_parser 源代码 <
"""The parser for JSON object in the model response."""
import json
from copy import deepcopy
-
from typing import Optional , Any , List
+
from typing import Optional , Any , List , Sequence , Union
from loguru import logger
@@ -114,6 +114,7 @@
agentscope.parsers.json_object_parser 源代码 <
)
from agentscope.models import ModelResponse
from agentscope.parsers import ParserBase
+
from agentscope.parsers.parser_base import DictFilterMixin
from agentscope.utils.tools import _join_str_with_comma_and
@@ -232,7 +233,7 @@
agentscope.parsers.json_object_parser 源代码 <
[文档]
-
class MarkdownJsonDictParser ( MarkdownJsonObjectParser ):
+
class MarkdownJsonDictParser ( MarkdownJsonObjectParser , DictFilterMixin ):
"""A class used to parse a JSON dictionary object in a markdown fenced
code"""
@@ -265,6 +266,9 @@
agentscope.parsers.json_object_parser 源代码 <
self ,
content_hint : Optional [ Any ] = None ,
required_keys : List [ str ] = None ,
+
keys_to_memory : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_content : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_metadata : Optional [ Union [ str , bool , Sequence [ str ]]] = False ,
) -> None :
"""Initialize the parser with the content hint.
@@ -278,8 +282,42 @@
agentscope.parsers.json_object_parser 源代码 <
A list of required keys in the JSON dictionary object. If the
response misses any of the required keys, it will raise a
RequiredFieldNotFoundError.
+ keys_to_memory (`Optional[Union[str, bool, Sequence[str]]]`,
+ defaults to `True`):
+ The key or keys to be filtered in `to_memory` method. If
+ it's
+ - `False`, `None` will be returned in the `to_memory` method
+ - `str`, the corresponding value will be returned
+ - `List[str]`, a filtered dictionary will be returned
+ - `True`, the whole dictionary will be returned
+ keys_to_content (`Optional[Union[str, bool, Sequence[str]]`,
+ defaults to `True`):
+ The key or keys to be filtered in `to_content` method. If
+ it's
+ - `False`, `None` will be returned in the `to_content` method
+ - `str`, the corresponding value will be returned
+ - `List[str]`, a filtered dictionary will be returned
+ - `True`, the whole dictionary will be returned
+ keys_to_metadata (`Optional[Union[str, bool, Sequence[str]]`,
+ defaults to `False`):
+ The key or keys to be filtered in `to_metadata` method. If
+ it's
+ - `False`, `None` will be returned in the `to_metadata` method
+ - `str`, the corresponding value will be returned
+ - `List[str]`, a filtered dictionary will be returned
+ - `True`, the whole dictionary will be returned
+
"""
- super () . __init__ ( content_hint )
+ # Initialize the markdown json object parser
+ MarkdownJsonObjectParser . __init__ ( self , content_hint )
+
+ # Initialize the mixin class to allow filtering the parsed response
+ DictFilterMixin . __init__ (
+ self ,
+ keys_to_memory = keys_to_memory ,
+ keys_to_content = keys_to_content ,
+ keys_to_metadata = keys_to_metadata ,
+ )
self . required_keys = required_keys or []
diff --git a/zh_CN/_modules/agentscope/parsers/parser_base.html b/zh_CN/_modules/agentscope/parsers/parser_base.html
index a6e02b859..e3be2d59d 100644
--- a/zh_CN/_modules/agentscope/parsers/parser_base.html
+++ b/zh_CN/_modules/agentscope/parsers/parser_base.html
@@ -101,10 +101,17 @@
agentscope.parsers.parser_base 源代码
# -*- coding: utf-8 -*-
"""The base class for model response parser."""
from abc import ABC , abstractmethod
+from typing import Union , Sequence
+
+from loguru import logger
from agentscope.exception import TagNotFoundError
from agentscope.models import ModelResponse
+# TODO: Support one-time warning in logger rather than setting global variable
+_FIRST_TIME_TO_REPORT_CONTENT = True
+_FIRST_TIME_TO_REPORT_MEMORY = True
+
[文档]
@@ -159,7 +166,7 @@
agentscope.parsers.parser_base 源代码
raise TagNotFoundError (
f "Missing "
f "tag { '' if len ( missing_tags ) == 1 else 's' } "
- f " { ' and ' . join ( missing_tags ) } in response." ,
+ f " { ' and ' . join ( missing_tags ) } in response: { text } " ,
raw_response = text ,
missing_begin_tag = index_start == - 1 ,
missing_end_tag = index_end == - 1 ,
@@ -171,6 +178,155 @@ agentscope.parsers.parser_base 源代码
+
+
+
+
[文档]
+
class DictFilterMixin :
+
"""A mixin class to filter the parsed response by keys. It allows users
+
to set keys to be filtered during speaking, storing in memory, and
+
returning in the agent reply function.
+
"""
+
+
+
[文档]
+
def __init__ (
+
self ,
+
keys_to_memory : Union [ str , bool , Sequence [ str ]],
+
keys_to_content : Union [ str , bool , Sequence [ str ]],
+
keys_to_metadata : Union [ str , bool , Sequence [ str ]],
+
) -> None :
+
"""Initialize the mixin class with the keys to be filtered during
+
speaking, storing in memory, and returning in the agent reply function.
+
+
Args:
+
keys_to_memory (`Optional[Union[str, bool, Sequence[str]]]`):
+
The key or keys to be filtered in `to_memory` method. If
+
it's
+
- `False`, `None` will be returned in the `to_memory` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_content (`Optional[Union[str, bool, Sequence[str]]`):
+
The key or keys to be filtered in `to_content` method. If
+
it's
+
- `False`, `None` will be returned in the `to_content` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_metadata (`Optional[Union[str, bool, Sequence[str]]]`):
+
The key or keys to be filtered in `to_metadata` method. If
+
it's
+
- `False`, `None` will be returned in the `to_metadata` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
"""
+
self . keys_to_memory = keys_to_memory
+
self . keys_to_content = keys_to_content
+
self . keys_to_metadata = keys_to_metadata
+
+
+
+
[文档]
+
def to_memory (
+
self ,
+
parsed_response : dict ,
+
allow_missing : bool = False ,
+
) -> Union [ str , dict , None ]:
+
"""Filter the fields that will be stored in memory."""
+
return self . _filter_content_by_names (
+
parsed_response ,
+
self . keys_to_memory ,
+
allow_missing = allow_missing ,
+
)
+
+
+
+
[文档]
+
def to_content (
+
self ,
+
parsed_response : dict ,
+
allow_missing : bool = False ,
+
) -> Union [ str , dict , None ]:
+
"""Filter the fields that will be fed into the content field in the
+
returned message, which will be exposed to other agents.
+
"""
+
return self . _filter_content_by_names (
+
parsed_response ,
+
self . keys_to_content ,
+
allow_missing = allow_missing ,
+
)
+
+
+
+
+
+
def _filter_content_by_names (
+
self ,
+
parsed_response : dict ,
+
keys : Union [ str , bool , Sequence [ str ]],
+
allow_missing : bool = False ,
+
) -> Union [ str , dict , None ]:
+
"""Filter the parsed response by keys. If only one key is provided, the
+
returned content will be a single corresponding value. Otherwise,
+
the returned content will be a dictionary with the filtered keys and
+
their corresponding values.
+
+
Args:
+
keys (`Union[str, bool, Sequence[str]]`):
+
The key or keys to be filtered. If it's
+
- `False`, `None` will be returned in the `to_content` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
allow_missing (`bool`, defaults to `False`):
+
Whether to allow missing keys in the response. If set to
+
`True`, the method will skip the missing keys in the response.
+
Otherwise, it will raise a `ValueError` when a key is missing.
+
+
Returns:
+
`Union[str, dict]`: The filtered content.
+
"""
+
+
if isinstance ( keys , bool ):
+
if keys :
+
return parsed_response
+
else :
+
return None
+
+
if isinstance ( keys , str ):
+
return parsed_response [ keys ]
+
+
# check if the required names are in the response
+
for name in keys :
+
if name not in parsed_response :
+
if allow_missing :
+
logger . warning (
+
f "Content name { name } not found in the response. Skip "
+
f "it." ,
+
)
+
else :
+
raise ValueError ( f "Name { name } not found in the response." )
+
return {
+
name : parsed_response [ name ]
+
for name in keys
+
if name in parsed_response
+
}
diff --git a/zh_CN/_modules/agentscope/parsers/tagged_content_parser.html b/zh_CN/_modules/agentscope/parsers/tagged_content_parser.html
index 1787287cd..335706908 100644
--- a/zh_CN/_modules/agentscope/parsers/tagged_content_parser.html
+++ b/zh_CN/_modules/agentscope/parsers/tagged_content_parser.html
@@ -101,10 +101,12 @@ agentscope.parsers.tagged_content_parser 源代码 # -*- coding: utf-8 -*-
"""The parser for tagged content in the model response."""
import json
+
from typing import Union , Sequence , Optional , List
-
from agentscope.exception import JsonParsingError
+
from agentscope.exception import JsonParsingError , TagNotFoundError
from agentscope.models import ModelResponse
from agentscope.parsers import ParserBase
+
from agentscope.parsers.parser_base import DictFilterMixin
@@ -114,7 +116,8 @@
agentscope.parsers.tagged_content_parser 源代码 and tag end."""
name : str
-
"""The name of the tagged content."""
+
"""The name of the tagged content, which will be used as the key in
+
extracted dictionary."""
tag_begin : str
"""The beginning tag."""
@@ -168,7 +171,7 @@
agentscope.parsers.tagged_content_parser 源代码
[文档]
-
class MultiTaggedContentParser ( ParserBase ):
+
class MultiTaggedContentParser ( ParserBase , DictFilterMixin ):
"""Parse response text by multiple tags, and return a dict of their
content. Asking llm to generate JSON dictionary object directly maybe not a
good idea due to involving escape characters and other issues. So we can
@@ -189,14 +192,60 @@
agentscope.parsers.tagged_content_parser 源代码
[文档]
-
def __init__ ( self , * tagged_contents : TaggedContent ) -> None :
+
def __init__ (
+
self ,
+
* tagged_contents : TaggedContent ,
+
keys_to_memory : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_content : Optional [ Union [ str , bool , Sequence [ str ]]] = True ,
+
keys_to_metadata : Optional [ Union [ str , bool , Sequence [ str ]]] = False ,
+
keys_allow_missing : Optional [ List [ str ]] = None ,
+
) -> None :
"""Initialize the parser with tags.
Args:
-
tags (`dict[str, Tuple[str, str]]`):
-
A dictionary of tags, the key is the tag name, and the value is
-
a tuple of starting tag and end tag.
+
*tagged_contents (`dict[str, Tuple[str, str]]`):
+
Multiple TaggedContent objects, each object contains the tag
+
name, tag begin, content hint and tag end. The name will be
+
used as the key in the extracted dictionary.
+
required_keys (`Optional[List[str]]`, defaults to `None`):
+
A list of required
+
keys_to_memory (`Optional[Union[str, bool, Sequence[str]]]`,
+
defaults to `True`):
+
The key or keys to be filtered in `to_memory` method. If
+
it's
+
- `False`, `None` will be returned in the `to_memory` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_content (`Optional[Union[str, bool, Sequence[str]]`,
+
defaults to `True`):
+
The key or keys to be filtered in `to_content` method. If
+
it's
+
- `False`, `None` will be returned in the `to_content` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_to_metadata (`Optional[Union[str, bool, Sequence[str]]]`,
+
defaults to `False`):
+
The key or keys to be filtered in `to_metadata` method. If
+
it's
+
- `False`, `None` will be returned in the `to_metadata` method
+
- `str`, the corresponding value will be returned
+
- `List[str]`, a filtered dictionary will be returned
+
- `True`, the whole dictionary will be returned
+
keys_allow_missing (`Optional[List[str]]`, defaults to `None`):
+
A list of keys that are allowed to be missing in the response.
"""
+
# Initialize the mixin class
+
DictFilterMixin . __init__ (
+
self ,
+
keys_to_memory = keys_to_memory ,
+
keys_to_content = keys_to_content ,
+
keys_to_metadata = keys_to_metadata ,
+
)
+
+
self . keys_allow_missing = keys_allow_missing
+
self . tagged_contents = list ( tagged_contents )
# Prepare the format instruction according to the tagged contents
@@ -236,26 +285,38 @@
agentscope.parsers.tagged_content_parser 源代码 tag_begin = tagged_content . tag_begin
tag_end = tagged_content . tag_end
- extract_content = self . _extract_first_content_by_tag (
- response ,
- tag_begin ,
- tag_end ,
- )
-
- if tagged_content . parse_json :
- try :
- extract_content = json . loads ( extract_content )
- except json . decoder . JSONDecodeError as e :
- raw_response = f " { tag_begin }{ extract_content }{ tag_end } "
- raise JsonParsingError (
- f "The content between { tagged_content . tag_begin } and "
- f " { tagged_content . tag_end } should be a JSON object."
- f 'When parsing " { raw_response } ", an error occurred: '
- f " { e } " ,
- raw_response = raw_response ,
- ) from None
-
- tag_to_content [ tagged_content . name ] = extract_content
+ try :
+ extract_content = self . _extract_first_content_by_tag (
+ response ,
+ tag_begin ,
+ tag_end ,
+ )
+
+ if tagged_content . parse_json :
+ try :
+ extract_content = json . loads ( extract_content )
+ except json . decoder . JSONDecodeError as e :
+ raw_response = f " { tag_begin }{ extract_content }{ tag_end } "
+ raise JsonParsingError (
+ f "The content between "
+ f " { tagged_content . tag_begin } and "
+ f " { tagged_content . tag_end } should be a JSON "
+ f 'object. An error " { e } " occurred when parsing: '
+ f " { raw_response } " ,
+ raw_response = raw_response ,
+ ) from None
+
+ tag_to_content [ tagged_content . name ] = extract_content
+
+ except TagNotFoundError as e :
+ # if the key is allowed to be missing, skip the error
+ if (
+ self . keys_allow_missing is not None
+ and tagged_content . name in self . keys_allow_missing
+ ):
+ continue
+
+ raise e from None
response . parsed = tag_to_content
return response
diff --git a/zh_CN/_sources/tutorial/203-parser.md.txt b/zh_CN/_sources/tutorial/203-parser.md.txt
new file mode 100644
index 000000000..a8b2a30fb
--- /dev/null
+++ b/zh_CN/_sources/tutorial/203-parser.md.txt
@@ -0,0 +1,476 @@
+(203-parser-zh)=
+
+# 模型结果解析
+
+## 目录
+
+- [背景](#背景)
+- [解析器模块](#解析器模块)
+ - [功能说明](#功能说明)
+ - [字符串类型](#字符串str类型)
+ - [MarkdownCodeBlockParser](#markdowncodeblockparser)
+ - [初始化](#初始化)
+ - [响应格式模版](#响应格式模版)
+ - [解析函数](#解析函数)
+ - [字典类型](#字典dict类型)
+ - [MarkdownJsonDictParser](#markdownjsondictparser)
+ - [初始化 & 响应格式模版](#初始化--响应格式模版)
+ - [MultiTaggedContentParser](#multitaggedcontentparser)
+ - [初始化 & 响应格式模版](#初始化--响应格式模版-1)
+ - [解析函数](#解析函数-1)
+ - [JSON / Python 对象类型](#json--python-对象类型)
+ - [MarkdownJsonObjectParser](#markdownjsonobjectparser)
+ - [初始化 & 响应格式模版](#初始化--响应格式模版-2)
+ - [解析函数](#解析函数-2)
+- [典型使用样例](#典型使用样例)
+ - [狼人杀游戏](#狼人杀游戏)
+ - [ReAct 智能体和工具使用](#react-智能体和工具使用)
+- [自定义解析器](#自定义解析器)
+
+
+## 背景
+
+利用LLM构建应用的过程中，将 LLM 产生的字符串解析成指定的格式，提取出需要的信息，是一个非常重要的环节。
+但同时由于下列原因，这个过程也是一个非常复杂的过程：
+
+1. **多样性**：解析的目标格式多种多样，需要提取的信息可能是一段特定文本，一个JSON对象，或者是一个复杂的数据结构。
+2. **复杂性**：结果解析不仅仅是将 LLM 产生的文本转换成目标格式，还涉及到提示工程（提醒 LLM 应该产生什么格式的输出），错误处理等一些列问题。
+3. **灵活性**：同一个应用中，不同阶段也可能需要智能体产生不同格式的输出。
+
+为了让开发者能够便捷、灵活的地进行结果解析，AgentScope设计并提供了解析器模块（Parser）。利用该模块，开发者可以通过简单的配置，实现目标格式的解析，同时可以灵活的切换解析的目标格式。
+
+AgentScope中，解析器模块的设计原则是：
+1. **灵活**：开发者可以灵活设置所需返回格式、灵活地切换解析器，实现不同格式的解析，而无需修改智能体类的代码，即具体的“目标格式”与智能体类内`reply`函数的处理逻辑解耦
+2. **自由**：用户可以自由选择是否使用解析器。解析器所提供的响应格式提示、解析结果等功能都是在`reply`函数内显式调用的，用户可以自由选择使用解析器或是自己实现代码实现结果解析
+3. **透明**：利用解析器时，提示（prompt）构建的过程和结果在`reply`函数内对开发者完全可见且透明，开发者可以精确调试自己的应用。
+
+## 解析器模块
+
+### 功能说明
+
+解析器模块（Parser）的主要功能包括：
+
+1. 提供“响应格式说明”（format instruction），即提示 LLM 应该在什么位置产生什么输出，例如
+
+> You should generate python code in a fenced code block as follows
+>
+> \```python
+>
+> {your_python_code}
+>
+> \```
+
+
+2. 提供解析函数（parse function），直接将 LLM 产生的文本解析成目标数据格式
+
+3. 针对字典格式的后处理功能。在将文本解析成字典后，其中不同的字段可能有不同的用处
+
+AgentScope提供了多种不同解析器，开发者可以根据自己的需求进行选择。
+
+| 目标格式 | 解析器 | 说明 |
+|-------------------|----------------------------|-----------------------------------------------------------------------------|
+| 字符串(`str`)类型 | `MarkdownCodeBlockParser` | 要求 LLM 将指定的文本生成到Markdown中以 ``` 标识的代码块中，解析结果为字符串。 |
+| 字典(`dict`)类型 | `MarkdownJsonDictParser` | 要求 LLM 在 \```json 和 \``` 标识的代码块中产生指定内容的字典，解析结果为 Python 字典。 |
+| | `MultiTaggedContentParser` | 要求 LLM 在多个标签中产生指定内容，这些不同标签中的内容将一同被解析成一个 Python 字典，并填入不同的键值对中。 |
+| JSON / Python对象类型 | `MarkdownJsonObjectParser` | 要求 LLM 在 \```json 和 \``` 标识的代码块中产生指定的内容，解析结果将通过 `json.loads` 转换成 Python 对象。 |
+
+> **NOTE**: 相比`MarkdownJsonDictParser`，`MultiTaggedContentParser`更适合于模型能力不强，以及需要 LLM 返回内容过于复杂的情况。例如 LLM 返回 Python 代码，如果直接在字典中返回代码，那么 LLM 需要注意特殊字符的转义（\t,\n,...），`json.loads`读取时对双引号和单引号的区分等问题。而`MultiTaggedContentParser`实际是让大模型在每个单独的标签中返回各个键值，然后再将它们组成字典，从而降低了LLM返回的难度。
+
+下面我们将根据不同的目标格式，介绍这些解析器的用法。
+
+### 字符串（`str`）类型
+
+
+
+ MarkdownCodeBlockParser
+
+##### 初始化
+
+- `MarkdownCodeBlockParser`采用 Markdown 代码块的形式，要求 LLM 将指定文本产生到指定的代码块中。可以通过`language_name`参数指定不同的语言，从而利用大模型代码能力产生对应的输出。例如要求大模型产生 Python 代码时，初始化如下：
+
+ ```python
+ from agentscope.parsers import MarkdownCodeBlockParser
+
+ parser = MarkdownCodeBlockParser(language_name="python")
+ ```
+
+##### 响应格式模版
+
+- `MarkdownCodeBlockParser`类提供如下的“响应格式说明”模版，在用户调用`format_instruction`属性时，会将`{language_name}`替换为初始化时输入的字符串：
+
+ > You should generate {language_name} code in a {language_name} fenced code block as follows:
+ >
+ > \```{language_name}
+ >
+ > ${your_{language_name}_code}
+ >
+ > \```
+
+- 例如上述对`language_name`为`"python"`的初始化，调用`format_instruction`属性时，会返回如下字符串：
+
+ ```python
+ print(parser.format_instruction)
+ ```
+
+ > You should generate python code in a python fenced code block as follows
+ >
+ > \```python
+ >
+ > ${your_python_code}
+ >
+ > \```
+
+##### 解析函数
+
+- `MarkdownCodeBlockParser`类提供`parse`方法，用于解析LLM产生的文本，返回的是字符串。
+
+ ````python
+ res = parser.parse(
+ ModelResponse(
+ text="""The following is generated python code
+ ```python
+ print("Hello world!")
+ ```
+ """
+ )
+ )
+
+ print(res.parsed)
+ ````
+
+ > print("hello world!")
+
+
+
+### 字典（`dict`）类型
+
+与字符串和一般的 JSON / Python 对象不同，作为LLM应用中常用的数据格式，AgentScope为字典类型提供了额外的后处理功能。初始化解析器时，可以通过额外设置`keys_to_content`，`keys_to_memory`，`keys_to_metadata`三个参数，从而实现在调用`parser`的`to_content`，`to_memory`和`to_metadata`方法时，对字典键值对的过滤。
+其中
+ - `keys_to_content` 指定的键值对将被放置在返回`Msg`对象中的`content`字段，这个字段内容将会被返回给其它智能体，参与到其他智能体的提示构建中，同时也会被`self.speak`函数调用，用于显式输出
+ - `keys_to_memory` 指定的键值对将被存储到智能体的记忆中
+ - `keys_to_metadata` 指定的键值对将被放置在`Msg`对象的`metadata`字段，可以用于应用的控制流程判断，或挂载一些不需要返回给其它智能体的信息。
+
+三个参数接收布尔值、字符串和字符串列表。其值的含义如下：
+- `False`: 对应的过滤函数将返回`None`。
+- `True`: 整个字典将被返回。
+- `str`: 对应的键值将被直接返回，注意返回的会是对应的值而非字典。
+- `List[str]`: 根据键值对列表返回过滤后的字典。
+
+AgentScope中，`keys_to_content` 和 `keys_to_memory` 默认为 `True`，即整个字典将被返回。`keys_to_metadata` 默认为 `False`，即对应的过滤函数将返回 `None`。
+
+下面是狼人杀游戏的样例，在白天讨论过程中 LLM 扮演狼人产生的字典。在这个例子中，
+- `"thought"`字段不应该返回给其它智能体，但是应该存储在智能体的记忆中，从而保证狼人策略的延续；
+- `"speak"`字段应该被返回给其它智能体，并且存储在智能体记忆中；
+- `"finish_discussion"`字段用于应用的控制流程中，判断讨论是否已经结束。为了节省token，该字段不应该被返回给其它的智能体，同时也不应该存储在智能体的记忆中。
+
+ ```python
+ {
+ "thought": "The others didn't realize I was a werewolf. I should end the discussion soon.",
+ "speak": "I agree with you.",
+ "finish_discussion": True
+ }
+ ```
+
+AgentScope中，我们通过调用`to_content`，`to_memory`和`to_metadata`方法实现后处理功能，示意代码如下：
+
+- 应用中的控制流代码，创建对应的解析器对象并装载
+
+ ```python
+ from agentscope.parsers import MarkdownJsonDictParser
+
+ # ...
+
+ agent = DictDialogAgent(...)
+
+ # 以MarkdownJsonDictParser为例
+ parser = MarkdownJsonDictParser(
+ content_hint={
+ "thought": "what you thought",
+ "speak": "what you speak",
+ "finish_discussion": "whether the discussion is finished"
+ },
+ keys_to_content="speak",
+ keys_to_memory=["thought", "speak"],
+ keys_to_metadata=["finish_discussion"]
+ )
+
+ # 装载解析器，即相当于指定了要求的相应格式
+ agent.set_parser(parser)
+
+ # 讨论过程
+ while True:
+ # ...
+ x = agent(x)
+ # 根据metadata字段，获取LLM对当前是否应该结束讨论的判断
+ if x.metadata["finish_discussion"]:
+ break
+ ```
+
+
+- 智能体内部`reply`函数内实现字典的过滤
+
+ ```python
+ # ...
+ def reply(x: dict = None) -> None:
+
+ # ...
+ res = self.model(prompt, parse_func=self.parser.parse)
+
+ # 过滤后拥有 thought 和 speak 字段的字典，存储到智能体记忆中
+ self.memory.add(
+ Msg(
+ self.name,
+ content=self.parser.to_memory(res.parsed),
+ role="assistant",
+ )
+ )
+
+ # 存储到content中，同时存储到metadata中
+ msg = Msg(
+ self.name,
+ content=self.parser.to_content(res.parsed),
+ role="assistant",
+ metadata=self.parser.to_metadata(res.parsed),
+ )
+ self.speak(msg)
+
+ return msg
+ ```
+
+
+
+
+> **Note**: `keys_to_content`，`keys_to_memory`和`keys_to_metadata`参数可以是列表，字符串，也可以是布尔值。
+> - 如果是`True`，则会直接返回整个字典，即不进行过滤
+> - 如果是`False`，则会直接返回`None`值
+> - 如果是字符串类型，则`to_content`，`to_memory`和`to_metadata`方法将会把字符串对应的键值直接放入到对应的位置，例如`keys_to_content="speak"`，则`to_content`方法将会把`res.parsed["speak"]`放入到`Msg`对象的`content`字段中，`content`字段会是字符串而不是字典。
+> - 如果是列表类型，则`to_content`，`to_memory`和`to_metadata`方法实现的将是过滤功能，对应过滤后的结果是字典
+> ```python
+> parser = MarkdownJsonDictParser(
+> content_hint={
+> "thought": "what you thought",
+> "speak": "what you speak",
+> },
+> keys_to_content="speak",
+> keys_to_memory=["thought", "speak"],
+> )
+>
+> example_dict = {"thought": "abc", "speak": "def"}
+> print(parser.to_content(example_dict)) # def
+> print(parser.to_memory(example_dict)) # {"thought": "abc", "speak": "def"}
+> print(parser.to_metadata(example_dict)) # None
+> ```
+> > def
+> >
+> > {"thought": "abc", "speak": "def"}
+> >
+> > None
+
+下面我们具体介绍两种字典类型的解析器。
+
+
+
+ MarkdownJsonDictParser
+
+##### 初始化 & 响应格式模版
+
+- `MarkdownJsonDictParser`要求 LLM 在 \```json 和 \``` 标识的代码块中产生指定内容的字典。
+- 除了`to_content`，`to_memory`和`to_metadata`参数外，可以通过提供 `content_hint` 参数提供响应结果样例和说明，即提示LLM应该产生什么样子的字典，该参数可以是字符串，也可以是字典，在构建响应格式提示的时候将会被自动转换成字符串进行拼接。
+
+ ```python
+ from agentscope.parsers import MarkdownJsonDictParser
+
+ # 字典
+ MarkdownJsonDictParser(
+ content_hint={
+ "thought": "what you thought",
+ "speak": "what you speak",
+ }
+ )
+ # 或字符串
+ MarkdownJsonDictParser(
+ content_hint="""{
+ "thought": "what you thought",
+ "speak": "what you speak",
+ }"""
+ )
+ ```
+ - 对应的`instruction_format`属性
+
+ > You should respond a json object in a json fenced code block as follows:
+ >
+ > \```json
+ >
+ > {content_hint}
+ >
+ > \```
+
+
+
+
+
+ MultiTaggedContentParser
+
+`MultiTaggedContentParser`要求 LLM 在多个指定的标签对中产生指定的内容，这些不同标签的内容将一同被解析为一个 Python 字典。使用方法与`MarkdownJsonDictParser`类似，只是初始化方法不同，更适合能力较弱的LLM，或是比较复杂的返回内容。
+
+##### 初始化 & 响应格式模版
+
+`MultiTaggedContentParser`中，每一组标签将会以`TaggedContent`对象的形式传入，其中`TaggedContent`对象包含了
+- 标签名（`name`），即返回字典中的key值
+- 开始标签（`tag_begin`）
+- 标签内容提示（`content_hint`）
+- 结束标签（`tag_end`)
+- 内容解析功能（`parse_json`），默认为`False`。当置为`True`时，将在响应格式提示中自动添加提示，并且提取出的内容将通过`json.loads`解析成 Python 对象
+
+```python
+from agentscope.parsers import MultiTaggedContentParser, TaggedContent
+parser = MultiTaggedContentParser(
+ TaggedContent(
+ name="thought",
+ tag_begin="[THOUGHT]",
+ content_hint="what you thought",
+ tag_end="[/THOUGHT]"
+ ),
+ TaggedContent(
+ name="speak",
+ tag_begin="[SPEAK]",
+ content_hint="what you speak",
+ tag_end="[/SPEAK]"
+ ),
+ TaggedContent(
+ name="finish_discussion",
+ tag_begin="[FINISH_DISCUSSION]",
+ content_hint="true/false, whether the discussion is finished",
+ tag_end="[/FINISH_DISCUSSION]",
+ parse_json=True, # 我们希望这个字段的内容直接被解析成 True 或 False 的 Python 布尔值
+ )
+)
+
+print(parser.format_instruction)
+```
+
+> Respond with specific tags as outlined below, and the content between [FINISH_DISCUSSION] and [/FINISH_DISCUSSION] MUST be a JSON object:
+>
+> [THOUGHT]what you thought[/THOUGHT]
+>
+> [SPEAK]what you speak[/SPEAK]
+>
+> [FINISH_DISCUSSION]true/false, whether the discussion is finished[/FINISH_DISCUSSION]
+
+##### 解析函数
+
+- `MultiTaggedContentParser`的解析结果为字典，其中key为`TaggedContent`对象的`name`的值，以下是狼人杀中解析 LLM 返回的样例：
+
+```python
+res_dict = parser.parse(
+ ModelResponse(text="""As a werewolf, I should keep pretending to be a villager
+[THOUGHT]The others didn't realize I was a werewolf. I should end the discussion soon.[/THOUGHT]
+[SPEAK]I agree with you.[/SPEAK]
+[FINISH_DISCUSSION]true[/FINISH_DISCUSSION]
+"""
+ )
+)
+
+print(res_dict)
+```
+
+> {
+>
+> "thought": "The others didn't realize I was a werewolf. I should end the discussion soon.",
+>
+> "speak": "I agree with you.",
+>
+> "finish_discussion": true
+>
+> }
+
+
+
+### JSON / Python 对象类型
+
+
+
+ MarkdownJsonObjectParser
+
+`MarkdownJsonObjectParser`同样采用 Markdown 的\```json和\```标识，但是不限制解析的内容的类型，可以是列表，字典，数值，字符串等可以通过`json.loads`进行解析字符串。
+
+##### 初始化 & 响应格式模版
+
+```python
+from agentscope.parsers import MarkdownJsonObjectParser
+
+parser = MarkdownJsonObjectParser(
+ content_hint="{A list of numbers.}"
+)
+
+print(parser.format_instruction)
+```
+
+> You should respond a json object in a json fenced code block as follows:
+>
+> \```json
+>
+> {a list of numbers}
+>
+> \```
+
+##### 解析函数
+
+````python
+res = parser.parse(
+ ModelResponse(text="""Yes, here is the generated list
+```json
+[1,2,3,4,5]
+```
+"""
+ )
+)
+
+print(type(res))
+print(res)
+````
+>
+>
+> [1, 2, 3, 4, 5]
+
+
+
+## 典型使用样例
+
+### 狼人杀游戏
+
+狼人杀（Werewolf）是字典解析器的一个经典使用场景，在游戏的不同阶段内，需要同一个智能体在不同阶段产生除了`"thought"`和`"speak"`外其它的标识字段，例如是否结束讨论，预言家是否使用能力，女巫是否使用解药和毒药，投票等。
+
+AgentScope中已经内置了[狼人杀](https://github.com/modelscope/agentscope/tree/main/examples/game_werewolf)的样例，该样例采用`DictDialogAgent`类，配合不同的解析器，实现了灵活的目标格式切换。同时利用解析器的后处理功能，实现了“想”与“说”的分离，同时控制游戏流程的推进。
+详细实现请参考狼人杀[源码](https://github.com/modelscope/agentscope/tree/main/examples/game_werewolf)。
+
+### ReAct 智能体和工具使用
+
+`ReActAgent`是AgentScope中为了工具使用构建的智能体类，基于 ReAct 算法进行搭建，可以配合不同的工具函数进行使用。其中工具的调用，格式解析，采用了和解析器同样的实现思路。详细实现请参考[代码](https://github.com/modelscope/agentscope/blob/main/src/agentscope/agents/react_agent.py)。
+
+
+## 自定义解析器
+
+AgentScope中提供了解析器的基类`ParserBase`，开发者可以通过继承该基类，并实现其中的`format_instruction`属性和`parse`方法来实现自己的解析器。
+
+针对目标格式是字典类型的解析，可以额外继承`agentscope.parser.DictFilterMixin`类实现对字典类型的后处理。
+
+```python
+from abc import ABC, abstractmethod
+
+from agentscope.models import ModelResponse
+
+
+class ParserBase(ABC):
+ """The base class for model response parser."""
+
+ format_instruction: str
+ """The instruction for the response format."""
+
+ @abstractmethod
+ def parse(self, response: ModelResponse) -> ModelResponse:
+ """Parse the response text to a specific object, and stored in the
+ parsed field of the response object."""
+
+ # ...
+```
diff --git a/zh_CN/_sources/tutorial/advance.rst.txt b/zh_CN/_sources/tutorial/advance.rst.txt
index 9de74f5cd..17ab3d8c8 100644
--- a/zh_CN/_sources/tutorial/advance.rst.txt
+++ b/zh_CN/_sources/tutorial/advance.rst.txt
@@ -7,6 +7,7 @@
201-agent.md
202-pipeline.md
203-model.md
+ 203-parser.md
204-service.md
205-memory.md
206-prompt.md
diff --git a/zh_CN/agentscope.agents.dict_dialog_agent.html b/zh_CN/agentscope.agents.dict_dialog_agent.html
index c7baaaa19..2e3eb875f 100644
--- a/zh_CN/agentscope.agents.dict_dialog_agent.html
+++ b/zh_CN/agentscope.agents.dict_dialog_agent.html
@@ -98,44 +98,20 @@
agentscope.agents.dict_dialog_agent
-A dict dialog agent that using parse_func and fault_handler to
-parse the model response.
-
-
-agentscope.agents.dict_dialog_agent. parse_dict ( response : ModelResponse ) → ModelResponse [源代码]
-Parse function for DictDialogAgent
-
-
-
-
-agentscope.agents.dict_dialog_agent. default_response ( response : ModelResponse ) → ModelResponse [源代码]
-The default response of fault_handler
-
-
+An agent that replies in a dictionary format.
class agentscope.agents.dict_dialog_agent. DictDialogAgent ( * args : tuple ** kwargs : dict ) [源代码]
基类：AgentBase
An agent that generates response in a dict format, where user can
-specify the required fields in the response via prompt, e.g.
-prompt = "... Response in the following format that can be loaded by
-python json . loads ()
-{
- "thought" : "thought" ,
- "speak" : "thoughts summary to say to others" ,
- # ...
-} "
-
-
This agent class is an example for using parse_func and fault_handler
-to parse the output from the model, and handling the fault when parsing
-fails. We take “speak” as a required field in the response, and print
-the speak field as the output response.
+specify the required fields in the response via specifying the parser
+About parser, please refer to our
+[tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html )
For usage example, please refer to the example of werewolf in
examples/game_werewolf
-__init__ ( name: str, sys_prompt: str, model_config_name: str, use_memory: bool = True, memory_config: dict | None = None, parse_func: ~typing.Callable[[...], ~typing.Any] | None = <function parse_dict>, fault_handler: ~typing.Callable[[...], ~typing.Any] | None = <function default_response>, max_retries: int | None = 3, prompt_type: ~agentscope.prompt.PromptType | None = None ) → None [源代码]
+__init__ ( name : str sys_prompt : str model_config_name : str use_memory : bool = True memory_config : dict | None = None max_retries : int | None = 3 ) → None [源代码] Initialize the dict dialog agent.
参数:
@@ -147,20 +123,22 @@
configuration.
use_memory (bool , defaults to True ) – Whether the agent has memory.
memory_config (Optional[dict] , defaults to None ) – The config of memory.
parse_func (Optional[Callable[…, Any]] , defaults to parse_dict ) – The function used to parse the model output,
-e.g. json.loads , which is used to extract json from the
-output.
fault_handler (Optional[Callable[…, Any]] , defaults to default_response ) – The function used to handle the fault when parse_func fails
-to parse the model output.
max_retries (Optional[int] , defaults to None ) – The maximum number of retries when failed to parse the model
output.
prompt_type (Optional[PromptType] , defaults to PromptType.LIST ) – The type of the prompt organization, chosen from
-PromptType.LIST or PromptType.STRING .
+
+
+set_parser ( parser : ParserBase ) → None [源代码]
+Set response parser, which will provide 1) format instruction; 2)
+response parsing; 3) filtering fields when returning message, storing
+message in memory. So developers only need to change the
+parser, and the agent will work as expected.
+
+
reply ( x : dict | None = None ) → dict [源代码]
diff --git a/zh_CN/agentscope.agents.html b/zh_CN/agentscope.agents.html
index a7a8f51fd..7d54bbfe2 100644
--- a/zh_CN/agentscope.agents.html
+++ b/zh_CN/agentscope.agents.html
@@ -89,6 +89,7 @@
DictDialogAgent class agentscope.agents. DictDialogAgent ( * args : tuple ** kwargs : dict ) [源代码] 基类：AgentBase
An agent that generates response in a dict format, where user can
-specify the required fields in the response via prompt, e.g.
-prompt = "... Response in the following format that can be loaded by
-python json . loads ()
-{
- "thought" : "thought" ,
- "speak" : "thoughts summary to say to others" ,
- # ...
-} "
-
-
This agent class is an example for using parse_func and fault_handler
-to parse the output from the model, and handling the fault when parsing
-fails. We take “speak” as a required field in the response, and print
-the speak field as the output response.
+specify the required fields in the response via specifying the parser
+About parser, please refer to our
+[tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html )
For usage example, please refer to the example of werewolf in
examples/game_werewolf
-__init__ ( name: str, sys_prompt: str, model_config_name: str, use_memory: bool = True, memory_config: dict | None = None, parse_func: ~typing.Callable[[...], ~typing.Any] | None = <function parse_dict>, fault_handler: ~typing.Callable[[...], ~typing.Any] | None = <function default_response>, max_retries: int | None = 3, prompt_type: ~agentscope.prompt.PromptType | None = None ) → None [源代码]
+__init__ ( name : str sys_prompt : str model_config_name : str use_memory : bool = True memory_config : dict | None = None max_retries : int | None = 3 ) → None [源代码] Initialize the dict dialog agent.
参数:
@@ -482,20 +472,22 @@
configuration.
use_memory (bool , defaults to True ) – Whether the agent has memory.
memory_config (Optional[dict] , defaults to None ) – The config of memory.
parse_func (Optional[Callable[…, Any]] , defaults to parse_dict ) – The function used to parse the model output,
-e.g. json.loads , which is used to extract json from the
-output.
fault_handler (Optional[Callable[…, Any]] , defaults to default_response ) – The function used to handle the fault when parse_func fails
-to parse the model output.
max_retries (Optional[int] , defaults to None ) – The maximum number of retries when failed to parse the model
output.
prompt_type (Optional[PromptType] , defaults to PromptType.LIST ) – The type of the prompt organization, chosen from
-PromptType.LIST or PromptType.STRING .
+
+set_parser ( parser : ParserBase ) → None [源代码]
+Set response parser, which will provide 1) format instruction; 2)
+response parsing; 3) filtering fields when returning message, storing
+message in memory. So developers only need to change the
+parser, and the agent will work as expected.
+
+
reply ( x : dict | None = None ) → dict [源代码]
diff --git a/zh_CN/agentscope.message.html b/zh_CN/agentscope.message.html
index 03873c7f5..8b2bc4616 100644
--- a/zh_CN/agentscope.message.html
+++ b/zh_CN/agentscope.message.html
@@ -68,6 +68,13 @@
Msg
+Msg.id Msg.name Msg.content Msg.role Msg.metadata Msg.url Msg.timestamp Msg.__init__() Msg.to_str() Msg.serialize()
-class agentscope.message. Msg ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False ** kwargs : Any ) [源代码]
+class agentscope.message. Msg ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False metadata : dict | str | None = None ** kwargs : Any ) [源代码] 基类：MessageBase
The Message class.
+
+
+id : str
+The id of the message.
+
+
+
+
+name : str
+The name of who send the message.
+
+
+
+
+content : Any
+The content of the message.
+
+
+
+
+role : Literal [ 'system' , 'user' , 'assistant' ]
+The role of the message sender.
+
+
+
+
+metadata : dict | None
+Save the information for application’s control flow, or other
+purposes.
+
+
+
+
+url : Sequence [ str ] | str | None
+A url to file, image, video, audio or website.
+
+
+
+
+timestamp : str
+The timestamp of the message.
+
+
-__init__ ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False ** kwargs : Any ) → None [源代码]
+__init__ ( name : str content : Any role : Literal [ 'system' , 'user' , 'assistant' ] | None = None url : Sequence [ str ] | str | None = None timestamp : str | None = None echo : bool = False metadata : dict | str | None = None ** kwargs : Any ) → None [源代码] Initialize the message object
参数:
@@ -194,6 +244,9 @@
url (Optional[Union[list[str], str]] , defaults to None ) – A url to file, image, video, audio or website.
timestamp (Optional[str] , defaults to None ) – The timestamp of the message, if None, it will be set to
current time.
echo (bool , defaults to False ) – Whether to print the message to the console.
metadata (Optional[Union[dict, str]] , defaults to None ) – Save the information for application’s control flow, or other
+purposes.
**kwargs (Any ) – Other attributes of the message.
diff --git a/zh_CN/agentscope.parsers.code_block_parser.html b/zh_CN/agentscope.parsers.code_block_parser.html
index 223745687..4da8df88d 100644
--- a/zh_CN/agentscope.parsers.code_block_parser.html
+++ b/zh_CN/agentscope.parsers.code_block_parser.html
@@ -101,15 +101,9 @@
Model response parser class for Markdown code block.
-class agentscope.parsers.code_block_parser. MarkdownCodeBlockParser ( language_name : str ) [源代码]
+class agentscope.parsers.code_block_parser. MarkdownCodeBlockParser ( language_name : str content_hint : str | None = None ) [源代码] 基类：ParserBase
The base class for parsing the response text by fenced block.
-
-
-content_hint : str = '${{your_{language_name}_code}}'
-The hint of the content.
-
-
tag_end : str = '```'
@@ -118,8 +112,16 @@
-__init__ ( language_name : str ) → None [源代码]
-
+__init__ ( language_name : str content_hint : str | None = None ) → None [源代码] Initialize the parser with the language name and the optional
+content hint.
+
+参数:
+language_name – The name of the language, which will be used
+in `` `
+
+
@@ -133,9 +135,15 @@
The beginning tag.
+
+
+content_hint : str = '${{your_{language_name}_code}}'
+The hint of the content.
+
+
-format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n${{your_{language_name}_code}}\n```'
+format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n{content_hint}\n```' The instruction for the format of the code block.
diff --git a/zh_CN/agentscope.parsers.html b/zh_CN/agentscope.parsers.html
index 8c65503b8..e1126d6a7 100644
--- a/zh_CN/agentscope.parsers.html
+++ b/zh_CN/agentscope.parsers.html
@@ -90,11 +90,11 @@
MarkdownCodeBlockParser
-class agentscope.parsers. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) [源代码]
-基类：MarkdownJsonObjectParser
+class agentscope.parsers. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) [源代码] 基类：MarkdownJsonObjectParser DictFilterMixin
A class used to parse a JSON dictionary object in a markdown fenced
code
@@ -258,7 +258,7 @@
-__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) → None [源代码]
+__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) → None [源代码] Initialize the parser with the content hint.
参数:
@@ -270,9 +270,57 @@
required_keys (List[str] , defaults to [] ) – A list of required keys in the JSON dictionary object. If the
response misses any of the required keys, it will raise a
RequiredFieldNotFoundError.
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
@@ -295,15 +343,9 @@
-class agentscope.parsers. MarkdownCodeBlockParser ( language_name : str ) [源代码]
+class agentscope.parsers. MarkdownCodeBlockParser ( language_name : str content_hint : str | None = None ) [源代码] 基类：ParserBase
The base class for parsing the response text by fenced block.
-
-
-content_hint : str = '${{your_{language_name}_code}}'
-The hint of the content.
-
-
tag_end : str = '```'
@@ -312,8 +354,16 @@
-__init__ ( language_name : str ) → None [源代码]
-
+__init__ ( language_name : str content_hint : str | None = None ) → None [源代码] Initialize the parser with the language name and the optional
+content hint.
+
+参数:
+language_name – The name of the language, which will be used
+in `` `
+
+
@@ -327,9 +377,15 @@
The beginning tag.
+
+
+content_hint : str = '${{your_{language_name}_code}}'
+The hint of the content.
+
+
-format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n${{your_{language_name}_code}}\n```'
+format_instruction : str = 'You should generate {language_name} code in a {language_name} fenced code block as follows: \n```{language_name}\n{content_hint}\n```' The instruction for the format of the code block.
@@ -368,7 +424,8 @@
name : str
-The name of the tagged content.
+The name of the tagged content, which will be used as the key in
+extracted dictionary.
@@ -399,8 +456,8 @@
-class agentscope.parsers. MultiTaggedContentParser ( * tagged_contents : TaggedContent ) [源代码]
-基类：ParserBase
+class agentscope.parsers. MultiTaggedContentParser ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) [源代码] 基类：ParserBase DictFilterMixin
Parse response text by multiple tags, and return a dict of their
content. Asking llm to generate JSON dictionary object directly maybe not a
good idea due to involving escape characters and other issues. So we can
@@ -416,12 +473,69 @@
-__init__ ( * tagged_contents : TaggedContent ) → None [源代码]
+__init__ ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) → None [源代码] Initialize the parser with tags.
参数:
-tags (dict[str, Tuple[str, str]] ) – A dictionary of tags, the key is the tag name, and the value is
-a tuple of starting tag and end tag.
+
+*tagged_contents (dict[str, Tuple[str, str]] ) – Multiple TaggedContent objects, each object contains the tag
+name, tag begin, content hint and tag end. The name will be
+used as the key in the extracted dictionary.
required_keys (Optional[List[str]] , defaults to None ) – A list of required
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+keys_allow_missing (Optional[List[str]] , defaults to None ) – A list of keys that are allowed to be missing in the response.
diff --git a/zh_CN/agentscope.parsers.json_object_parser.html b/zh_CN/agentscope.parsers.json_object_parser.html
index 6a07f0413..4be7c2fdf 100644
--- a/zh_CN/agentscope.parsers.json_object_parser.html
+++ b/zh_CN/agentscope.parsers.json_object_parser.html
@@ -160,8 +160,8 @@
-class agentscope.parsers.json_object_parser. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) [源代码]
-基类：MarkdownJsonObjectParser
+class agentscope.parsers.json_object_parser. MarkdownJsonDictParser ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) [源代码] 基类：MarkdownJsonObjectParser DictFilterMixin
A class used to parse a JSON dictionary object in a markdown fenced
code
@@ -190,7 +190,7 @@
-__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None ) → None [源代码]
+__init__ ( content_hint : Any | None = None required_keys : List [ str ] | None = None keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False ) → None [源代码] Initialize the parser with the content hint.
参数:
@@ -202,9 +202,57 @@
required_keys (List[str] , defaults to [] ) – A list of required keys in the JSON dictionary object. If the
response misses any of the required keys, it will raise a
RequiredFieldNotFoundError.
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
diff --git a/zh_CN/agentscope.parsers.parser_base.html b/zh_CN/agentscope.parsers.parser_base.html
index f5d99c2e2..f2b68cb25 100644
--- a/zh_CN/agentscope.parsers.parser_base.html
+++ b/zh_CN/agentscope.parsers.parser_base.html
@@ -113,6 +113,66 @@
+
+
+class agentscope.parsers.parser_base. DictFilterMixin ( keys_to_memory : str | bool | Sequence [ str ] keys_to_content : str | bool | Sequence [ str ] keys_to_metadata : str | bool | Sequence [ str ] ) [源代码]
+基类：object
+A mixin class to filter the parsed response by keys. It allows users
+to set keys to be filtered during speaking, storing in memory, and
+returning in the agent reply function.
+
+
+__init__ ( keys_to_memory : str | bool | Sequence [ str ] keys_to_content : str | bool | Sequence [ str ] keys_to_metadata : str | bool | Sequence [ str ] ) → None [源代码]
+Initialize the mixin class with the keys to be filtered during
+speaking, storing in memory, and returning in the agent reply function.
+
+参数:
+
+keys_to_memory (Optional[Union[str, bool, Sequence[str]]] ) – The key or keys to be filtered in to_memory method. If
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
keys_to_content (Optional[Union[str, bool, Sequence[str]] ) – The key or keys to be filtered in to_content method. If
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
keys_to_metadata (Optional[Union[str, bool, Sequence[str]]] ) – The key or keys to be filtered in to_metadata method. If
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+
+
+
+to_memory ( parsed_response : dict allow_missing : bool = False ) → str | dict | None [源代码]
+Filter the fields that will be stored in memory.
+
+
+
+
+to_content ( parsed_response : dict allow_missing : bool = False ) → str | dict | None [源代码]
+Filter the fields that will be fed into the content field in the
+returned message, which will be exposed to other agents.
+
+
+
+
+to_metadata ( parsed_response : dict allow_missing : bool = False ) → str | dict | None [源代码]
+Filter the fields that will be fed into the returned message
+directly to control the application workflow.
+
+
+
+
diff --git a/zh_CN/agentscope.parsers.tagged_content_parser.html b/zh_CN/agentscope.parsers.tagged_content_parser.html
index f45062ca6..459e97aa7 100644
--- a/zh_CN/agentscope.parsers.tagged_content_parser.html
+++ b/zh_CN/agentscope.parsers.tagged_content_parser.html
@@ -125,7 +125,8 @@
name : str
-The name of the tagged content.
+The name of the tagged content, which will be used as the key in
+extracted dictionary.
@@ -156,8 +157,8 @@
-class agentscope.parsers.tagged_content_parser. MultiTaggedContentParser ( * tagged_contents : TaggedContent ) [源代码]
-基类：ParserBase
+class agentscope.parsers.tagged_content_parser. MultiTaggedContentParser ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) [源代码] 基类：ParserBase DictFilterMixin
Parse response text by multiple tags, and return a dict of their
content. Asking llm to generate JSON dictionary object directly maybe not a
good idea due to involving escape characters and other issues. So we can
@@ -173,12 +174,69 @@
-__init__ ( * tagged_contents : TaggedContent ) → None [源代码]
+__init__ ( * tagged_contents : TaggedContent keys_to_memory : str | bool | Sequence [ str ] | None = True keys_to_content : str | bool | Sequence [ str ] | None = True keys_to_metadata : str | bool | Sequence [ str ] | None = False keys_allow_missing : List [ str ] | None = None ) → None [源代码] Initialize the parser with tags.
参数:
-tags (dict[str, Tuple[str, str]] ) – A dictionary of tags, the key is the tag name, and the value is
-a tuple of starting tag and end tag.
+
+*tagged_contents (dict[str, Tuple[str, str]] ) – Multiple TaggedContent objects, each object contains the tag
+name, tag begin, content hint and tag end. The name will be
+used as the key in the extracted dictionary.
required_keys (Optional[List[str]] , defaults to None ) – A list of required
( `Optional [ Union [ str (keys_to_memory ) –
bool
Sequence [ str ] ] ] `
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_memory method. If
+
+it’s
+- False , None will be returned in the to_memory method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to True ): The key or keys to be filtered in to_content method. If
+
+it’s
+- False , None will be returned in the to_content method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+
+
+
+:param :
+:param defaults to False ): The key or keys to be filtered in to_metadata method. If
+
+it’s
+- False , None will be returned in the to_metadata method
+- str , the corresponding value will be returned
+- List[str] , a filtered dictionary will be returned
+- True , the whole dictionary will be returned
+
+
+参数:
+keys_allow_missing (Optional[List[str]] , defaults to None ) – A list of keys that are allowed to be missing in the response.
diff --git a/zh_CN/genindex.html b/zh_CN/genindex.html
index 70b31a142..5726dada0 100644
--- a/zh_CN/genindex.html
+++ b/zh_CN/genindex.html
@@ -236,6 +236,8 @@ _
delete_file()（在 agentscope.service 模块中）
delete_file()（在 agentscope.service.file.common 模块中）
@@ -1287,6 +1289,8 @@ D
DictDialogAgent（agentscope.agents 中的类）
DictDialogAgent（agentscope.agents.dict_dialog_agent 中的类）
+DictFilterMixin（agentscope.parsers.parser_base 中的类）
digest_webpage()（在 agentscope.service 模块中）
G
I
+ id（agentscope.message.Msg 属性）
+ifelsepipeline()（在 agentscope.pipelines 模块中）
ifelsepipeline()（在 agentscope.pipelines.functional 模块中）
@@ -1747,6 +1753,8 @@ M
MessageBase（agentscope.message 中的类）
MESSAGE（agentscope.web.workstation.workflow_node.WorkflowNodeType 属性）
+metadata（agentscope.message.Msg 属性）
missing_begin_tag（agentscope.exception.TagNotFoundError 属性）
M
N
update_monitor() （agentscope.models.ModelWrapperBase 方法）
update_value() （agentscope.message.PlaceholderMessage 方法）
+url（agentscope.message.Msg 属性）
user_input()（在 agentscope.web.studio.utils 模块中）
Pipeline 和 MsgHub 模型 模型结果解析 服务函数 记忆 提示工程
模型 模型结果解析 服务函数 记忆 提示工程 创建自己的Model Wrapper 模型结果解析 服务函数 记忆 提示工程 创建自己的Model Wrapper