Agentariumの `Agent` クラスをコード読みしてみた（2025年1月時点）

## はじめに
- [Agentarium](https://pypi.org/project/agentarium/) は、複数のAIエージェントを手軽に操作・連携させるためのPythonライブラリ。  
- この記事では、その中心となる `Agent` クラスのコードを実際に読んでみます。  
- 「コードを追いながら、どんな仕組みで動いているのかをざっくり把握する」ことが目的です。  
- **2025年1月時点**の状況なので、将来的に変更される可能性があります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/e64188af-f629-2fca-3263-83bbc65ba2ee.png)

---

## `Agent`クラス全体の役割
- **エージェント（AIキャラクター）の作成・管理**  
- **他エージェントとの会話・思考などのアクション**  
- **LLM（大規模言語モデル）を活用したテキスト生成・自動化**  
- **CheckpointManager での状態保存**  
- **faker と組み合わせたプロフィール自動生成**  

要するに、1体の「AIキャラクター」を表現するためのクラスになっています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/f65f781d-f32a-acc3-2aa8-763884929644.png)

---

## コードの構成をざっくり眺める
```python
class Agent:
    """
    A class representing an autonomous agent in the environment.
    """

    _interaction_manager = AgentInteractionManager()
    _allow_init = False

    def __init__(self, **kwargs):
        ...
    
    @staticmethod
    @cache_w_checkpoint_manager
    def create_agent(...):
        ...
    
    @property
    def name(self) -> str:
        ...
    
    @cache_w_checkpoint_manager
    def act(self) -> str:
        ...
    
    def talk_to(self, receiver: Agent, message: str) -> None:
        ...
    
    def think(self, message: str) -> None:
        ...
    
    def ask(self, message: str) -> None:
        ...
    
    def add_new_action(self, action_descriptor: dict, action_function: Callable) -> None:
        ...
    
    def reset(self) -> None:
        ...
```

- コード全体を見ると、**Agentを初期化**するメソッド群、**プロパティ**による情報参照、**act/talk_to/think**などの**行動メソッド**、**拡張用add_new_action** などが並んでいます。  
- それぞれの流れを順を追って見てみましょう。

---

## `__init__` と `create_agent` 周り
```python
def __init__(self, **kwargs):
    if not Agent._allow_init:
        raise RuntimeError("Agent instances should be created using Agent.create_agent()")
    ...
    # fakerなどを用いて各種プロフィール情報を生成
    # _interaction_managerにエージェントを登録
    ...
```
- `__init__` では直接 `Agent(...)` できないようにしているのがポイント。  
- かわりに `create_agent(...)` を使って生成する流れになっています。

```python
@staticmethod
@cache_w_checkpoint_manager
def create_agent(...):
    try:
        Agent._allow_init = True
        return Agent(...)  # コンストラクタ呼び出し
    finally:
        Agent._allow_init = False
```
- `create_agent()` の中で `Agent._allow_init = True` にしてから `__init__` を呼び出すことで、「コンストラクタを使わないとダメだよ」を実現しています。  
- `cache_w_checkpoint_manager` デコレータが付いているので、このメソッドの呼び出し履歴がチェックポイントに記録される形です。

---

## faker と LLM の組み合わせ
```python
self.agent_id = self.agent_id if self.agent_id != DefaultValue.NOT_PROVIDED else faker.uuid4()
self.agent_informations: dict = kwargs or {}
if "gender" not in kwargs or kwargs["gender"] == DefaultValue.NOT_PROVIDED:
    self.agent_informations["gender"] = faker.random_element(elements=["male", "female"])
...
if "bio" not in kwargs or kwargs["bio"] == DefaultValue.NOT_PROVIDED:
    self.agent_informations["bio"] = Agent._generate_agent_bio(self.agent_informations)
```
- `gender`/`name`/`age`/`occupation`などを、指定がなければ `faker` で自動生成しています。  
- `bio`（エージェントの紹介文）は `_generate_agent_bio` という静的メソッドでLLMを使って生成。  

---

## `_interaction_manager` とやりとり管理
```python
_interaction_manager = AgentInteractionManager()
```
- クラス変数として存在。複数のAgentがいる場合でも、このマネージャは一つだけ。  
- `AgentInteractionManager` は `record_interaction(...)` などを通じて各エージェント間のメッセージ履歴を管理します。

---

## ざっくりまとめ

- **`Agent` クラスは「AIキャラ一体分の状態・やりとりを管理するための基盤」**  
- **faker＋LLM で手軽に初期プロフィールを作成**できるので、すぐに動く。  
- **カスタムアクション**も追加できるので、いろいろ拡張して遊べそう。

**2025年1月時点**ではまだ仕様が変わる可能性があるため、最新のドキュメントやGitHubリポジトリをチェックして活用してみてください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/6362e088-31b6-15f5-cfff-e3fbd9064593.png)

---

### 参考リンク
- [Agentarium (PyPI)](https://pypi.org/project/agentarium/)  
- [GitHub Repository](https://github.com/Thytu/Agentarium) 
- [Faker公式ドキュメント](https://faker.readthedocs.io/)  
- [aisuite](https://pypi.org/project/aisuite/)  

以上、「Agentariumの`Agent`クラスをコード読んでみた」記事でした。何かの参考になれば幸いです！

# Agentarium 関数一覧

| 関数名 | 説明 | 備考 |
|--------|------|------|
| `__init__` | インスタンス初期化 | - 直接は使用不可<br>- プロフィール情報の初期化<br>- エージェントの登録 |
| `create_agent` | エージェント生成 | - 静的メソッド<br>- チェックポイントに記録<br>- エージェント作成の正式な方法 |
| `name` | エージェント名の取得 | - プロパティ<br>- 読み取り専用 |
| `act` | 行動の実行 | - チェックポイントに記録<br>- エージェントの活動を管理 |
| `talk_to` | 他エージェントとの会話 | - メッセージの送信<br>- 対話履歴の記録 |
| `think` | 内部思考の処理 | - 思考プロセスの実行<br>- 内部状態の更新 |
| `ask` | 質問の処理 | - 他エージェントへの問いかけ<br>- 応答の待機 |
| `add_new_action` | 新規アクション追加 | - カスタム機能の追加<br>- 拡張性の提供 |
| `reset` | 状態のリセット | - エージェントの初期化<br>- 履歴のクリア |

注意：この内容は2025年1月時点のものです。実装は変更される可能性があります。