operagents

Операции

Установка

Установите последнюю версию с:

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

Концепции

Агент

Агент - это человеческая или языковая модель, которая может действовать как символы и использовать реквизиты в оперных сценах. Агент может общаться с другими, наблюдая и действуя. У каждого агента есть бэкэнд (например, пользователь, API OpenAI) для создания ответа и собственной памяти для хранения долгосрочной / краткосрочной информации.

Сцена

Сцена является частью оперы, которая содержит несколько символов. Каждая сцена имеет поток и режиссер для управления всем сессионным процессом. Сцена также может иметь раздел подготовки, чтобы выполнить некоторые работы по инициализации, прежде чем начнется сцена.

Характер

Персонаж - это роль в сцене. У каждого персонажа есть имя, описание и список реквизитов. Когда начнется сцена, агент будет действовать как персонаж и общаться с другими.

Поток

Поток используется для управления порядком персонажей в сцене.

Директор

Режиссер используется, чтобы решить, закончить ли текущую сцену и какую сцену сыграть дальше.

Проп

Опора - это инструмент, который может использоваться агентами для улучшения их действия. Агенты могут получить внешнюю информацию с помощью реквизита.

Временная шкала

График является основным компонентом выполнения Opera для управления процессом сеанса. Он запускает текущий сеанс и переключатели между сеансами. Временная шкала также записывает глобальную информацию о операции и может быть передана всем агентам.

Сессия

Сессия указывает на один забег сцены. Он содержит уникальный идентификатор и его соответствующую сцену.

Использование

Обычным способом использования операций является написание файла конфигурации и запуск Opera с помощью инструмента командной строки operagents .

Начните записывать файл конфигурации

Создайте файл config.yaml со следующим базовым контентом:

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

agents :
opening_scene : " "
scenes :

Первая строка - это комментарий, который сообщает Yaml Language Server использовать схему из указанного URL. Это обеспечит автозаполнение и проверку в вашем редакторе.
Схема связана с версией используемой вами структуры Operagents. URL находится в формате https://operagents.yyydl.top/schemas/config-<version>.schema.json <version>.schema.json, где <version> является версией структуры, например, 0.0.1 . Если не указана версия, будет использоваться последняя (главная) версия.

Конфигурация шаблона

Перед написанием конфигураций агента и сцены нам нужно узнать о конфигурации шаблона.

Operagents использует шаблоны для создания ввода контекста для языковой модели. Шаблон - это строка в формате джинджи. Вы можете использовать синтаксис Jinja2 с предоставленными контекстными переменными для управления входом в языковую модель.

Конфигурация шаблона может быть в следующем формате:

1. Простой шаблон строки

    user_template : |-
     {# some jinja template #}

2. шаблон с пользовательскими функциями

    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 #}

Вы также можете настроить бэкэнд, предоставив объектный путь класса пользовательского бэкэнда, который реализует класс Abstract 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 (необязательно) может использоваться для определения реквизита символа, см. Конфигурацию опорта для получения более подробной информации.

Flow сцены предназначен для управления порядком актерского мастерства персонажей. Вы можете указать тип и параметры Flow .

1. тип order

   Тип order используется для предварительного определения порядка актерского мастерства символов. Персонажи пройдут через список заказов, пока сцена не закончится.

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

2. тип 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

3. Тип user

   Тип user позволяет человеку выбрать следующий символ для действия.

    scenes :
     talking :
       flow :
         type : user

4. 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 сцены используется для контроля следующей сцены, чтобы играть. Вы можете указать тип и параметры директора.

1. тип 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

2. Тип user

   Тип user позволяет человеку выбрать следующую сцену для игры.

    scenes :
     talking :
       director :
         type : user

3. never печатайте

   never никогда не заканчивает нынешнюю сцену. Полезно, когда есть одна сцена, и вы хотите закончить оперу Prop .

    scenes :
     talking :
       director :
         type : never

4. 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 сцены» используется для определения шагов подготовки до начала сцены. Вы можете выполнить некоторую работу по инициализации здесь.

1. Тип preface

   Вы можете заставить персонажа сказать что -то до того, как начнется сцена.

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

2. Тип 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

3. 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 представляет собой список реквизитов, где каждая опора является словарем с типом опоры и конфигурацией опоры.

1. 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 будут использоваться в качестве имени и описания опоры. Вы также можете дать описание ARGS с помощью Field Pydantic. Шаблон исключений будет использоваться для отображения ответа, когда функция выдвигает ошибку.

2. 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 представляет собой список крючков, где каждый крючок представляет собой словарь с типом крюка и конфигурацией крюка. По умолчанию Operagents включает в себя summary , если вы не измените раздел hooks .

1. summary крючок

   summary крючок позвонит агентам, чтобы суммировать сеанс, когда заканчивается сеанс. При желании вы можете указать имена агентов, чтобы суммировать.

    hooks :
     - type : summary
       agent_names :
         - Mike
         - John

2. 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> является типом события временной шкалы.

Запустить оперу

Operagents предоставляет инструмент командной строки для легкого запуска опера. Вы можете запустить опера со следующей командой:

operagents run config.yaml

Если вы хотите увидеть журналы отладки, вы можете установить опцию --log-level :

operagents run --log-level DEBUG config.yaml

Больше команд и параметров можно найти с помощью operagents --help .

Если вы хотите запустить Opera программно, вы можете использовать функцию 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

Разработка

Открыть в CodeSpaces (Dev Container):

Или установить среду разработки локально с помощью:

poetry install && poetry run pre-commit install