🤖
GraphAIの紹介

Isamu
2024/06/11に公開
 GraphAIとはGraphAIは、LLM/RAG/Tools/DBなどの複数のAgentを組み合わせて作る、Multi agentsシステムを効率よく構築するためにフレームワークです。
Multi agentsも数個の単純な組み合わせであればプログラムで記述することは容易です。しかし、複雑な組み合わせて、並列実行やデータの依存関係がある場合、並列で動くMulti agentsを作ることは容易ではありません。

最適化を考えないで作れば作ることはできますが、それぞれの処理に数秒かかるAgentを多く組み合わせるとユーザへのアウトプットが極端に遅くなります。また、スケーラビリティや、サーバ、クライアントでの役割、Stream処理など、現在のAIシステムは様々な要求があります。
GraphAIは
複雑な非同期/並列処理とデータの依存関係を解決できる
TypeScriptで書かれていて、ブラウザとサーバの両方で動きます。
Agentは１つのコードでサーバ、ブラウザの両方で動かすことができる
ブラウザから利用する場合、少しの設定を追加するだけでブラウザのAgentを呼び出すだけでサーバでAgentを実行できる
Streamをブラウザ、サーバでサポートする
GraphAIを使うために様々なツールやサンプルが揃っている
といった特徴があります。
GraphAIで使うAgentは
Agentは、それ単体で実装/テストができるので、開発しやすい
Open Sourceで提供されているAgentを利用できる
です。
現在は、receptronという組織で開発をしています。

 Quick Startまずは、簡単にGraphAIを使ってみましょう。npmの環境とOpenAIのapi keyを用意してください。
そして、GraphAI の cliをインストールします。
npm i -g  @receptron/graphai_cli
以下のyamlファイル(Graphデータ)をダウンロードして保存してください。
https://raw.githubusercontent.com/receptron/graphai/refs/heads/main/packages/samples/graph_data/openai/business_idea_jp.yaml
そのファイルを保存したディレクトリーに.envというファイルをつくってOpenAIのAPI KEYを記述します。
OPENAI_API_KEY=sk-xxxx
用意は以上です。実行します。
graphai business_idea_jp.yaml
成功していれば、何も表示されないでしばらくまちます。
しばらくすると、「このビジネスアイデアコンテスト」のアイデア、評価、結果が表示されます。
yamlファイルをみると流れはわかると思いますがOpenAIのGPTに問い合わせるAgentが３回実行されています。

GPT(AI)への問い合わせと、その結果を使って更に問い合わせをするという流れです。
問い合わせの内容を変更すると、ビジネスアイデア以外の結果を得ることができるので、改良して使ってみてください。
このように、yamlファイルに定義することで、簡単にAIを使ったAgentを組み合わせて動かすことが可能となります。

 Sample
 yamlのサンプルgraphaiのcliコマンドで実行できるyamlサンプルです。@receptron/graphai_cliがインストール済みであれば
graphai {filename}
で実行できます。
https://github.com/receptron/graphai/tree/main/packages/samples/graph_data

 tsのサンプルtypescriptで書かれたサンプルです。ソースをcloneして、それぞれのディレクトリーで以下のコマンドで実行できます。
yarn run samples {sampleFile}
https://github.com/receptron/graphai/tree/main/packages/samples/src

 簡単なGraphAIの使い方こちらのチュートリアルを参考にしてください。英語ですが、ほとんどがソースなので翻訳を使いながらでも簡単に理解できます。
公式チュートリアル
このチュートリアルは、graphai_cliを使ってCliでyamlを読み込んでGraphAIを使います。

graphai_cliはGraphAI本体と、@graphai/agentsを含んでいて、全てのAgentを利用できます。

 GraphAIの簡単な動作の流れyamlやjson,TypeScriptで記述されたGraphデータを読み込む
