operagents下載 - operagents源代碼下載

作業系統

安裝

以以下方式安裝最新版本

pip install operagents
# or use poetry
poetry add operagents
# or use pdm
pdm add operagents
# or use uv
uv pip install operagents

概念

代理人

代理是人類或語言模型，可以充當角色並在歌劇場景中使用道具。代理可以通過觀察和行動與他人交流。每個代理都有一個後端（例如用戶，OpenAI API）來生成響應和自己的內存來存儲長期 /短期信息。

場景

場景是包含許多字符的歌劇的一部分。每個場景都有一個流程和主管來控制整個會話過程。場景還可以在場景開始之前進行準備部分進行一些初始化工作。

特點

角色是場景中的角色。每個角色都有一個名稱，描述和道具列表。場景開始時，代理人將充當角色並與他人交流。

流動

該流程用於控製字符在場景中的作用的順序。

導演

導演被用來決定是否結束當前場景以及下一步要播放哪個場景。

支柱

道具是一種工具，可以被代理商使用來改善其表演。代理可以使用道具獲取外部信息。

時間表

時間表是管理會話過程的Opera的主要運行時組件。它運行當前會話並在會話之間切換。時間表還記錄了歌劇的全球信息，所有代理商都可以共享。

會議

會話表示場景的單一運行。它包含一個唯一的標識符及其相應的場景。

用法

使用操作系統的常見方法是編寫配置文件並使用operagents命令行工具運行Opera。

開始編寫配置文件

創建一個具有以下基本內容的config.yaml文件：

 # yaml-language-server: $schema=https://operagents.yyydl.top/schemas/config.schema.json

agents :
opening_scene : " "
scenes :

第一行是一條評論，該評論告訴YAML語言服務器使用指定URL中的架構。這將在編輯器中啟用自動完成和驗證。
該架構與您正在使用的操作系統框架的版本有關。 URL的格式為https://operagents.yyydl.top/schemas/config-<version>.schema.json > schema.json，其中<version>是框架的版本，例如0.0.1 。如果未指定版本，將使用最新的（主）版本。

模板配置

在編寫代理和場景配置之前，我們需要了解模板配置。

操作員使用模板為語言模型生成上下文輸入。模板是Jinja格式的字符串。您可以將Jinja2語法與提供的上下文變量一起控制語言模型的輸入。

模板配置可以採用以下格式：

