Agent 概要

Agent は Elftia の主要機能の一つです。AI を受動的に質問へ答えるだけの存在から、能動的にタスクを実行する存在へと引き上げます。ファイルの読み書き、コマンドの実行、Web 検索、外部ツールの呼び出し、さらには複数のサブ Agent を並列に連携させることもできます。

Agent とは

従来のチャットでは、AI はテキストを生成することしかできません。Agent モードでは、AI は以下を実行できます。

1. タスクを分析する — リクエストを理解し、実行計画を立てる
2. ツールを呼び出す — ファイルを読み込み、コードを編集し、コマンドを実行する
3. 反復する — 結果を確認し、エラーを修正し、実行を継続する
4. 結果を返す — タスクが完了したら最終応答を提供する

この「考える → 行動する → 観察する → もう一度考える」というサイクルを Agent Loop と呼びます。

User message → Engine dispatch → LLM thinks → Tool call → Observe result → Continue loop or return reply
                                      ↑                                           ↓
                                      └───────────────────────────────────────────┘

マルチエンジンアーキテクチャ

Elftia は複数の Agent エンジンをサポートしており、それぞれ異なるシナリオに適しています。

エンジン種別	ID	説明	最適な用途
TinyElf	tinyelf	Elftia 組み込みの軽量 Agent エンジン	日常的なコーディング、ファイル操作、自動化タスク
Claude SDK	claude-sdk	Anthropic 公式 Agent SDK ベース	Claude のネイティブツールチェーンが必要なシナリオ
CLI Runner	cli	外部コマンドラインツール（Claude Code、Codex）	外部 CLI Agent の使用
Chat	chat	純粋なチャットエンジン（ツール呼び出しなし）	シンプルな Q&A、翻訳、文章作成
STChat	st-chat	シングルターン会話エンジン	高速なシングルターンタスク
API	api	軽量 API 呼び出し	メディア生成などの非チャットシナリオ

TinyElf エンジン

TinyElf は Elftia のデフォルト Agent エンジンで、以下の特徴があります。

• プロセス内実行 — サブプロセスやプロキシサーバーを起動する必要がなく、素早く開始できます
• マルチ LLM 対応 — TinyElfLLMAdapter を通じて任意の LLM プロバイダーに適応します
• 組み込みツールチェーン — ファイルの読み書き、シェルコマンド、Web 検索、MCP ツール
• サブ Agent 連携 — フォアグラウンドおよびバックグラウンドのサブ Agent の並列実行をサポートします
• スキルシステム — 再利用可能な SKILL.md スキル指示を読み込めます
• セキュリティ制御 — 3 層のセキュリティ（ファイアウォール + ガーディアン Agent + 権限確認）

Claude SDK エンジン

@anthropic-ai/claude-agent-sdk ベースで、Claude のネイティブ機能が必要なシナリオに適しています。

• Claude の公式プリセットシステムプロンプトとツールを使用します
• 非 Anthropic プロバイダーをサポートします（形式変換用の組み込みプロキシサーバー経由）
• 複数 API キーによる負荷分散

CLI Runner エンジン

ProcessSupervisor を通じて外部 CLI ツールプロセスを管理します。

• Claude Code CLI と Codex CLI をサポートします
• PTY ターミナルモードと標準サブプロセスモード
• 自動タイムアウト処理と出力解析

主要機能

ツール呼び出し

Agent はさまざまなツールを使用してタスクを完了できます。

ツールカテゴリ	ツール	説明
ファイルシステム	Read, Write, Edit, ListDir, Glob, Grep	プロジェクトファイルの読み書きと検索
シェル	Bash	ターミナルコマンドを実行
Web	WebSearch, WebFetch	Web コンテンツを検索・取得
サブ Agent	spawn_agent	サブタスクを処理するサブ Agent を起動
セッション管理	SessionsSpawn, SessionsList, SessionsSend	セッションをまたいだ連携
スキル	list_skills, read_skill	スキル内容の表示と読み込み
MCP	mcp__*（動的に読み込み）	外部 MCP サーバーツール
制御	Notify, SessionsYield	通知とフロー制御

サブ Agent 連携

Agent はサブ Agent を起動して、サブタスクを並列に処理できます。