Graphデータに矛盾がないかvalidationをする。矛盾があればエラーで終了
全てのComputed nodeをタスクキューに入れて、依存がないNodeから実行する
１つのNodeの実行が終わると、それに依存し、他のタスク待ちがないNodeを探し、見つかればそのNodeが実行される。ただし並列動作の上限に達した場合には実行待ちとなる。
AgentFilterが設定されている場合、各Nodeの実行前にAgentFilterが実行される
全てのNodeの実行が終わるとisResultで指定されたNodeの結果が返される。Loop指定がある場合は、最初から実行される。

 GraphAIのNode.jsで使い方GraphAIを動作させるのに必要な最小限のnpmはgraphaiといずれかのagentです。

最も簡単に使えるAgentのvanilla agents(@graphai/vanilla 他に依存がないagentをvanillaと呼んでいます)を使って簡単なGraphデータを作り、動かしてみます。
最初にnpmの初期化をして、必要なnpmを入れます。typescriptを実行するためにts-nodeも入れます。
npm init
yarn add graphai @graphai/vanilla ts-node
以下が最小限のスクリプトです。graphai.tsで保存します。

Static nodeのnode1でメッセージを指定して、そのデータを受け取ったComputed nodeのnode2でcopyAgentを実行します。

node2の結果を出力としてかえします。
import { GraphAI } from "graphai";
import * as agents from "@graphai/vanilla";

const graph_data = {
  version: 0.5,
  nodes: {
    node1: {
      value: "hello, GraphAI",
    },
    node2: {
      agent: "copyAgent",
      inputs: {text: ":node1"},
      isResult: true,
    },
  },
};

export const main = async () => {
  const graph = new GraphAI(graph_data, agents);
  const result = await graph.run();
  console.log(JSON.stringify(result));

};

if (process.argv[1] === __filename) {
  main();
}
実行します
$ npx ts-node graphai.ts
{"node2": {text: "hello, GraphAI"}}
node1で指定して文字列がnode2に渡され、結果として表示されました。

 WebのサンプルVue3で書かれたwebのサンプルです。
https://github.com/receptron/graphai-demo-web
サンプルサイト

https://graphai-demo.web.app/

 WebのサンプルStream編LLMをサーバで動かし、そのレスポンスをstreamで受け取るサンプルです。

サーバ側、クラアント側、両方でstreamをサポートしています。
クライアント
https://github.com/isamu/graphai-stream-web
サーバ
https://github.com/receptron/graphai-agent-server
localで動作します。
両方のレポジトリをclone
root directorynpmのinstall.
yarn install
vueの起動
yarn run serve
serverの起動
yarn run server
で利用できます。

 レポジトリとnpm構成
 ソースコードhttps://github.com/receptron/graphai
にあります。このレポジトリはモノレポとなっていて、GraphAI本体の他に、各種ツールやAgentが含まれます。

packagesディレクトリ
GraphAI本体とcliやテスト用の各種ツール、AgentFilter,全てのAgentを利用できるagentのメタパッケージなど


agentsディレクトリ
GraphAIで利用するagentsがそれぞれの分類ごとに分かれておいてある

各packages/agents以下のディレクトリはそれぞれのnpmのパッケージとして提供されています。
GraphAI本体は https://github.com/receptron/graphai/blob/main/packages/graphai/src/ 以下の

graphai.ts
GraphAI本体


node.ts
Agentと対応するNode


task_manager.ts
並列処理を含むAgentの実行を管理するタスクマネージャー


type.ts
型定義