簡單的字符串模板

 user_template : |-
  {# some jinja template #}

具有自定義功能的模板

 user_template :
  content : |-
    {# some jinja template #}
  custom_functions :
    function_name : module_name:function_name

如果要在模板中使用自定義功能，則需要提供custom_functions鍵，該鍵是自定義函數名稱的字典及其相應的模塊路徑，以點符號格式。

代理配置

agents部分是代理的詞典，其中密鑰是代理的名稱，值是代理的配置。

代理需要在場景中充當角色並響應他人的信息。因此，代理配置的第一部分是後端配置，用於與語言模型或用戶進行通信。您可以使用backend鍵指定後端類型及其配置。

 agents :
  Mike :
    backend :
      # user as the backend (a.k.a human-agent)
      type : user
  John :
    backend :
      # openai api as the backend
      type : openai
      model : gpt-3.5-turbo
      temperature : 0.5
      api_key :
      base_url :
      max_retries : 2
      tool_choice :
        type : auto
      prop_validation_error_template : |-
        {# some jinja template #}

您還可以通過提供實現Backend摘要類的自定義後端類的對象路徑來自定義後端。

 agents :
  Mike :
    backend :
      type : custom
      path : module_name:CustomBackend
      custom_config : value

 # module_name.py

from typing import Self

from operagents . prop import Prop
from operagents . timeline import Timeline
from operagents . config import CustomBackendConfig
from operagents . backend import Backend , Message , GenerateResponse , GeneratePropUsage


class CustomBackend ( Backend ):
    @ classmethod
    def from_config ( cls , config : CustomBackendConfig ) -> Self :
        return cls ()

    @ overload
    async def generate (
        self ,
        timeline : Timeline ,
        messages : list [ Message ],
        props : None = None ,
    ) -> AsyncGenerator [ GenerateResponse , None ]: ...

    @ overload
    async def generate (
        self ,
        timeline : Timeline ,
        messages : list [ Message ],
        props : list [ Prop ],
    ) -> AsyncGenerator [ GenerateResponse | GeneratePropUsage , None ]: ...

    async def generate (
        self , timeline : Timeline , messages : list [ Message ], props : list [ Prop ] | None = None
    ) -> AsyncGenerator [ GenerateResponse | GeneratePropUsage , None ]:
        yield GenerateResponse ( content = "" )

代理配置的下一部分是用於生成語言模型的上下文輸入的系統/用戶模板。您可以使用system_template / user_template鍵來指定係統 /用戶模板。這是模板配置的示例：

 agents :
  John :
    system_template : |-
      Your name is {{ agent.name }}.
      Current scene is {{ timeline.current_scene.name }}.
      {% if timeline.current_scene.description -%}
      {{ timeline.current_scene.description }}
      {%- endif -%}
      You are acting as {{ timeline.current_character.name }}.
      {% if timeline.current_character.description -%}
      {{ timeline.current_character.description }}
      {%- endif -%}
      Please continue the conversation on behalf of {{ agent.name }}({{ timeline.current_character.name }}) based on your known information and make your answer appear as natural and coherent as possible.
      Please answer directly what you want to say and keep your reply as concise as possible.
    user_template : |-
      {% for event in timeline.past_events(agent) -%}
      {% if event.type_ == "session_act" -%}
      {{ event.character.agent_name }}({{ event.character.name }}): {{ event.content }}
      {%- endif %}
      {%- endfor %}

代理配置的另一部分是會話摘要係統/用戶模板，該模板用於生成場景會話的摘要。您可以使用session_summary_system_template / session_summary_user_template鍵來指定會話摘要係統 /用戶模板。這是模板配置的示例：

 agents :
  John :
    session_summary_system_template : |-
      Your name is {{ agent.name }}.
      Your task is to summarize the historical dialogue records according to the current scene, and summarize the most important information.
    session_summary_user_template : |-
      {% for event in agent.memory.get_memory_for_session(session_id) -%}
      {% if event.type_ == "observe" -%}
      {{ event.content }}
      {%- elif event.type_ == "act" -%}
      {{ agent.name }}({{ event.character.name }}): {{ event.content }}
      {%- endif %}
      {%- endfor %}
      {% for event in timeline.session_past_events(agent, session_id) -%}
      {% if event.type_ == "session_act" -%}
      {{ event.character.agent_name }}({{ event.character.name }}): {{ event.content }}
      {%- endif %}
      {%- endfor %}

開放場景配置

opening_scene鍵用於指定歌劇的開始場景。價值是開幕場景的名稱。

 opening_scene : " Introduction "

場景配置

scenes部分是場景詞典，其中鍵是場景的名稱，值是場景的配置。

歌劇由多個場景組成，每個場景都有許多字符。您首先需要定義場景的名稱，描述（可選）和字符。

 scenes :
  talking :
    description : " The scene is about two people talking. "
    characters :
      user :
        agent_name : " Mike "
      ai assistant :
        agent_name : " John "
        description : |-
          You are a helpful assistant.
        props : []

場景中的字符必須定義agent_name鍵，該鍵是代理的名稱，該鍵的名稱是角色。 description鍵（可選）可用於描述代理模板中的字符。 props鍵（可選）可用於定義角色的道具，有關更多詳細信息，請參見Prop Config。

場景的Flow旨在控制角色表演的順序。您可以指定Flow的類型和參數。

order類型

該order類型用於預先定義字符的表演順序。角色將循環瀏覽訂單列表，直到場景結束為止。

 scenes :
  talking :
    flow :
      type : order
      order :
        - user
        - ai assistant

model類型

model類型用於指定模型以預測下一個要行動的字符。該模型將根據當前上下文預測下一個字符。

 scenes :
  talking :
    flow :
      type : model
      backend :
        type : openai
        model : gpt-3.5-turbo
        temperature : 0.5
      system_template : " "
      user_template : " "
      allowed_characters : # optional, the characters allowed to act
        - user
        - ai assistant
      begin_character : user # optional, the first character to act
      fallback_character : ai assistant # optional, the fallback character when the model fails to predict

user類型
user類型允許人類選擇下一個要採取行動的角色。
```
 scenes :
  talking :
    flow :
      type : user
```

custom類型

custom類型允許您定義自定義流類以控製字符的表演順序。

 scenes :
  talking :
    flow :
      type : custom
      path : module_name:CustomFlow
      custom_config : value

 # module_name.py

from typing import Self

from operagents . flow import Flow
from operagents . timeline import Timeline
from operagents . character import Character
from operagents . config import CustomFlowConfig


class CustomFlow ( Flow ):
    @ classmethod
    def from_config ( cls , config : CustomFlowConfig ) -> Self :
        return cls ()

    async def begin ( self , timeline : Timeline ) -> Character :
        return ""

    async def next ( self , timeline : Timeline ) -> Character :
        return ""

場景Director用於控制下一個場景。您可以指定導演的類型和參數。

model類型

model類型用於指定模型以預測要播放的下一個場景。如果找不到結束標誌或找不到場景名稱，則庫倫場景將繼續播放。

 scenes :
  talking :
    director :
      type : model
      backend :
        type : openai
        model : gpt-3.5-turbo
        temperature : 0.5
      system_template : " "
      user_template : " "
      allowed_scenes : # optional, the next scenes allowed to play
        - walking
        - running
      finish_flag : " finish " # optional, the finish flag to end the opera

user類型

user類型允許人類選擇下一個場景。

 scenes :
  talking :
    director :
      type : user

never打字
never導演永遠不會結束當前場景。當有一個場景時，您想通過Prop結束歌劇。
```
 scenes :
  talking :
    director :
      type : never
```

custom類型

custom類型允許您定義自定義導演類以控制下一個要播放的場景。

 scenes :
  talking :
    director :
      type : custom
      path : module_name:CustomDirector
      custom_config : value

 # module_name.py

from typing import Self

from operagents . scene import Scene
from operagents . director import Director
from operagents . timeline import Timeline
from operagents . config import CustomDirectorConfig

class CustomDirector ( Director ):
    @ classmethod
    def from_config ( cls , config : CustomDirectorConfig ) -> Self :
        return cls ()

    async def next_scene ( self , timeline : Timeline ) -> Scene | None :
        return None

場景的prepare部分用於在場景開始之前定義準備步驟。您可以在這裡進行一些初始化工作。

preface類型

您可以在場景開始之前讓角色說些什麼。

 scenes :
  talking :
    prepare :
      - type : preface
        character_name : ai assistant
        content : |-
          Hello, I am John, your AI assistant. How can I help you today?

function類型

function類型將在場景啟動之前調用自定義功能。

 scenes :
  talking :
    prepare :
      - type : function
        function : module_name:function_name

自定義功能將接收一個類型operagents.timeline.Timeline的參數。

 # module_name.py

from operagents . timeline import Timeline

async def function_name ( timeline : Timeline ) -> None :
    pass

custom類型

custom類型將在場景開始之前調用自定義準備課程。

 scenes :
  talking :
    prepare :
      - type : custom
        path : module_name:CustomPrepare
        custom_config : value

 # module_name.py

from typing import Self

from operagents . timeline import Timeline
from operagents . scene . prepare import ScenePrepare
from operagents . config import CustomScenePrepareConfig

class CustomScenePrepare ( ScenePrepare ):
    @ classmethod
    def from_config ( cls , config : CustomScenePrepareConfig ) -> Self :
        return cls ()

    async def prepare ( self , timeline : Timeline ) -> None :
        pass

道具配置

場景中的角色可以使用道具來改進那裡的表演。 props部分是道具列表，其中每個道具是帶有道具類型和道具配置的字典。

function道具

使用道具時， function道具將調用自定義功能。

 scenes :
  talking :
    characters :
      ai assistant :
        props :
          - type : function
            function : module_name:function_name
            exception_template : |-
              {# some jinja template #}

自定義函數不應具有pydantic.BaseModel類型的參數或一個參數。

 from pydantic import Field , BaseModel
from datetime import datetime , timezone

async def current_time () -> str :
    """Get the current real world time."""
    return datetime . now ( timezone . utc ). astimezone (). isoformat ()

class Args ( BaseModel ):
    name : str = Field ( description = "The name" )

async def greet ( args : Args ) -> str :
    """Greet the name."""
    return f"Hello, { args . name } !"

請注意，該函數的名稱和DOCSTRING將用作道具的姓名和描述。您還可以提供Pydantic Field對ARGS的描述。當函數引起錯誤時，異常模板將用於呈現響應。

custom道具

使用道具時， custom道具將調用自定義道具類。

 scenes :
  talking :
    characters :
      ai assistant :
        props :
          - type : custom
            path : module_name:CustomProp
            custom_config : value

 # module_name.py

from typing import Any , Self

from pydantic import BaseModel
from operagents . prop import Prop
from operagents . config import CustomPropConfig

class CustomProp ( Prop ):
    """The description of the prop"""

    params : BaseModel | None
    """The parameters of the prop"""

    @ classmethod
    def from_config ( cls , config : CustomPropConfig ) -> Self :
        return cls ()

    async def call ( self , params : BaseModel | None ) -> Any :
        return ""

鉤配置

掛鉤使您可以在發生特定的時間表事件時運行自定義代碼。 hooks部分是掛鉤列表，其中每個鉤子都是帶有鉤類型和鉤構型的字典。默認情況下，除非您更改hooks部分，否則操作系統可以啟用summary鉤。

summary鉤
summary掛鉤將打電話給代理以總結會話結束時會話。您可以選擇指定要匯總的代理名稱。
```
 hooks :
  - type : summary
    agent_names :
      - Mike
      - John
```

custom鉤

當特定時間表事件遇到時， custom鉤將調用自定義鉤類。

 hooks :
  - type : custom
    path : module_name:CustomHook
    custom_config : value

 # module_name.py

from typing import Self

from operagents . hook import Hook
from operagents . timeline import Timeline
from operagents . config import CustomHookConfig
from operagents . timeline . event import (
    TimelineEventEnd ,
    TimelineEventStart ,
    TimelineEventSessionAct ,
    TimelineEventSessionEnd ,
    TimelineEventSessionStart ,
)

class CustomHook ( Hook ):
    @ classmethod
    def from_config ( cls , config : CustomHookConfig ) -> Self :
        return cls ()

    async def on_timeline_start (
        self , timeline : Timeline , event : TimelineEventStart
    ):
        """Called when the timeline is started."""
        pass

    async def on_timeline_end (
        self , timeline : Timeline , event : TimelineEventEnd
    ):
        """Called when the timeline is ended."""
        pass

    async def on_timeline_session_start (
        self , timeline : Timeline , event : TimelineEventSessionStart
    ):
        """Called when a session is started."""
        pass

    async def on_timeline_session_end (
        self , timeline : Timeline , event : TimelineEventSessionEnd
    ):
        """Called when a session is ended."""
        pass

    async def on_timeline_session_act (
        self , timeline : Timeline , event : TimelineEventSessionAct
    ):
        """Called when a character acts in a session."""
        pass

鉤類可能包含on_timeline_<event_type>格式的方法，其中<event_type>是時間表事件的類型。

運行歌劇

操作員提供了一個命令行工具，可以輕鬆運行Opera。您可以使用以下命令運行Opera：

operagents run config.yaml

如果要查看調試日誌，則可以設置--log-level選項：

operagents run --log-level DEBUG config.yaml

可以通過運行的operagents --help來找到更多命令和選項。

如果要以編程方式運行歌劇，則可以使用opera.run函數：

 import asyncio
from pathlib import Path

import yaml
from operagents . opera import Opera
from operagents . log import setup_logging
from operagents . config import OperagentsConfig


async def main ():
    # if you want to setup the default logging for operagents
    setup_logging ( "INFO" )

    # load the opera from config file
    opera = Opera . from_config (
        OperagentsConfig . model_validate (
            yaml . safe_load ( Path ( "./config.yaml" ). read_text ( encoding = "utf-8" ))
        )
    )

    finish_state = await opera . run ()


if __name__ == "__main__" :
    asyncio . run ( main ())

例子

聊天機器人

 cd examples/chatbot
env OPENAI_API_KEY=sk-xxx OPENAI_BASE_URL=https://api.openai.com/v1 operagents run --log-level DEBUG config.yaml

發展

在代碼空間（DEV容器）中打開：

或在本地安裝開發環境：

poetry install && poetry run pre-commit install

展開

operagents

作業系統

安裝

概念

代理人

場景

特點

流動

導演

支柱

時間表

會議

用法

開始編寫配置文件

模板配置

代理配置

開放場景配置

場景配置

道具配置

鉤配置

運行歌劇

例子

聊天機器人

發展

ML stack

awesome free chatgpt

pywin_contextmenu

promptl

tick.chat

FastLoRAChat

chat.petals.dev

GPT Prompt Templates

GPTyped

ML stack

awesome free chatgpt

pywin_contextmenu

Google Dorks

shepherd

mongo express