Elemental

---

Elemental は、会話ベースのコラボレーションを目的にチームとして構成された AI エージェントを使ってタスクを自動化する、汎用のマルチエージェントフレームワークです。エージェントはさまざまなプロバイダーの言語モデル（ローカル環境の小規模モデルを含む）を利用できるため、必要に応じて環境をより柔軟に選択し、外部インフラストラクチャから作業を隔離できます。最先端の LLM もサポートされています。エージェントには、外部システム（内部システムや MCP サーバーが提供するシステム）とやり取りできるツールが備わっています。Elemental では、シンプルなアシスタント、隔離されたエージェント、マルチエージェントチーム、ワークフロー、またはマルチエージェントチームなど、さまざまな構成が可能です。エージェント構成は動的で、作業の計画や実行中のタスクの再計画が可能です。

機能

• マルチエージェントによるタスク実行。
• エージェントごとにカスタムの言語モデルを設定できます。推論エンジンやモデルサイズも個別に選択でき、Ollama、Llama.cpp、Gemini、OpenAI および互換 API、Anthropic（ネイティブおよび AWS Bedrock）を直接サポートします。
• OpenAI、Anthropic、Anthropic、Gemini、Ollama によるマルチモーダルメッセージ。
• エージェントごとにシンプルにモデルを選択できます。例：ollama|gemma3 または openai|gpt-4.1-mini。
• Jinja 形式の変数を含む、カスタマイズ可能なテンプレート。
• 動的な計画、実行、再計画、構成、検証の各ステップを備えた、デフォルトの動的オーケストレーター。
• YAML ファイルでエージェント構成を指定できる、シンプルなコマンドラインインターフェイス。
• あらゆる言語モデルで実行できるネイティブツールを提供する、拡張可能なインターフェイスによるツール実行。
• 推論型および会話型のエージェントプロンプト戦略。
• ツールセット全体または個別のツール単位で選択できる MCP ツール。
• ファイルをメッセージに取り込むためのコンテキストマネージャー。
• エージェントイベントの可観測性。

はじめに

インストール

次のコマンドでインストールします：

pip install elemental-agents

ソースからインストール

git clone [email protected]:AttoAgents/elemental.git
cd elemental
poetry build
pip install dist/elemental_agents-*.whl

.env ファイル

Elemental プロジェクト用の .env ファイルの例：

openai_api_key="<OPENAI API KEY HERE>"
openai_streaming=False
openai_max_tokens=10000
default_engine="ollama"
custom_max_tokens=2000
google_search_api_key="<GOOGLE SEARCH API HERE>"
google_cse_id="<GOOGLE CSE ID HERE>"
google_search_timeout=5
wikipedia_user_agent="<Agents/1.0 YOUR EMAIL HERE>"
observer_destination="screen"
mcpServers='{"Github": {"command": "npx", "args": ["-y","@modelcontextprotocol/server-github"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR GITHUB TOKEN>"}}}'

デフォルトでは、Elemental はカレントディレクトリの .env ファイルを使用します。ただし、別の構成ファイルのパスを指定する環境変数 ATTO_ENV_FILE が設定されている場合は、そのファイルを使用します。

例

以下では、elemental_agents フレームワークをプログラムから利用して、シンプルなアシスタントやエージェント、エージェントチームを設定し、ツールを使い、外部 MCP サーバーを活用する方法を紹介します。ここに示す例はすべて、examples ディレクトリにもあります。

シンプルなアシスタント

Elemental で最もシンプルなエージェント構成は、ツールを実行する機能を持たず、言語モデルとのインターフェイスとして機能するシンプルなアシスタントです。ただし、このアシスタントは会話を認識し、会話履歴を保存する ShortMemory を備えています。

from loguru import logger

from elemental_agents.core.agent.agent_factory import AgentFactory

TASK = "Why is the sky blue?"
SESSION = "TestSession"

assistant = AgentFactory.create(
    agent_name="AssistantAgent",
    agent_persona="Simple always helpful assistant",
    agent_type="simple",
    llm_model="ollama|gemma3",
)

result = assistant.run(task=TASK, input_session=SESSION)
logger.info(f"Result: {result}")

この例では、Gemma3 モデルとともに Ollama を使用します（例 1 を参照）。

ReAct エージェント