• フォアグラウンドサブ Agent — ブロックして結果を待機し、親 Agent に直接返します
• バックグラウンドサブ Agent — バックグラウンドで非同期実行され、完了時に結果が親ループへ注入されます
• Agent 設定の継承 — サブ Agent は親 Agent の MCP ツールとスキルを継承できます
• セキュリティの継承 — サブ Agent は親 Agent のセキュリティ設定と権限モードを継承します

スキルシステム

スキルは、SKILL.md ファイルとして存在する再利用可能な指示セットです。

• プロジェクトスキル — .claude/skills/ に配置され、プロジェクト内で共有されます
• 個人スキル — ~/.claude/skills/ に配置され、グローバルに利用できます
• コミュニティスキル — SkillHub から検索してインストールできます

Agent ギャラリー

Elftia には、さまざまなシナリオをカバーする事前設定済み Agent が用意されています。

• プログラミングアシスタント、コードレビュー、テスト作成
• ドキュメント作成、翻訳と校正
• 調査分析、データ処理
• タスク自動化、ワークフローオーケストレーション

Agents ページ: フラットな単層モデル

バージョン 0.1.7 で 2 段階のマージが完了し、「Persona / Avatar / Agent の 3 層構造」はなくなりました。すべての Agent は Agents ページ（/agents）の単一グリッドで管理されます。

1 つの Agent = 1 つの独立した会話対象

ページレイアウト:

• 左カテゴリバー: 13 カテゴリ（Featured、My、Work、Coding、Creative、Research、Writing、Life、Education、Entertainment、Social、Automation、Tools）
• 上部検索: Agent 名 / 説明 / タグで一致
• 右グリッド: すべての組み込み Agent とユーザー定義 Agent のカード

組み込み Agent

• Clawia — 汎用 Agent。メインの会話エントリーポイントです
• Cocoia — スケジュールタスク専用
• Canvas — ビジュアルプロトタイピング
• ClaudeCode — コード開発
• Design Studio — デザインワークベンチ
• Artia — クリエイティブアシスタント
• 動的に読み込まれる datia-class パッケージ: Deep Research、Visual Layout、Novel Writer など

基盤となるメディア生成 Agent（Chat / Image / Video / Music）はシステム内に残っており、それぞれの専用パネルのエントリーポイントから呼び出されます。Agents ページには個別には表示されません。

データ移行に関する注意

基盤データの移行は、アップグレード時に自動的に実行されます。

• v82（0.1.7、ステップ 1）: フラットな Agent モデルに戻します。以前 Codia 配下にあった Canvas / ClaudeCode は、独立したトップレベル Agent に分割されます
• v87（0.1.7、ステップ 2）: 基盤となる Persona テーブルと Agent テーブルを単一の agent テーブルに統合し、データモデルを簡素化します

過去のセッションは完全に保持されます。以前 Codia 配下にあったセッションは、使用していた Agent の下に独立して一覧表示されるようになり、過去のメッセージが失われることはありません。ロールバックが必要な場合、サポートチームは <userData>/migrations/ 配下のスナップショットファイルを使って復元できます。

クイックスタート

組み込み Agent を使用する

1. Agent パネルを開きます（サイドバーの Agent アイコン）
2. Agent ギャラリーを参照し、適切な Agent を選択します
3. 会話を開始します。Agent は必要なツールを自動的に呼び出します

カスタム Agent を作成する

1. Agent パネルで「Create Agent」をクリックします
2. 名前、説明、システムプロンプトを設定します
3. 利用可能なツールと権限モードを選択します
4. 保存して使用を開始します

詳しい手順については、カスタム Agent の作成 を参照してください。

FAQ

問題	原因	解決策
Agent がツールを実行できない	エンジン種別が chat（ツールサポートなし）	tinyelf または claude-sdk エンジンに切り替える
ツール実行で頻繁に確認が必要になる	権限モードが default	acceptEdits または bypassPermissions に設定する
Agent ループがすぐに停止する	maxIterations の設定が低すぎる	最大反復回数を増やす（デフォルト: 40）
MCP ツールが表示されない	MCP サーバーが関連付けられていない	Agent 設定で MCP サーバーを追加する
サブ Agent の実行に失敗する	サブ Agent 設定ファイルが無効	.claude/agents/*.md の形式を確認する

関連リンク

• 組み込み Agent — プリセット Agent を参照して使用する
• カスタム Agent の作成 — 独自の Agent 設定を書く
• ツール権限とセキュリティ — 権限モードとセキュリティ設定
• スキルシステム — スキルの使用と作成