operagents

Operagen

Instalasi

Instal versi terbaru dengan:

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

Konsep

Agen

Agen adalah model manusia atau bahasa yang dapat bertindak sebagai karakter dan menggunakan alat peraga dalam adegan opera. Agen dapat berkomunikasi dengan orang lain dengan mengamati dan bertindak. Setiap agen memiliki backend (misalnya pengguna, API OpenAI) untuk menghasilkan respons dan memiliki memori untuk menyimpan informasi jangka panjang / jangka pendek.

Pemandangan

Adegan adalah bagian dari opera yang berisi sejumlah karakter. Setiap adegan memiliki aliran dan sutradara untuk mengendalikan seluruh proses sesi. Adegan ini juga dapat memiliki bagian persiapan untuk melakukan beberapa pekerjaan inisialisasi sebelum adegan dimulai.

Karakter

Karakter adalah peran dalam adegan. Setiap karakter memiliki nama, deskripsi, dan daftar alat peraga. Ketika adegan dimulai, seorang agen akan bertindak sebagai karakter dan berkomunikasi dengan orang lain.

Mengalir

Aliran digunakan untuk mengontrol urutan akting karakter dalam adegan.

Direktur

Sutradara digunakan untuk memutuskan apakah akan mengakhiri adegan saat ini dan adegan mana yang akan dimainkan selanjutnya.

Menopang

Prop adalah alat yang dapat digunakan oleh agen untuk meningkatkan akting mereka. Agen bisa mendapatkan informasi eksternal dengan menggunakan alat peraga.

Timeline

Garis waktu adalah komponen runtime utama dari opera untuk mengelola proses sesi. Ini menjalankan sesi saat ini dan beralih antar sesi. Garis waktu juga mencatat informasi global opera, dan dapat dibagikan oleh semua agen.

Sidang

Sesi menunjukkan satu run adegan. Ini berisi pengidentifikasi unik dan adegan yang sesuai.

Penggunaan

Cara umum untuk menggunakan opera adalah dengan menulis file konfigurasi dan menjalankan opera dengan alat baris perintah operagents .

Mulailah menulis file konfigurasi

Buat file config.yaml dengan konten dasar berikut:

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

agents :
opening_scene : " "
scenes :

Baris pertama adalah komentar yang memberitahu server bahasa YAML untuk menggunakan skema dari URL yang ditentukan. Ini akan memungkinkan pelengkapan dan validasi autoc di editor Anda.
Skema ini terkait dengan versi kerangka kerja opera yang Anda gunakan. URL berada dalam format https://operagents.yyydl.top/schemas/config-<version>.schema.json <version>.schema.json, di mana <version> adalah versi kerangka kerja, misalnya 0.0.1 . Jika tidak ada versi yang ditentukan, versi (master) terbaru akan digunakan.

Konfigurasi Template

Sebelum menulis konfigurasi agen dan adegan, kita perlu belajar tentang konfigurasi template.

Operagents menggunakan templat untuk menghasilkan input konteks untuk model bahasa. Templat adalah string dalam format Jinja. Anda dapat menggunakan sintaks Jinja2 dengan varaibles konteks yang disediakan untuk mengontrol input ke model bahasa.

Konfigurasi templat dapat dalam format berikut:

1. template string sederhana

    user_template : |-
     {# some jinja template #}

2. template dengan fungsi khusus

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

Jika Anda ingin menggunakan fungsi khusus dalam templat, Anda perlu menyediakan kunci custom_functions , yang merupakan kamus nama fungsi khusus dan jalur modul yang sesuai dalam format notasi titik.

Konfigurasi Agen

Bagian agents adalah kamus agen, di mana kuncinya adalah nama agen dan nilainya adalah konfigurasi agen.

Agen perlu bertindak sebagai karakter dalam adegan dan menanggapi pesan orang lain. Jadi, bagian pertama dari konfigurasi agen adalah konfigurasi backend, yang digunakan untuk berkomunikasi dengan model bahasa atau pengguna. Anda dapat menggunakan tombol backend untuk menentukan jenis backend dan konfigurasi.

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

Anda juga dapat menyesuaikan backend dengan menyediakan jalur objek dari kelas backend khusus yang mengimplementasikan kelas abstrak 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 = "" )

Bagian selanjutnya dari konfigurasi agen adalah templat sistem/pengguna yang digunakan untuk menghasilkan input konteks untuk model bahasa. Anda dapat menggunakan tombol system_template / user_template untuk menentukan templat sistem / pengguna. Berikut adalah contoh konfigurasi templat:

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

Bagian lain dari konfigurasi agen adalah sistem ringkasan sesi/templat pengguna, yang digunakan untuk menghasilkan ringkasan sesi adegan. Anda dapat menggunakan tombol session_summary_system_template / session_summary_user_template untuk menentukan sistem ringkasan sesi / template pengguna. Berikut adalah contoh konfigurasi templat:

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

Konfigurasi adegan pembukaan

Kunci opening_scene digunakan untuk menentukan adegan awal opera. Nilainya adalah nama adegan pembuka.

 opening_scene : " Introduction "

Konfigurasi Adegan

Bagian scenes adalah kamus adegan, di mana kuncinya adalah nama adegan dan nilainya adalah konfigurasi adegan.

Opera terdiri dari beberapa adegan, dan setiap adegan memiliki sejumlah karakter. Pertama -tama Anda harus mendefinisikan nama, deskripsi (opsional), dan karakter adegan.

 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 : []