ReAct のような反復的な推論プロンプト戦略を利用すると、より複雑で機能が充実したエージェントを作成できます。この場合、エージェントはアクションを実行してツールを利用し、その結果を観察として提示できます。以下の例では（例 2 を参照）、エージェントに複数のツールを設定しています。

from loguru import logger

from elemental_agents.core.agent.agent_factory import AgentFactory

TASK = "Calculate the sum of 5 and 3."
SESSION = "Test Session"

assistant = AgentFactory.create(
    agent_name="AssistantAgent",
    agent_persona="You are a helpful assistant.",
    agent_type="ReAct",
    llm_model="openai|gpt-4.1-mini",
    tools=["Calculator", "CurrentTime", "NoAction"],
)
result = assistant.run(task=TASK, input_session=SESSION)
logger.info(f"Result: {result}")

このタスクは、Calculator ツールを使う必要性を示しています。この例では、OpenAI API が提供する言語モデルを使用します。

メモ

Elemental は特定の言語モデルの関数呼び出し機能に依存せず、エージェントのプロンプト戦略によってアクション（ツールとそのパラメーターを選択するもの）の定義を処理します。

内部計画を備えた ReAct エージェント - PlanReAct

ReAct エージェントと同様に、内部計画を含む、より複雑なプロンプト戦略を定義できます。agent_type="PlanReAct" を選択すると、内部計画によって ReAct 戦略を拡張するエージェントを作成できます（例 3 を参照）。

from loguru import logger

from elemental_agents.core.agent.agent_factory import AgentFactory

TASK = "Calculate the sum of 5 and 3."
SESSION = "Test Session"

assistant = AgentFactory.create(
    agent_name="AssistantAgent",
    agent_persona="You are a helpful assistant.",
    agent_type="PlanReAct",
    llm_model="openai|gpt-4.1-mini",
    tools=["Calculator", "CurrentTime", "NoAction"],
)
result = assistant.run(task=TASK, input_session=SESSION)
logger.info(f"Result: {result}")

会話型エージェントチーム

連携して動作するエージェントのチームは、まず個々のエージェントを作成し、次に GenericAgentTeam クラスを使ってエージェントチームを作成することで定義できます。エージェントに会話型の特性を持たせるには、agent_type="ConvPlanReAct" を指定して作成する必要があります。これにより、プロンプト戦略によってチームの会話型の特性と認識が有効になります（例 4 を参照）。

from loguru import logger

from elemental_agents.core.agent.agent_factory import AgentFactory
from elemental_agents.core.agent_team.generic_agent_team import GenericAgentTeam
from elemental_agents.core.selector.agent_selector_factory import AgentSelectorFactory

agent1 = AgentFactory.create(
    agent_name="AssistantAgent",
    agent_persona="You are a helpful assistant.",
    agent_type="ConvPlanReAct",
    llm_model="openai|gpt-4.1-mini",
    tools=["Calculator", "CurrentTime", "NoAction"],
)
agent2 = AgentFactory.create(
    agent_name="ProgrammerAgent",
    agent_persona="You are a helpful programmer.",
    agent_type="ConvPlanReAct",
    llm_model="openai|gpt-4.1-mini",
    tools=["Calculator", "CurrentTime", "NoAction"],
)

selector_factory = AgentSelectorFactory()
agent_selector = selector_factory.create(
    selector_name="conversational", lead_agent="AssistantAgent"
)
agent_team = GenericAgentTeam(selector=agent_selector)
agent_team.register_agent("AssistantAgent", agent1, "ConvPlanReAct")
agent_team.register_agent("ProgrammerAgent", agent2, "ConvPlanReAct")

result = agent_team.run(
    task="What is the color of sky on Mars?", input_session="Example Session"
)
logger.info(f"Result: {result}")

上記のタスクでは、会話は必要ありません（または、会話が行われない可能性があります）。

エージェントのオーケストレーションチーム - 外部計画とタスクキュー

PlanReAct のような内部計画プロンプト戦略を持つ単一のエージェントを使用できますが、専用の計画エージェントを使って計画プロセスを実行することもできます。この場合、エージェントが計画を作成し、タスクキューに登録します。このプロセスは柔軟な DynamicAgentOrchestrator クラスによってオーケストレーションされ、実行中に行う再計画など、さらに多くのステップを含めることもできます。

以下の例では、プロセスを説明するために 2 つのシンプルなエージェントを使用します（例 5 を参照）。

from loguru import logger

