GraphAI 0.5.23 ユーザーガイド：CLI オプションと実行結果

# はじめに

GraphAI コマンドラインツールを実行したとき、色々とオプションあるのですが、詳細解説したものを見つけられなかったので備忘録かねて本記事作成します。

```
$ graphai
graphai <yaml_or_json_file>

run GraphAI with GraphAI file.

Positionals:
      --yaml_or_json_file  yaml or json file                            [文字列]

オプション:
      --help     ヘルプを表示                                             [真偽]
      --version  バージョンを表示                                         [真偽]
  -l, --list     agents list
  -s, --sample   agent sample data                                      [文字列]
  -d, --detail   agent detail                                           [文字列]
  -v, --verbose  verbose log                   [真偽] [必須] [デフォルト: false]
  -a, --all      all result                    [真偽] [必須] [デフォルト: false]
  -m, --mermaid  mermaid                       [真偽] [必須] [デフォルト: false]
      --yaml     dump yaml                     [真偽] [必須] [デフォルト: false]
      --json     dump json                     [真偽] [必須] [デフォルト: false]
      --log      output log                                             [文字列]

オプションではない引数が 0 個では不足しています。少なくとも 1 個の引数が必要です:
```

なおインストール方法については以下の記事を参考にしてください。

https://qiita.com/t_narita/items/4fa82f66f8c773e91394

# オプション一覧

## --help     ヘルプを表示

- 説明
ヘルプを表示します。  

- 使用例
    ```bash
    $ graphai --help
    graphai <yaml_or_json_file>
    
    run GraphAI with GraphAI file.
    
    Positionals:
          --yaml_or_json_file  yaml or json file                            [文字列]
    
    オプション:
          --help     ヘルプを表示                                             [真偽]
          --version  バージョンを表示                                         [真偽]
      -l, --list     agents list
      -s, --sample   agent sample data                                      [文字列]
      -d, --detail   agent detail                                           [文字列]
      -v, --verbose  verbose log                   [真偽] [必須] [デフォルト: false]
      -a, --all      all result                    [真偽] [必須] [デフォルト: false]
      -m, --mermaid  mermaid                       [真偽] [必須] [デフォルト: false]
          --yaml     dump yaml                     [真偽] [必須] [デフォルト: false]
          --json     dump json                     [真偽] [必須] [デフォルト: false]
          --log      output log                                             [文字列]
    narita@naritanoMacBook-Pro ~ % 
    ```

## --version  バージョンを表示

- 説明
バージョンを表示します。  

- 使用例
    ```bash
    $ graphai --version
    0.5.23
    ```
    
## -l, --list     agents list

- 説明
利用可能なエージェントを表示します。  

- 使用例
    ```bash
    $ graphai -l       
    Available Agents
    * anthropicAgent - Anthropic Agent
    * arrayFlatAgent - Array Flat Agent
    * arrayJoinAgent - Array Join Agent
    * compareAgent - compare
    * copy2ArrayAgent - Copy2Array agent
    * copyAgent - Returns namedInputs
    * copyMessageAgent - CopyMessage agent
    * countingAgent - Counting agent
    * dataObjectMergeTemplateAgent - Merge object
    * dataSumTemplateAgent - Returns the sum of input values
    * dotProductAgent - dotProduct Agent
    * echoAgent - Echo agent
    * fetchAgent - Retrieves JSON data from the specified URL
    * geminiAgent - Gemini Agent
    * groqAgent - Groq Agent
    * jsonParserAgent - Template agent
    * mapAgent - Map Agent
    * mergeNodeIdAgent - merge node id agent
    * nestedAgent - nested Agent
    * openAIAgent - OpenAI Agent
    * openAIImageAgent - OpenAI Image Agent
    * popAgent - Pop Agent
    * propertyFilterAgent - Filter properties based on property name either with 'include', 'exclude', 'alter', 'swap', 'inject', 'inspect'
    * pushAgent - push Agent
    * replicateAgent - Replicate Agent
    * shiftAgent - shift Agent
    * slashGPTAgent - Slash GPT Agent
    * sleepAndMergeAgent - sleeper and merge Agent
    * sleeperAgent - sleeper Agent
    * sleeperAgentDebug - sleeper debug Agent
    * sortByValuesAgent - sortByValues Agent
    * streamMockAgent - Stream mock agent
    * stringEmbeddingsAgent - Embeddings Agent
    * stringSplitterAgent - This agent strip one long string into chunks using following parameters
    * stringTemplateAgent - Template agent
    * textInputAgent - Text Input Agent
    * tokenBoundStringsAgent - token bound Agent
    * totalAgent - Returns the sum of input values
    * vanillaFetchAgent - Retrieves JSON data from the specified URL
    * wikipediaAgent - Retrieves data
    ```

##   -s, --sample   agent sample data

- 説明
エージェントのサンプルデータを表示します。

- 使用例
    ```
    narita@naritanoMacBook-Pro ~ % graphai -s echoAgent
    * echoAgent
    [
      {
        "inputs": {},
        "params": {
          "text": "this is test"
        },
        "result": {
          "text": "this is test"
        }
      },
      {
        "inputs": {},
        "params": {
          "text": "If you add filterParams option, it will respond to filterParams",
          "filterParams": true
        },
        "result": {}
      }
    ]
    ```

