agentjido/jido

# Jido [](https://hex.pm/packages/jido) [](https://hexdocs.pm/jido/) [](https://github.com/agentjido/jido/actions/workflows/ci.yml) [](https://github.com/agentjido/jido/blob/main/LICENSE) [](https://coveralls.io/github/agentjido/jido?branch=main) _名称 "Jido" (自動) 源自日语词汇，意为 "自动" 或 "自动化"，其中 自 (ji) 意为 "自己"，動 (dō) 意为 "运动"。_ _了解更多关于 Jido 的信息，请访问 [agentjido.xyz](https://agentjido.xyz)。_ ## 概述 使用 Jido，您的 Agent 是具有单一命令函数的不可变数据结构： ``` defmodule MyAgent do use Jido.Agent, name: "my_agent", description: "My custom agent", schema: [ count: [type: :integer, default: 0] ] end end {agent, directives} = MyAgent.cmd(agent, action) ``` 状态更改是纯粹的数据转换；副作用被描述为指令并由 OTP runtime 执行。您可以获得确定性的 Agent 逻辑、无需进程的可测试性，以及在生产环境中运行这些 Agent 的清晰路径。 ## Jido 生态系统 Jido 是 Jido 生态系统的核心包。该生态系统围绕核心 Jido Agent 行为构建，并提供多个可选包以扩展核心行为。 | Package | Description | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [req_llm](https://github.com/agentjido/req_llm) | LLM API 的 HTTP 客户端 | | [jido_action](https://github.com/agentjido/jido_action) | 可组合、经验证的操作，支持 AI 工具集成 | | [jido_signal](https://github.com/agentjido/jido_signal) | 基于 CloudEvents 的消息封装及支持路由和发布/订阅消息的工具 | | [jido](https://github.com/agentjido/jido) | 核心 Agent 框架，包含状态管理、指令和 runtime | | [jido_ai](https://github.com/agentjido/jido_ai) | Agent 的 AI/LLM 集成 | 有关使用 Jido 生态系统可以构建内容的演示和示例，请参阅 [https://agentjido.xyz](https://agentjido.xyz)。 ## 为什么选择 Jido？ OTP 原语非常出色。您可以使用原生 GenServer 构建 Agent 系统。但在构建*多个协作 Agent* 时，您会重新发明： | 原生 OTP | Jido 形式化 | | ----------------------------------- | --------------------------------------- | | 每个 GenServer 的临时消息形状 | 作为标准封装的 Signal | | 混合在回调中的业务逻辑 | 作为可重用命令模式的 Action | | 代码中分散的隐式效果 | 作为类型化效果描述的指令 | | 每个服务器的自定义子级跟踪 | 内置父/子层级 | | 进程退出 = 完成 | 基于状态的完成语义 | Jido 不是“更好的 GenServer”——它是在 GenServer *之上*构建的形式化 Agent 模式。 ## 关键特性 ### 不可变 Agent 架构 - 受 Elm/Redux 启发的纯函数式 Agent 设计 - `cmd/2` 作为核心操作：输入 Action，输出更新的 Agent + 指令 - 使用 NimbleOptions 或 Zoi 进行 Schema 验证的状态 ### 基于指令的效果 - Action 转换状态；指令描述外部效果 - 内置指令：Emit、Spawn、SpawnAgent、StopChild、Schedule、Stop - 基于协议的可扩展性，支持自定义指令 ### OTP Runtime 集成 - 基于 GenServer 的 AgentServer，用于生产部署 - 具有生命周期管理的父子 Agent 层级结构 - 具有可配置策略的 Signal 路由 - 用于多租户部署的实例范围监督 ### 可组合的插件 - 扩展 Agent 的可重用能力模块 - 每个插件的状态隔离，具有自动 Schema 合并 - 用于初始化和 Signal 处理的生命周期钩子 ### 执行策略 - 用于简单工作流的直接执行 - 用于状态驱动工作流的 FSM（有限状态机）策略 - 用于自定义执行模式的可扩展策略协议 ### 多 Agent 编排 - 具有可配置策略的多 Agent 工作流 - 用于复杂工作流的基于计划的编排 - 用于自定义执行模式的可扩展策略协议 ## 安装 ### 使用 Igniter（推荐） 开始使用最快的方式是使用 [Igniter](https://hex.pm/packages/igniter)： ``` mix igniter.install jido ``` 这会自动： - 将 Jido 添加到您的依赖项 - 创建一个 `MyApp.Jido` 实例模块 (`use Jido, otp_app: :my_app`) - 在 `config/config.exs` 中创建配置 - 将 `MyApp.Jido` 添加到您的监督树 生成一个示例 Agent 以开始使用： ``` mix igniter.install jido --example ``` ### 手动安装 将 `jido` 添加到 `mix.exs` 的依赖项列表中： ``` def deps do [ {:jido, "~> 2.0"} ] end ``` 然后定义一个 Jido 实例模块并将其添加到您的监督树： ``` # 在 lib/my_app/jido.ex 中 defmodule MyApp.Jido do use Jido, otp_app: :my_app end ``` ``` # 在 config/config.exs 中 config :my_app, MyApp.Jido, max_tasks: 1000, agent_pools: [] ``` ``` # 在你的 application.ex 中 children = [ MyApp.Jido ] Supervisor.start_link(children, strategy: :one_for_one) ``` ## 快速开始 ### 1. 定义 Agent ``` defmodule MyApp.CounterAgent do use Jido.Agent, name: "counter", description: "A simple counter agent", schema: [ count: [type: :integer, default: 0] ], signal_routes: [ {"increment", MyApp.Actions.Increment} ] end ``` ### 2. 定义 Action ``` defmodule MyApp.Actions.Increment do use Jido.Action, name: "increment", description: "Increments the counter by a given amount", schema: [ amount: [type: :integer, default: 1] ] def run(params, context) do current = context.state[:count] || 0 {:ok, %{count: current + params.amount}} end end ``` ### 3. 执行命令 ``` # 创建 agent agent = MyApp.CounterAgent.new() # 执行 action - 返回更新后的 agent + 指令 {agent, directives} = MyApp.CounterAgent.cmd(agent, {MyApp.Actions.Increment, %{amount: 5}}) # 检查 state agent.state.count # => 5 ``` ### 4. 使用 AgentServer 运行 ``` # 启动 agent 服务器 {:ok, pid} = MyApp.Jido.start_agent(MyApp.CounterAgent, id: "counter-1") # 向运行中的 agent 发送 signal (同步) # Signal 类型必须在 signal_routes 中声明 {:ok, agent} = Jido.AgentServer.call(pid, Jido.Signal.new!("increment", %{amount: 10}, source: "/user")) # 通过 ID 查找 agent pid = MyApp.Jido.whereis("counter-1") # 列出所有运行中的 agent agents = MyApp.Jido.list_agents() ``` ## 核心概念 ### `cmd/2` 契约 Jido 中的基本操作： ``` {agent, directives} = MyAgent.cmd(agent, action) ``` 关键不变量： - 返回的 `agent` 始终是完整的——不需要“应用指令”步骤 - `directives` 仅描述外部效果——它们从不修改 Agent 状态 - `cmd/2` 是一个纯函数——相同的输入总是产生相同的输出 ### Action 与 指令 与 状态操作 | Action | 指令 | 状态操作 | | ------------------------------------------ | ------------------------------------- | ------------------------------- | | 转换状态，可能执行副作用 | 描述外部效果 | 描述内部状态变化 | | 由 `cmd/2` 执行，更新 `agent.state` | Agent 发出的裸结构体 | 由策略层应用 | | 可以调用 API、读取文件、查询数据库 | Runtime (AgentServer) 解释它们 | 永不离开策略 | ### 状态操作 (`Jido.Agent.StateOp`) 状态操作是由策略层在 `cmd/2` 期间处理的内部状态转换。与指令不同，它们永远不会到达 runtime。 | StateOp | Purpose | | -------------- | -------------------------------- | | `SetState` | 深度合并属性到状态 | | `ReplaceState` | 完全替换状态 wholesale | | `DeleteKeys` | 删除顶级键 | | `SetPath` | 在嵌套路径设置值 | | `DeletePath` | 删除嵌套路径的值 | ### 指令类型 | Directive | Purpose | | ------------ | ------------------------------------------------ | | `Emit` | 通过配置的适配器分发 Signal | | `Error` | 从 cmd/2 发出错误信号 | | `Spawn` | 生成一个通用 BEAM 子进程 | | `SpawnAgent` | 生成一个带有层级跟踪的子 Jido Agent | | `StopChild` | 优雅地停止被跟踪的子 Agent | | `Schedule` | 调度延迟消息 | | `Stop` | 停止 Agent 进程 | ## 文档 **从这里开始：** - [快速开始](guides/getting-started.livemd) - 在 5 分钟内构建您的第一个 Agent - [核心循环](guides/core-loop.md) - 理解思维模型 **指南：** - [构建 Agent](guides/agents.md) - Agent 定义和状态管理 - [Signal 与路由](guides/signals.md) - 基于 Signal 的通信 - [Agent 指令](guides/directives.md) - Runtime 的效果描述 - [Runtime 和 AgentServer](guides/runtime.md) - 基于进程的 Agent 执行 - [持久化与存储](guides/storage.md) - Hibernate、thaw 和 InstanceManager 生命周期 - [调度](guides/scheduling.md) - 声明式和动态 cron 调度 - [插件](guides/plugins.md) - 可组合的能力束 - [策略](guides/strategies.md) - 执行策略（Direct、FSM） **高级：** - [FSM 策略深入探讨](guides/fsm-strategy.livemd) - 状态机工作流 - [Worker Pool](guides/worker-pools.md) - 预热的 Agent 池以提高吞吐量 - [测试 Agent](guides/testing.md) - 测试模式和最佳实践 **API 参考：** [hexdocs.pm/jido](https://hexdocs.pm/jido) ## 开发 ### 前置条件 - Elixir 1.17+ - Erlang/OTP 26+ ### 运行测试 ``` mix test ``` ### 质量检查 ``` mix quality # Runs formatter, dialyzer, and credo ``` ## 贡献 我们欢迎贡献！请参阅我们的[贡献指南](CONTRIBUTING.md)了解有关以下内容的详细信息： - 设置您的开发环境 - 运行测试和质量检查 - 提交 Pull Request - 代码风格指南 ## 许可证 Copyright 2024-2025 Mike Hostetler 根据 Apache License 2.0 版本授权。详情请参阅 [LICENSE](LICENSE)。 ## 链接 - **文档**: [https://hexdocs.pm/jido](https://hexdocs.pm/jido) - **GitHub**: [https://github.com/agentjido/jido](https://github.com/agentjido/jido) - **AgentJido**: [https://agentjido.xyz](https://agentjido.xyz) - **Jido Workbench**: [https://github.com/agentjido/jido_workbench](https://github.com/agentjido/jido_workbench)

标签：Agent框架, AI开发框架, C2, DLL 劫持, Elixir, Erlang虚拟机, Jido, LLM集成, OTP, 不可变数据结构, 企业级AI, 函数式编程, 分布式系统, 动态工作流, 响应大小分析, 大语言模型, 并发编程, 状态机, 网络调试, 自主智能体, 自动化