from elemental_agents.core.agent.agent_factory import AgentFactory
from elemental_agents.core.orchestration.dynamic_agent_orchestrator import (
    DynamicAgentOrchestrator,
)

planner_agent = AgentFactory.create(
    agent_name="PlannerAgent",
    agent_persona="",
    agent_type="planner",
    llm_model="openai|gpt-4.1-mini",
)
executor_agent = AgentFactory.create(
    agent_name="ExecutorAgent",
    agent_persona="You are an expert software engineer.",
    agent_type="ReAct",
    llm_model="openai|gpt-4.1-mini",
    tools=[
            "Calculator",
            "CurrentTime",
            "NoAction",
            "ReadFiles",
            "WriteFile",
            "ListFiles"
        ],
)

orchestrator = DynamicAgentOrchestrator(planner=planner_agent, executor=executor_agent)

result = orchestrator.run(
    instruction="Create FastAPI backend for a TODO application.",
    input_session="Example Session"
)
logger.info(f"Result: {result}")

上記の例では、DynamicAgentOrchestrator が管理するワークフローの 2 つのステップを使用しています。ステップの完全な一覧は、planner、plan_verifier、replanner、executor、verifier、composer です。

YAML ファイルを使った定義

エージェントの設定は YAML ファイルで指定できます。Elemental には、DynamicAgentOrchestrator の実行に必要なすべてのオブジェクト（エージェント／エージェントチームなど）をセットアップする Workflow クラスと Driver クラスが含まれています。

設定例は次のとおりです（例 6 を参照）。

workflowName: ModelTest
workflow:
  - executor
executor:
  - name: Assistant
    type: Simple
    persona: >-
      You are expert researcher and great communicator of complex topics using
      simple terms. You always give comprehensive and extensive responses that
      consider the task at hand.
    tools: []
    llm: ollama|qwen3:14b
    temperature: 0
    frequencyPenalty: 0
    presencePenalty: 0
    topP: 1
    maxTokens: 2000
    stopWords: <PAUSE>, STOP
    template: >
      {{ agent_persona }}

      Follow user's instruction. Do this on a stepwise basis and double-check
      each step, one at a time. Use markdown in your response for more readable
      format. 

この YAML 設定は、プログラムから Driver クラスを組み込むか、非常にシンプルなユーザーインターフェースを提供する elemental_agents.main.main ツールを使うことで利用できます。

上記の設定は、次のコマンドで実行できます。

python -m elemental_agents.main.main --config example.yaml --instruction "Why is the sky blue?" 

この場合、--instruction オプションによって、ユーザーが指定したタスクがこの設定に追加されます。

Model Context Protocol（MCP）サーバーのツール

Elemental で MCP サーバーを使用するには、設定ファイルで mcpConfig 変数を使って定義する必要があります。例：

mcpServers='{"Github": {"command": "npx", "args": ["-y","@modelcontextprotocol/server-github"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR GITHUB TOKEN>"}}}'

上記の mcpConfig 変数の値は、Github MCP サーバーを追加します。JSON オブジェクトに項目を追加すれば、同様の方法で複数のサーバーを定義できます。 MCP サーバーのツールは、MCP|server_name|tool_name という構文でエージェントに簡単に追加できます。以下の例では（例 7 を参照）、上記で定義した Github MCP サーバーから search_repositories ツールを MCP|Github|search_repositories として追加します。

from loguru import logger

from elemental_agents.core.agent.agent_factory import AgentFactory

TASK = "Search Github repositories for REST API creation in Python."
SESSION = "Test Session"

assistant = AgentFactory.create(
    agent_name="AssistantAgent",
    agent_persona="You are a helpful assistant.",
    agent_type="ReAct",
    llm_model="openai|gpt-4.1-mini",
    tools=["Calculator", "CurrentTime", "NoAction", "MCP|Github|search_repositories"],
)
result = assistant.run(task=TASK, input_session=SESSION)
logger.info(f"Result: {result}")

MCP サーバーが提供するすべてのツールをエージェントで使用できるようにするには、ツール名として MCP|server_name|* を指定します。これによりツールが照会され、すべて登録されます。上記の例では、MCP|Github|search_repositories を MCP|Github|* に変更することで同じ設定にできます（例 8 を参照）。

お問い合わせ

本プロジェクトは AttoAgents が開発・保守しています。詳細については、[email protected] までお問い合わせください。