Karakter dalam adegan harus menentukan kunci agent_name , yang merupakan nama agen yang bertindak sebagai karakter. Kunci description (opsional) dapat digunakan untuk menggambarkan karakter dalam templat agen. Kunci props (opsional) dapat digunakan untuk menentukan alat peraga karakter, lihat konfigurasi prop untuk detail lebih lanjut.

Flow adegan dirancang untuk mengontrol urutan akting karakter. Anda dapat menentukan jenis dan parameter Flow .

1. jenis order

   Jenis order digunakan untuk mendefinisikan urutan akting karakter. Karakter akan bersepeda melalui daftar pesanan sampai adegan berakhir.

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

2. tipe model

   Jenis model digunakan untuk menentukan model untuk memprediksi karakter berikutnya untuk bertindak. Model akan memprediksi karakter berikutnya berdasarkan konteks saat ini.

    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. Jenis user

   Jenis user memungkinkan manusia untuk memilih karakter berikutnya untuk bertindak.

    scenes :
     talking :
       flow :
         type : user

4. Jenis custom

   Jenis custom memungkinkan Anda untuk menentukan kelas aliran khusus untuk mengontrol urutan akting karakter.

    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 adegan itu digunakan untuk mengontrol adegan berikutnya untuk dimainkan. Anda dapat menentukan jenis dan parameter sutradara.

1. tipe model

   Jenis model digunakan untuk menentukan model untuk memprediksi adegan berikutnya untuk dimainkan. Jika tidak ada bendera finish yang ditemukan atau tidak ada nama adegan yang ditemukan, adegan curent akan terus bermain.

    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. Jenis user

   Jenis user memungkinkan manusia untuk memilih adegan berikutnya untuk dimainkan.

    scenes :
     talking :
       director :
         type : user

3. never mengetik

   Sutradara never tidak pernah mengakhiri adegan saat ini. Berguna saat ada satu adegan dan Anda ingin mengakhiri opera dengan Prop .

    scenes :
     talking :
       director :
         type : never

4. Jenis custom

   Jenis custom memungkinkan Anda untuk mendefinisikan kelas sutradara khusus untuk mengontrol adegan berikutnya untuk dimainkan.

    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

Bagian prepare adegan digunakan untuk menentukan langkah -langkah persiapan sebelum adegan dimulai. Anda dapat melakukan beberapa pekerjaan inisialisasi di sini.

1. jenis kata preface

   Anda dapat membuat karakter mengatakan sesuatu sebelum adegan dimulai.

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

2. tipe function

   Jenis function akan memanggil fungsi khusus sebelum adegan dimulai.

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

   Fungsi khusus akan menerima satu parameter tipe operagents.timeline.Timeline .

    # module_name.py
   
   from operagents . timeline import Timeline
   
   async def function_name ( timeline : Timeline ) -> None :
       pass

3. Jenis custom

   Jenis custom akan menghubungi kelas persiapan khusus sebelum adegan dimulai.

    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

Konfigurasi prop

Karakter dalam adegan dapat menggunakan alat peraga untuk meningkatkan akting di sana. Bagian props adalah daftar alat peraga, di mana setiap prop adalah kamus dengan jenis prop dan konfigurasi prop.

1. function prop

   Prop function akan memanggil fungsi khusus saat prop digunakan.

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

   Fungsi khusus seharusnya tidak memiliki argumen atau satu argumen tipe 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 } !"

   Perhatikan bahwa nama dan docString fungsi akan digunakan sebagai nama dan deskripsi prop. Anda juga dapat memberikan deskripsi Args by Pydantic's Field . Template pengecualian akan digunakan untuk memberikan respons ketika fungsi menimbulkan kesalahan.

2. Prop custom

   Prop custom akan menghubungi kelas prop khusus saat penyangga digunakan.

    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 ""

Konfigurasi hook

Hooks memungkinkan Anda untuk menjalankan kode khusus ketika peristiwa timeline tertentu terjadi. Bagian hooks adalah daftar kait, di mana setiap kait adalah kamus dengan jenis kait dan konfigurasi kait. Secara default, opera memungkinkan summary kait kecuali Anda mengubah bagian hooks .

1. summary kait

   summary kait akan memanggil agen untuk meringkas sesi ketika sesi berakhir. Anda secara opsional dapat menentukan nama agen untuk diringkas.

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

2. Kait custom

   Kait custom akan memohon kelas kait khusus saat pertemuan acara timeline tertentu.

    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

   Kelas hook dapat berisi metode dalam format on_timeline_<event_type> , di mana <event_type> adalah jenis acara timeline.

Jalankan opera

Operagents menyediakan alat baris perintah untuk dengan mudah menjalankan opera. Anda dapat menjalankan opera dengan perintah berikut:

operagents run config.yaml

Jika Anda ingin melihat log debug, Anda dapat mengatur opsi --log-level :

operagents run --log-level DEBUG config.yaml

Lebih banyak perintah dan opsi dapat ditemukan dengan menjalankan operagents --help .

Jika Anda ingin menjalankan opera secara terprogram, Anda dapat menggunakan fungsi 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 ())

Contoh

Chatbot

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

Perkembangan

Buka di Codespaces (Dev Container):

Atau instal lingkungan pengembangan secara lokal dengan:

poetry install && poetry run pre-commit install