の４つのファイルで、合わせても1000行程度とコンパクトに作られています。
本体以外にAgent/AgentFilter/Validator/GraphAIの機能を拡張するAgent(nestしたGraphやGraphを並列で動かす）などを組み合わせて使うため、シンプルなエンジンで複雑な処理を行うことが可能となります。

 npm packagenpmパッケージは以下で配布しています。

 GraphAI本体https://www.npmjs.com/package/graphai

 GraphAI関連ツールreceptronのorganization配下で、ツールを提供しています。
yamlやjsonをcliで読み込んで使うツールやexpressのmiddlewareなどがあります。
receptron organization

 Agentsgraphai organization下で、Agentを配布しています。

@graphai/agents
配布している全てのパッケージを盛り込んだメタパッケージ。
含まれるパッケージは、ここのソースを参照してください


@graphai/vanilla
他のnpmに依存しないagent群
nestedGraph
arrayの処理
データ処理
文字列やjsonの変換



@graphai/service_agents
wikipediaやfetchなどネットワークサービスを使うagent.


@graphai/llm_agents
LLMのagent. LLMをapi経由で使うのにAPI KEYが必要になります。サーバで使うことを想定しています。


@graphai/data_agents
データ加工用のAgent. vanillaに入れなかった依存関係のあるパッケージ


 用語説明Graph
円グラフや棒グラフのグラフではなく、グラフ理論のグラフ。NodeとそれをつなぐEdgeで、それぞれのNodeの関連性を示す

GraphAI
GraphAI本体

Graphデータ
GraphAIで使うGraphを定義したデータ。グラフ理論のNodeはnodeとして、edgeはinputsで定義される。グラフは有向グラフで閉loopなし。
yaml, jsonファイルで定義したり、TypeScriptで直接記述も可能。

Agent
GraphAIで実行されるプログラム。各Node(Computed Node)は１つのAgentと対応し、実行する。同じAgentを複数のNodeで使うこともできる。LLMを実行するLLM Agentや、データを処理するpopAgent, stringAgentなどがある。TypeScriptで記述する

Node
GraphのNode。Static NodeとComputed Nodeの２種類がある。

Static Node
データのみを扱うNode。初期値を定義したり、loop(同じグラフを繰り返し処理する）時に、前回実行した結果をデータとして受け取る。

Computed Node
Agentに対応したNode。プログラムを実行する

Agent Filter
各Agentを実行する前に実行されるプログラム。共通の処理、AgentのデータのValidation, stream処理などができる。

Node.js
JavaScriptの実行環境。GraphAIのnodeと混同しそうなので、Node.jsと表記します。


 Graphデータの作り方
 echoAgentを使った簡単なGraphの作成echoAgent(指定されたデータを出力するAgent)を使って、簡単なGraphファイルを作ります。

GraphAIのGraphファイルの必須項目はversionとnodesです。
versionは、0.5を指定します。(2024/06現在)
nodesは、GraphAIで使う各ノードを書いていきます。

このサンプルではnodesにechoAgentを使った１つのnodeを追加します。

echoAgentはparamsで指定しているユーザからの入力値をそのまま返すAgentです。
追加するnodeは、node1というNode名をつけます。

このnodeはmessage: helloというデータを出力します。
このサンプルのYAMLは１つしかnodeがありませんが、結果を返すnodeはnode1なので、isResult: trueを追加し、このnodeの結果がこのGraphの結果と指定します。
version: 0.5
nodes:
  node1: 
    params:
      message: hello
    agent: echoAgent
    isResult: true
   
これをecho.yamlというファイル名で保存して、graphaiのcliで実行します
$ graphai echo.yaml 
{ node1: { message: 'hello' } }
2行目のmessage: helloが表示されていれば成功です。

 inputsを追加する次に複数のAgentを組み合わせ、inputsで入力を指定したYAMLを作ります。

入力を指定することで依存関係が定義でき、それによって実行順が制御されます。
copyAgentは入力値をそのまま出力値で返すAgentです。

先程のechoAgentのyamlにnode2を追加します。node2のagentはcopyAgentを指定します。

入力のinputsとして、前のnode1を指定します。inputsは文字列の配列で、node名を指定します。
今回は出力はcopyAgentのnode2なので、node2にisResult: trueを指定します。node1のisResultは削除します。
version: 0.5
nodes:
  node1: 
    params:
      message: hello
    agent: echoAgent
  node2: 
    agent: copyAgent
    inputs:
      text: ":node1.message"
    isResult: true
実行される順に説明すると、
node1のechoAgentが実行され、paramsの値を結果として返す
node1を入力としているnode、node2が実行される。node2の入力値はnode1の実行結果で、それを入力としてうけとる。node2のcopyAgentは入力値をそのまま結果として返すagentなので、node1の結果をそのまま返す。
これを実行するとnode2の結果としてtext: 'hello'が表示されます。

また結果はarrayになっています。
 $ graphai echo2.yaml
{ node2: { text: 'hello' } }
同じように、今度は入力を増やして試してみます。

node1と同じechoAgentをnode2とし、copyAgentをnode3にします。
入力のinputsは今度は array: [":node1", ":node2"]と２つ指定します。
node3がisResult: trueです。
version: 0.5
nodes:
  node1: 
    params:
      message: hello
    agent: echoAgent
  node2: 
    params:
      message: こんにちは
    agent: echoAgent
  node3: 
    agent: copyAgent
    inputs:
      array:
        - ":node1.message"
        - ":node2.message"
    isResult: true
$ graphai echo3.yaml
{ node3: { array: ['hello', 'こんにちは'] }}
node3の結果として、２つの入力値がそのまま出力されます
このようにinputsを使って、複数のエージェントをつなげていくことができます。
inputsを持つagentは、入力となるnode1, node2のagentの実行結果を待ってから実行します。

入力のagentがデータベースに接続したり、APIを叩くような時間のかかる処理の場合でも、その前の処理が終わるのを待ってから実行されます。

 Agentのdocument各AgentのAgentFunctionInfoに書かれた情報を元に、機械的に生成したdocumentがAgentDocにあります。

 AgentFunctionInfoについてnpmで配布されるagentは、実行されるagentの関数と、そのAgentの情報を含むAgentFunctionInfoの形式配布されます。
AgentFunctionInfoには、Agentの情報(nameやdescription)、サンプルの入出力、入力のスキーマなどの情報が含まれています。Sampleはドキュメントの自動生成やUnit testにも使われます。
Agentを作成してGraphAIで利用するときは、AgentFunctionInfoを作る必要があります。
(* 簡易的にagentを即時関数で使う方法や、AgentFunctionInfoのモックデータを使うなど、開発時には省略する方法もあります。別途説明予定）

 Agentの開発方法GraphAIで使うAgentの作り方の説明をします。
こちらのサンプルのagentのレポジトリがあります。

https://github.com/isamu/graphai_agent_template
Agentは、Agentの本体とそれをテストするテストコードで構成されます。

Agentの本体をsrc/以下(今回はsrc/sample_agent.ts), Agentのテストコードをtest/以下(今回はtests/test_agent.ts)に作ります。
今回作成するAgentはSampleAgentという名前です。

動作は、GraphAIからの入力値(設定ファイルのparams)のparamsと、前のagentからの入力値inputs、この２つの値をmergeしてobjectとして返す簡単なAgentです。

 AgentAgentの本体はこちらです。
import { AgentFunction } from "graphai";

export const sampleAgent: AgentFunction = async ({ params, inputs }) => {
  return { params, inputs };
};
Agentは必ずAgentFunctionの型で、非同期(async)な関数です。

最初の説明にあったように、paramsと入力をとって、それを返すだけのコードです。
どんなAgentも基本的にはこのように入力値を受け取って、何らかの結果を返す１つの関数です。

 AgentFunctionInfoAgentは、AgentFunctionInfoの型のデータとしてGraphAIにわたす必要があります。

AgentFunctionInfoはAgent本体とinputs/params/resultのサンプルの値、Agentのメタ情報を含みます。
src/sample_agent.tsに追加します。
// for test and document
以下にテストのサンプル値と、このAgentの情報(AgentFunctionInfo)を記載しています。

これらをsampleAgentInfoにまとめてexportします。
サンプル値はUnit Test(つまり、サンプルのドキュメントとUnit Testの両方を兼ねています）で使います。

後述する開発時にはこのサンプル値を使ってTestRunnerでテストをします。
Agentのファイルは、agentを含むパッケージ情報(AgentFunctionInfo)をdefaule exportします。
import { AgentFunctionInfo } from "graphai";

const sampleInput = [{message: "hello"}, {message: "test"}];
const sampleParams = { sample: "123" };
const sampleResult = { inputs: sampleInput, params: sampleParams };

const sampleAgentInfo: AgentFunctionInfo = {
  name: "sampleAgent",
  agent: sampleAgent,
  mock: sampleAgent,
  inputs: {
    type: "array",
  },
  samples: [
    {
      inputs: sampleInput,
      params: sampleParams,
      result: sampleResult,
    },
  ],
  description: "Sample agent",
  author: "isamu arimoto",
  repository: "https://github.com/isamu/graphai_doc",
  license: "MIT",
};

export default sampleAgentInfo;

複数のサンプル値を用意する場合は
  samples: [
    {
      inputs: sampleInput,
      params: sampleParams,
      result: sampleResult,
    },
    {
      inputs: sampleInput2,
      params: sampleParams2,
      result: sampleResult2,
    },
  ],
とします。

複数のサンプル値があるときはテストランナーは全てのケースをテストします。

 Unit TestAgentのパッケージの情報を使ってAgent単体のUnit Testをします。

GraphAIに含まれるagentTestRunnerにsampleAgentInfoを渡してUnit Testを実行します。

agentTestRunnerは、sampleAgentInfoに含まれるサンプル値を使ってAgentを実行します。

この関数は、内部でnode:testを使っています。

inputs, paramsのペアを使ってAgentを実行、結果とresultが一致すればテストは成功です。
import sampleAgentInfo from "@/sample_agent";
import { agentTestRunner } from "@receptron/test_utils";

agentTestRunner(sampleAgentInfo);
package.jsonにテスト実行のスクリプトがあるので
yarn run test
でテストを実行します。

 開発最初にAgentを開発するとき、このレポジトリをforkして使うと良いです。

Agent作成に必要な設定は package.json, eslintrc.js, .prettierrc, tsconfig.json に設定済みです
src/sample_agent.tsをベースに必要な実装を追加していき、期待すべきsamplesを更新、追加しながらUnit Testを動かします。

Unit TestをPassし、期待すべき動作がするようになればAgentは完成です。

 Agentの受け取るデータsampleAgentでは、Agentの関数で{ params, inputs }を受け取りました。

実際はAgentFunctionContextの情報を受け取っています。
params
GraphDataのyaml/jsonのparamsで与えられる値

inputs
GraphDataのinputsで指定される値。前に実行したAgentの結果や、static nodeでの値、inputsに書かれた値など。
inputsはArrayで、入力の数と同じ長さ。

namedInputs
inputsのobject(dictonary)時

基本的にはこのうちの２つ(paramsと(inputs or namedInputs))を入力として受け取り、Agentの処理をします。結果はreturnで返します。

Agentの結果は、次に実行されるAgentのinputsなどで利用されます。(inputの記述方法は別途解説します)
inputsとinputsはGraphDataで
inputs: [":node1", ":node2"] とarrayにした場合はinputs,
inputs: {v1: ":node1", v2: ":node2"} とした場合にはobjectでnamedInputs

が渡されます。同時に２つがくることはありません。
agentFilters
AgentFilterという仕組みを使う場合に使う
debugInfo
debug時などに必要な情報
で、それ以外はNestedGraphで使う特別なデータなので、通常は利用しません。

 Agentのdocument生成とテストAgentFunctionInfoに含まれる方法を使って、agentのunit testを実行する、documentを自動生成することが可能です。
Test runnerは、@receptron/test_utilsに含まれています。
import { agentTestRunner } from "@receptron/test_utils";

const main = async () => {
  await agentTestRunner(agentFunctionInfo);
};

main();
Documentの自動生成はこちらを参考に。今後、利用しやすい形式で提供予定です。
https://github.com/receptron/graphai/blob/main/packages/cli/src/docs.ts

 AgentFilterAgentFilterは、それぞれのComputed Nodeが実行される前に、なにかの処理を追加することができます。
@graphai/agent_filtersではhttpのstreamのためのfilterや、AgentFunctionInfoのinput schemaを使った入力値のvalidateを行うagent filterがあります。

 namedInput ValidatornamedInputの値をagentFunctionInfoのinput schemaの情報を元にvalidationします
Testコードでの利用例

https://github.com/isamu/graphai/blob/agentFilter/packages/agent_filters/tests/validation/test_agent_namedinput_validator.ts
import { GraphAI } from "graphai";
import * as agents from "@graphai/agents";
import { namedInputValidatorFilter } from "@graphai/agent_filters";

const agentFilters = [
  {
    name: "namedInputValidatorFilter",
    agent: namedInputValidatorFilter,
  },
];

const graph = new GraphAI(graph_data, agents, { agentFilters });
const results = await graph.run();


 streamAgentFilterGeneratorfilterParamsのstreamTokenCallback関数を通してstreamのデータを受信します。

サーバ、クライアントで利用可能です。

 server 例https://github.com/receptron/graphai_utils/blob/main/packages/express/src/express.ts
express server
    return async (req: express.Request, res: express.Response) => {
      res.setHeader("Content-Type", "text/event-stream;charset=utf-8");
      res.setHeader("Cache-Control", "no-cache, no-transform");
      res.setHeader("X-Accel-Buffering", "no");

      const callback = (context: AgentFunctionContext, token: string) => {
        if (token) {
          res.write(token);
        }
      };
      const streamAgentFilter = {
        name: "streamAgentFilter",
        agent: streamAgentFilterGenerator<string>(callback),
      };
      const agentFilters = [streamAgentFilter]

      const agentFilterRunner = agentFilterRunnerBuilder(agentFilters);
      const result = await agentFilterRunner(context, agent.agent);

      const json_data = JSON.stringify(result);
      res.write("___END___");
      res.write(json_data);
      return res.end();
   }

 web clienthttps://github.com/isamu/graphai-stream-web/blob/main/src/views/Home.vue
const useAgentFilter = (callback: (context: AgentFunctionContext, data: T) => void) => {
  const streamAgentFilter = streamAgentFilterGenerator(callback);

  const agentFilters = [
    {
      name: "streamAgentFilter",
      agent: streamAgentFilter,
      agentIds: streamAgents,
    },
  ];
  return agentFilters;
};   

export default defineComponent({
  setup() {
    const streamingData = ref<Record<string, unknown>>({});

    const callback = (context: AgentFunctionContext, data: string) => {
      const { nodeId } = context.debugInfo;
      streamingData.value[nodeId] = (streamingData.value[nodeId] ?? "") + data;
    };
    const agentFilters = useAgentFilter(callback);
    
    const graphai = new GraphAI(graphData, agents, { agentFilters });
  }
})

 httpAgentFilterグラフのフローで、agentの実行をバイパスし、http経由でサーバのagentを実行します。

Webでのサンプルはこちらにあります。
https://github.com/isamu/graphai-stream-web/blob/main/src/views/Home.vue

 agentFilterRunnerBuilderGraphAIを使わないでagentFilterとagentを動かすRunnerです。

クライアントからサーバのagentを呼び出すときに、サーバ側で使います。

agentFilterやagentの単体テストでも利用可能です。
expressとtest時のサンプルはこちら。
express

https://github.com/receptron/graphai_utils/blob/main/packages/express/src/express.ts
test

https://github.com/isamu/graphai/blob/agentFilter/packages/agent_filters/tests/filters/test_filter_runner.ts

 関連レポジトリ
 GraphAI visual programinghttps://github.com/receptron/graphai-litegraph/

 GraphAI Python Agent serverhttps://github.com/receptron/graphai_python_server

 GraphAI PlayGroundhttps://github.com/receptron/graphai-playground
シンギュラリティ・ソサエティPublication
人工知能を活用したアプリケーションやサービスを活用し、内発的動機付けで行動するエンジニア、起業家、社会起業家をサポートするコミュニティーです。 singularitysociety.org
GraphAIとは

Quick Start

Sample

yamlのサンプル

tsのサンプル

簡単なGraphAIの使い方

GraphAIの簡単な動作の流れ

GraphAIのNode.jsで使い方

Webのサンプル

WebのサンプルStream編

レポジトリとnpm構成

ソースコード

npm package

GraphAI本体

GraphAI関連ツール

Agents

用語説明

Graphデータの作り方

echoAgentを使った簡単なGraphの作成

inputsを追加する

Agentのdocument

AgentFunctionInfoについて

Agentの開発方法

Agent

AgentFunctionInfo

Unit Test

開発

Agentの受け取るデータ

Agentのdocument生成とテスト

AgentFilter

namedInput Validator

streamAgentFilterGenerator

server 例

web client

httpAgentFilter

agentFilterRunnerBuilder

関連レポジトリ

GraphAI visual programing

GraphAI Python Agent server

GraphAI PlayGround

Discussion
