agentl

ウェブサイト · はじめに · コネクター · PyPI · ロードマップ · ディスカッション · X · Instagram

YAML で記述するエージェント型 ETL。 ファイル、API、データベースからデータを読み込み、LLM で各レコードをスキーマに照らして分類または抽出し、データを検証して出力します。レコード単位のキャッシュ、予算、再試行、ライブダッシュボードを標準で備えています。

• レコードごとに一度だけ支払います： 変更のないデータを再実行してもモデル呼び出しは発生せず、ジョブが途中で失敗した場合も、未完了の処理分だけが課金対象になります（実行前と実行後）。
• 信頼できるデータ： 固定ルールによる check ステップと、出力前のエージェントレビューを利用できます。
• データがある場所で動作： CSV、Excel、PDF、SQL、Postgres、S3、SharePoint、Google Sheets、Kafka、SQS、webhook、および Claude Code と Cursor 用の MCP サーバーに対応しています。
• 正直な数値： 純粋な Python との比較を含むベンチマークと評価、および性能が劣るケースも公開しています。

ステータス：ベータ（v0.10）。マイナーリリースで API が変更される場合があります。変更内容はすべて変更履歴に記載しています。

AI エージェント向け： ドキュメントはagentl.com.br/llms.txtにあり、各ドキュメントページには raw Markdown 版（<page>/index.md）があります。

インストール

pip install agentl-etl                 # core: CSV, JSON, HTTP, SQLite, runner, dashboard
pip install 'agentl-etl[office,pdf]'   # Excel, Word, PDF
pip install 'agentl-etl[anthropic]'    # Claude as the LLM provider
pip install 'agentl-etl[all]'

PyPI での配布名は agentl-etl です。インポート名と CLI 名はいずれも agentl です。

パイプライン

name: invoices
llm:
  provider: anthropic          # or "echo" to run offline
  model: claude-opus-5-5

steps:
  - id: invoices
    use: csv.read
    with: { path: data/invoices.csv }

  - id: customers
    use: json.read
    with: { path: data/customers.json }

  - id: matched
    use: join
    input: [invoices, customers]
    with: { left: invoices, right: customers, on: tax_id, how: left }

  - id: classify
    agent: Classify the expense category and flag unknown clients for review.
    input: matched
    output: { number: str, customer: str?, category: str?, needs_review: bool? }

  - id: save
    use: sqlite.write
    input: classify
    with: { db: out/invoices.db, table: invoices }

notify:
  channels:
    slack: { webhook: "${SLACK_WEBHOOK}" }
  rules:
    - on: run.failed
      to: [slack]
      summary: agent             # the LLM explains the failure in 3 lines
    - on: item.rejected
      when: "rate > 0.05"
      to: [slack]

agentl validate pipeline.yaml
agentl run pipeline.yaml --show classify
agentl diagram pipeline.yaml      # Mermaid
agentl dashboard                  # http://127.0.0.1:7070

steps: の代わりに extract:、transform:、load: のセクションを記述することもできます。transform と load の中で input を指定していないステップは、直前のステップから読み込みます。

概念

すべてがステップです。 ステップは入力からレコード（list[dict]）を受け取り、レコードを返します。Extract、transform、load はラベルであり、仕組みが異なるわけではありません。ステップはグラフを構成するため、ETL、ELT、ファンアウト、結合のいずれにも対応できます。

ステップの種類	YAML	用途
コネクター	use: pdf.read	ファイル、API、データベースの読み書き
関数	fn: my_module:clean	独自の決定論的なコード
エージェント	agent: "..." + output:	分類、抽出、正規化、監査などの意味的な処理

エージェントステップはレコードごとに 1 回、並列（concurrency）で実行され、output スキーマ（str、int、float、bool、list[str]、dict。末尾の ? は省略可能であることを示します）の宣言が必須です。出力は検証されます。2 回失敗したレコードは、実行全体ではなくそのレコードのみが拒否され、item.rejected イベントに表示されます。結果は .agentl/agentl.db にレコードごとにキャッシュされるため、クラッシュ後に再実行しても、残りの処理分だけが課金対象になります。

シークレットは環境変数から取得します：${VAR} または ${VAR:-default}。YAML に記述しないでください。

組み込みコネクター

file.read csv.read csv.write json.read json.write txt.read excel.read parquet.read pdf.read docx.read doc.read xml.read html.read http.get http.post sqlite.read sqlite.write select filter dedupe join concat

file.read は形式を検出し、ZIP/GZ アーカイブを展開します。リーダーは path（glob）、url（HTTP ダウンロード）、または上流のレコードを受け付けます。agentl connectors を実行すると、インストール済みのコネクターを確認できます。http.get は URL 内の {field} プレースホルダーを受け付け、上流の各レコードに対してリクエストを送信します。また、items: data.results を指定すると、レスポンスからリストを取り出せます。

拡張

from agentl import connector, register_provider


@connector("crm.contacts")
def contacts(input, since=None):
    return [{"id": 1, "email": "[email protected]"}]

パッケージは agentl.connectors エントリーポイントグループを通じてコネクターを登録できるため、pip install agentl-yourthing だけでインストールできます。LLM プロバイダーは register_provider(name, factory) を使って追加できます。ファクトリーは structured(instruction, record, schema) と text(instruction, content) を備えたオブジェクトを返します。

イベント

ランナーは run.started、step.started、step.succeeded、step.failed、item.rejected、source.empty、run.succeeded、run.failed を発行します。これらのイベントはストア、ダッシュボード、通知ルール（slack、webhook、console）に送られます。

ロードマップ

今後は、pandas ブリッジ、upsert 対応の Postgres、AI エージェント向けドキュメントを予定しています。 全容は公開ロードマップをご覧ください。必要な課題に投票することもできます。

コントリビューション

バグ報告、コネクターのリクエスト、プルリクエストを歓迎します。セットアップ方法と、すべての PR が通過する必要のあるチェックについてはCONTRIBUTING.mdを、脆弱性を非公開で報告する方法についてはSECURITY.mdをご覧ください。 リリース履歴はCHANGELOG.mdにあります。

コントリビューター

agentl の開発に協力してくださった皆さまに感謝します。

参加してみませんか？good first issueのラベルが付いた課題から始めるのがおすすめです。

スポンサー

agentl は無料で、MIT ライセンスのもとで提供されています。時間の節約に役立った場合は、プロジェクトへのスポンサーをご検討ください。

ライセンス

MIT