角色

角色是TaskWeaver中的一个概念，代表对话系统中的不同角色。 Planner和CodeInterpreter就是TaskWeaver中角色的两个示例。

class Role:
    @inject
    def __init__(
        self,
        config: ModuleConfig,
        logger: TelemetryLogger,
        tracing: Tracing,
        event_emitter: SessionEventEmitter,
        role_entry: Optional[RoleEntry] = None,
    ):
        """
        The base class for all roles.
        """

info

我们使用injector包中的inject装饰器将依赖项注入到角色类中。

我们允许通过继承Role类并在taskweaver.ext_role模块中实现角色来向系统添加额外角色。我们提供了如何实现新角色的示例。一个非常简单的例子是Echo角色，它会将用户的消息原样返回给用户。

一个角色至少需要包含两个文件：role_name.py和role_name.role.yaml。角色文件应放置在taskweaver/ext_role/role_name文件夹中。我们需要遵循角色名称的命名规范，该名称必须与文件夹名称完全一致，否则会抛出异常。我们通常使用snake_case风格来命名角色。

在role_name.role.yaml文件中，我们定义了角色的配置。以下是Echo角色的echo.role.yaml配置文件。

alias: Echo
module: taskweaver.ext_role.echo.echo.Echo
intro : |-
  - Echo is responsible for echoing the user input.

配置文件包含以下字段：

alias: 角色的别名，这是在提示信息和对话中显示的角色名称。
module: 角色类的模块路径。TaskWeaver将导入该模块并实例化角色类。
intro: 角色介绍，这部分内容会显示在Planner的提示中，用于为特定任务选择角色。

在role_name.py文件中，我们定义了角色类。以下是Echo角色类的echo.py示例。

class EchoConfig(RoleConfig):
    def _configure(self):
        # configuration for the Echo role
        # can be configured in the project configuration file with `echo.decorator`
        self.decorator = self._get_str("decorator", "")


class Echo(Role):
    @inject
    def __init__(
        self,
        config: EchoConfig,
        logger: TelemetryLogger,
        tracing: Tracing,
        event_emitter: SessionEventEmitter,
        role_entry: RoleEntry,
    ):
        # configuration for the parent class; this is required
        super().__init__(config, logger, tracing, event_emitter, role_entry)

    def reply(self, memory: Memory, **kwargs) -> Post:
        rounds = memory.get_role_rounds(
            role=self.alias,
            include_failure_rounds=False,
        )

        # obtain the query from the last round
        last_post = rounds[-1].post_list[-1]

        post_proxy = self.event_emitter.create_post_proxy(self.alias)

        post_proxy.update_send_to(last_post.send_from)
        post_proxy.update_message(
            self.config.decorator +
            last_post.message +
            self.config.decorator
        )

        return post_proxy.end()

角色实现应当继承Role类并实现reply方法。上述示例展示了如何获取上一轮的查询。 Echo角色的reply函数只是简单地将用户消息原样返回给用户，可选择是否添加修饰。 reply函数应返回一个Post对象，这是角色对用户的响应。

我们提供相关功能，帮助角色与记忆系统、事件发射器和日志记录器进行交互。例如，event_emitter.create_post_proxy函数用于创建PostProxy对象，这是一个辅助类，用于创建Post对象。 PostProxy对象用于通过新消息、发送对象和其他属性来更新Post对象。当PostProxy对象更新完成后，事件发射器会将此事件发送给处理器，以便在前端显示该事件。

要在TaskWeaver中启用角色，我们需要将角色配置添加到taskweaver_config.json文件中。以下是taskweaver_config.json文件的示例，其中除了Planner和CodeInterpreter角色外，还包含Echo角色的配置。请注意，角色的名称应与角色文件夹名称相同，而非别名。

{
    "session.roles": ["planner", "echo", "code_interpreter"]
}

tip

如何判断应该创建新角色还是为CodeInterpreter实现新插件？ 答案取决于您想要实现的功能。如果功能是根据用户查询以文本消息形式回复，且您不预见需要在代码中处理回复文本，则应创建新角色。相反，如果功能是处理用户查询并以结构化格式返回结果，或者输入和输出都是结构化格式，则应实现一个新的CodeInterpreter插件。