##   -d, --detail   agent detail
- 説明
エージェントの詳細を表示します。

- 使用例
    ```
    $ graphai -d echoAgent
    * echoAgent
    echoAgent - Echo agent
    Author Satoshi Nakajima
    Repository https://github.com/receptron/graphai
    Licence MIT
    ```

##   -v, --verbose  verbose log

- 説明
エージェントの詳細を表示します。

- 使用例
    ```
    $ cat hello_world.yaml
    version: 0.5
    nodes:
      node1: 
        params:
          message: hello
        agent: echoAgent
        isResult: true

    # 通常の実行
    $ graphai hello_world.yaml 
    {
        "node1": {
            "message": "hello"
        }
    }
    
    # オプション付きで実行した場合
    $ graphai -v hello_world.yaml
    node1      queued
    node1      =>( []
    node1      {}  {"message":"hello"}
    {
      "node1": {
        "message": "hello"
      }
    ```

##   -a, --all      all result
- 説明
すべての結果を表示します。

- 使用例
    ```
    $ cat hello_world.yaml
    version: 0.5
    nodes:
      node1: 
        params:
          message: hello
        agent: echoAgent
        isResult: false  # falseに変更して表示されないようにする
    
    # 通常実行
    $ graphai hello_world.yaml 
    {}
    
    # オプション付きで実装
    $ graphai -a hello_world.yaml 
    {
      "node1": {
        "message": "hello"
      }
    }
    ```

##   -m, --mermaid  mermaid

- 説明
すべての結果を表示します。

- 使用例
    ```
    $ cat map_agent.yaml 
    version: 0.5
    nodes:
     source:
       value:
         fruits:
           - apple
           - orange
           - banana
           - lemon
           - melon
           - pineapple
           - tomato
     nestedNode:
       agent: mapAgent
       inputs:
         rows: :source.fruits
       graph:
         version: 0.5
         nodes:
           node2:
             agent: stringTemplateAgent
             params:
               template: I love ${m}.
             inputs:
               m: :row
             isResult: true
       params:
         compositeResult: true
     result:
       agent: sleepAndMergeAgent
       inputs:
         array:
           - :nestedNode.node2
       isResult: true

    $ graphai -m map_agent.yaml
    flowchart TD
     source(source) -- fruits --> nestedNode
     nestedNode(nestedNode) -- node2 --> result
    ```

##       --yaml     dump yaml

- 説明
yaml形式で出力します。

- 使用例
    ```
    $ cat hello_world.json 
    {
      "version": 0.5,
      "nodes": {
        "node1": {
          "params": {
            "message": "hello"
          },
          "agent": "echoAgent",
          "isResult": true
        }
      }
    }

    $ graphai --yaml hello_world.json                   
    version: 0.5
    nodes:
      node1:
        params:
          message: hello
        agent: echoAgent
        isResult: true
    ```

##       --json     dump json

- 説明
json形式で出力します。

- 使用例
    ```
    $ cat hello_world.yaml 
    version: 0.5
    nodes:
      node1: 
        params:
          message: hello
        agent: echoAgent
        isResult: true

    $ graphai --json hello_world.yaml
    {
      "version": 0.5,
      "nodes": {
        "node1": {
          "params": {
            "message": "hello"
          },
          "agent": "echoAgent",
          "isResult": true
        }
      }
    }
    ```

##       --log      output log

- 説明
ログを出力します。

- 使用例
    ```
    $ cat hello_world.yaml 
    version: 0.5
    nodes:
      node1: 
        params:
          message: hello
        agent: echoAgent
        isResult: true

    # オプションを付与して実行
    $ graphai --log log.txt hello_world.yaml 
    {
      "node1": {
        "message": "hello"
      }
    }

    # ログファイルが生成されてる
    $ cat log.txt 
    [
      {
        "nodeId": "node1",
        "state": "completed",
        "agentId": "echoAgent",
        "params": {
          "message": "hello"
        },
        "isLoop": false,
        "repeatCount": 0,
        "startTime": 1733713460531,
        "inputs": [],
        "result": {
          "message": "hello"
        },
        "resultKeys": [
          ":echoAgent",
          ":echoAgent.message"
        ],
        "endTime": 1733713460532
      },
      {
        "nodeId": "node1",
        "state": "completed",
        "agentId": "echoAgent",
        "params": {
          "message": "hello"
        },
        "isLoop": false,
        "repeatCount": 0,
        "startTime": 1733713460531,
        "inputs": [],
        "result": {
          "message": "hello"
        },
        "resultKeys": [
          ":echoAgent",
          ":echoAgent.message"
        ],
        "endTime": 1733713460532
      },
      {
        "nodeId": "node1",
        "state": "completed",
        "agentId": "echoAgent",
        "params": {
          "message": "hello"
        },
        "isLoop": false,
        "repeatCount": 0,
        "startTime": 1733713460531,
        "inputs": [],
        "result": {
          "message": "hello"
        },
        "resultKeys": [
          ":echoAgent",
          ":echoAgent.message"
        ],
        "endTime": 1733713460532
      }
    ]
    ```


# 参考サイト
GraphAI cli🤖
https://github.com/receptron/graphai/blob/main/packages/cli/README.md