Elemental

---

Elemental 是一个通用的多 Agent 框架，用于通过团队协作的对话式方式组合 AI Agent 来自动执行任务。Agent 可以使用来自各种提供商的语言模型（包括本地环境中的小型模型），从而允许更灵活地选择运行环境，并在需要时将工作与外部基础设施隔离。它也支持领先的大模型。Agent 配备了可与外部系统交互的工具（包括内部工具和 MCP 服务提供的工具）。Elemental 支持多种配置，包括简单助手、隔离 Agent、多 Agent 团队和工作流。Agent 配置是动态的，能够规划工作，并在执行期间重新规划任务。

功能

• 多 Agent 任务执行。
• 为每个 Agent 定制语言模型，包括不同的推理引擎和模型规模；直接支持 Ollama、Llama.cpp、Gemini、OpenAI 及兼容 API、Anthropic（原生和 AWS Bedrock）。
• 支持 OpenAI、Anthropic、Anthropic、Gemini 和 Ollama 的多模态消息。
• 为每个 Agent 简单地选择模型，例如 ollama|gemma3 或 openai|gpt-4.1-mini。
• 支持使用 Jinja 格式变量的可自定义模板。
• 默认动态编排器包含动态规划、执行、重新规划、组合和验证步骤。
• 简单的命令行界面，通过 YAML 文件提供 Agent 配置。
• 工具执行采用可扩展接口，可提供能与任何语言模型配合使用的原生工具。
• 推理型和对话型 Agent 提示词策略。
• MCP 工具支持选择完整工具集或单个工具。
• 上下文管理器可将文件引入消息。
• Agent 事件可观测性。

开始使用

安装

使用以下命令安装：

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 框架来设置简单助手、Agent、Agent 团队、使用工具以及利用外部 MCP 服务。此处展示的所有示例也都可以在 examples 目录中找到。

简单助手

Elemental 中最简单的 Agent 配置是设置一个无法执行工具、仅作为语言模型接口的简单助手。不过，该助手能够感知对话，并包含用于存储对话历史的 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}")

在此示例中，我们使用 Ollama 和 Gemma3 模型（参见示例 1）。

ReAct Agent

通过使用 ReAct 等迭代推理提示词策略，可以创建更复杂、更完整的 Agent。此时，Agent 能够通过执行操作来使用工具，并将结果作为观察返回。在下面的示例中（参见示例 2），我们为 Agent 配备了多个工具。

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 不依赖特定语言模型的函数调用能力，而是通过 Agent 的提示词策略处理操作定义（用于选择工具及其参数）。

带内部规划的 ReAct Agent - PlanReAct

与 ReAct Agent 类似，我们可以定义更复杂的提示词策略，其中包含内部规划。通过选择 agent_type="PlanReAct"，我们可以创建一个通过内部规划增强 ReAct 策略的 Agent（参见示例 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}")

对话式 Agent 团队

可以先创建各个 Agent，再使用 GenericAgentTeam 类创建 Agent 团队，让一组 Agent 协同工作。若要让 Agent 具备对话特性，需要使用 agent_type="ConvPlanReAct" 创建它们。此设置通过提示词策略赋予 Agent 对话特性和团队意识（参见示例 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}")

上述任务不需要（也可能不会使用）对话。

Agent 编排团队 - 外部规划和任务队列

单个 Agent 可以使用 PlanReAct 这类内部规划提示词策略，也可以使用专门的规划 Agent 来完成规划过程。在这种情况下，Agent 会制定计划并填充任务队列。此过程由灵活的 DynamicAgentOrchestrator 类进行编排，也可以包含更多步骤，例如在执行期间进行重新规划。

以下示例包含两个简单的 Agent，用于说明此过程（参见示例 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 管理的工作流中的两个步骤。完整列表包括 planner、plan_verifier、replanner、executor、verifier 和 composer。

使用 YAML 文件定义

Agent 配置可以通过 YAML 文件提供。Elemental 包含 Workflow 和 Driver 类，它们会为 DynamicAgentOrchestrator 运行设置所有必要的对象（即 Agent/Agent 团队）。

配置示例（参见示例 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. 

可以通过在程序中使用 Driver 类，或使用 elemental_agents.main.main 工具来应用此 YAML 配置；后者提供了非常简单的用户界面。

可以使用以下命令运行上述配置：

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

在此情况下，--instruction 选项会将用户提供的任务添加到此配置中。

模型上下文协议（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|server_name|tool_name 语法，将 MCP 服务中的工具无缝添加到 Agent。在以下示例中（参见示例 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}")

若要让 Agent 使用 MCP 服务提供的所有工具，请将 MCP|server_name|* 用作工具名称。系统会查询该服务的工具并将它们全部注册。可以将上述示例中的 MCP|Github|search_repositories 改为 MCP|Github|*（参见示例 8）。

联系方式

该项目由 AttoAgents 开发和维护。如需了解更多信息，请通过 [email protected] 联系我们。