PraisonAI

PraisonAI 🦞 — 聘请一支全天候工作的 AI 团队。 别再编写样板代码，开始部署能够研究、规划并跨应用执行任务的自主、自我改进 Agent。从单个 Agent 到整个组织，只需 5 行代码即可部署。

curl -fsSL https://praison.ai/install.sh | bash

     

 ██████╗ ██████╗  █████╗ ██╗███████╗ ██████╗ ███╗   ██╗     █████╗ ██╗
 ██╔══██╗██╔══██╗██╔══██╗██║██╔════╝██╔═══██╗████╗  ██║    ██╔══██╗██║
 ██████╔╝██████╔╝███████║██║███████╗██║   ██║██╔██╗ ██║    ███████║██║
 ██╔═══╝ ██╔══██╗██╔══██║██║╚════██║██║   ██║██║╚██╗██║    ██╔══██║██║
 ██║     ██║  ██║██║  ██║██║███████║╚██████╔╝██║ ╚████║    ██║  ██║██║
 ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝    ╚═╝  ╚═╝╚═╝

 pip install praisonai

🎯 使用场景

AI Agent 正在解决各行各业的实际问题：

🚀 认识你的第一个 Agent（不到 1 分钟）

1. 安装轻量级核心 SDK：

pip install praisonaiagents
export OPENAI_API_KEY="your-api-key"

2. 运行你的第一个自主 Agent：

from praisonaiagents import Agent

# Give your agent a goal, and watch it work.
agent = Agent(instructions="You are a senior data analyst.")
agent.start("Analyze the top 3 tech trends of 2026 and format as a markdown table.")

🧬 Agent 五层架构

大多数框架只提供一两层，其余的都留给你自己摸索。PraisonAI 涵盖全部五层，还包括决定 Agent 实际运行位置的外层。

每一层都封装其内层。Agent 出现异常时，对应的层会告诉你该从哪里排查。

┌─────────────────────────────────────────────────────────────────┐
│ ⬡ MANAGED AGENTS — Where does it actually run?                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 5 · GRAPH — Who runs when, and who checks whom?             │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ 4 · LOOP — When do we stop?                             │ │ │
│ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 3 · HARNESS — Can it act, and be checked?           │ │ │ │
│ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │
│ │ │ │ │ 2 · CONTEXT — Is the right thing in the window? │ │ │ │ │
│ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │
│ │ │ │ │ │ 1 · PROMPT — Did I say it clearly?          │ │ │ │ │ │
│ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │
│ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

第 1 层 · 提示词 —— 我说清楚了吗？

角色、指令、示例、输出格式。

from praisonaiagents import Agent

agent = Agent(
    role="Senior Data Analyst",
    goal="Turn raw numbers into decisions",
    output="verbose",              # markdown-formatted output
)
agent.start("Summarise Q3 revenue trends")

第 2 层 · 上下文 —— 窗口里有正确的内容吗？

写入、选择、压缩、隔离——四种上下文操作，各对应一个参数。

from praisonaiagents import Agent

agent = Agent(
    instructions="You are a support engineer.",
    memory={"user_id": "u-42"},    # write    — persists across runs (needs a user_id)
    knowledge=["docs/"],           # select   — retrieves only what's relevant
    context="summarize",           # compress — auto-compacts before the limit
)

隔离通过 handoffs=[specialist] 实现——子 Agent 会继承最近几条消息以及与你的工具集合的交集，而不是完整的对话记录。📖 交接

第 3 层 · 执行环境 —— 它能采取行动并接受检查吗？

Agent = 模型 + 执行环境。 工具调度，以及行动前引导 Agent 的指南和行动后观察的传感器。

from praisonaiagents import Agent, MCP, tool

@tool
def deploy(env: str) -> str:
    """Deploy the current build to an environment."""
    return f"Deployed to {env}"

agent = Agent(
    name="ReleaseEngineer",
    instructions="You are a release engineer.",
    tools=[deploy, MCP("npx -y @modelcontextprotocol/server-filesystem /tmp")],
    approval=True,                 # guide — human gate before risky tools run
)
agent.start("Deploy to staging, then list the files you can read")

第 4 层 · 循环 —— 何时停止？

明确设置迭代次数上限、预算上限、无进展检测和完成检查——每个制动机制都清晰可见。

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    instructions="Fix the failing tests.",
    execution=ExecutionConfig(max_iter=30, max_budget=0.50, on_budget_exceeded="stop"),
    autonomy=True,                 # required to drive the loop with run_autonomous()
)
result = agent.run_autonomous("Refactor the auth module", max_iterations=5)

print(result.completion_reason)
# goal | no_tool_calls | max_iterations | timeout | doom_loop | needs_help | error
# (with on_budget_exceeded="stop", hitting the cap raises BudgetExceededError,
#  surfaced here as completion_reason="error")

死循环检测默认开启。 系统会捕获重复的相同工具调用以及 A→B→A→B 式振荡，但不会误判输出持续变化的轮询器。📖 死循环检测

第 5 层 · 图 —— 谁在何时运行，谁检查谁？

将拓扑作为可版本控制的工件：提示词链、路由、并行化、协调器-工作器模式。

from praisonaiagents import AgentFlow
from praisonaiagents.workflows import route, parallel, repeat

flow = AgentFlow(steps=[
    classifier,
    route({"bug": [bug_agent], "feature": [feature_agent], "default": [triage]}),
    parallel([reviewer, tester]),                      # fan out, join automatically
    repeat(editor, until=lambda ctx: "approved" in ctx.previous_result.lower(),
           max_iterations=3),                          # evaluator–optimizer
])
flow.run("Ticket #123: login fails on Safari")

同一张图也可以用 YAML 表达，完全不需要 Python。📖 AgentFlow

⬡ 跳出技术栈：托管 Agent — 它究竟在哪里运行？

执行框架正日趋商品化；Agent 在哪里运行，将成为下一个倍增器。与其消耗笔记本电脑的 CPU，不如为 Agent 提供一个短期云沙箱 — 代码库、工具和测试都在其中运行。

pip install praisonai

最简单的入门方式是 tools_run_on= — 整个团队或工作流共享一个沙箱，因此步骤 1 写入的文件在步骤 2 中仍然可用。思考过程仍在你的机器上进行：

from praisonaiagents import Agent, AgentFlow

writer = Agent(name="Writer", instructions="You write files.")
reader = Agent(name="Reader", instructions="You read files.")

flow = AgentFlow(tools_run_on="docker", steps=[writer, reader])  # or e2b | modal | daytona | flyio
flow.run("Write 'hello' to /workspace/note.txt, then read it back")

不使用 Python 也可以做到同样的事：

name: remote-demo
tools_run_on: docker      # every step shares one sandbox
agents:
  writer: {role: Writer, goal: Write files}
  reader: {role: Reader, goal: Read files}
steps:
  - agent: writer
    action: "Write 'hello' to /workspace/note.txt"
  - agent: reader
    action: "Read /workspace/note.txt"

对于单个 Agent，两个词就够了 — 它们回答的是不同的问题：

from praisonaiagents import Agent

# A. Only the TOOLS move. Thinking stays on your machine.
agent = Agent(name="builder", instructions="You build things.",
              tools_run_on="docker")   # docker | e2b | modal | daytona | flyio
                                       # tenki | sandlock | ssh | novita | subprocess

# B. The WHOLE agent moves — model calls, loop and tools
agent = Agent(name="teacher", instructions="You teach.", run_on="anthropic")  # hosted
agent = Agent(name="builder", instructions="You build.", run_on="docker")     # self-hosted
agent.start("Write a Python script that prints the first 10 primes, then run it")

询问任意对象它在哪里运行，它都会告诉你：

>>> Agent(name="builder", instructions="x", tools_run_on="docker")
Agent(name='builder', thinks_on='this machine', tools_run_on='a Docker container')

>>> agent.where_does_it_run()
Thinking (the AI model calls) happens on this machine.
Tools run on a Docker container.
Your own tools (check_db) still run on this machine -- only shell, file and
code tools move. They read and write this machine's files.

指定一个无法胜任任务的位置属于拼写错误，而非个人偏好，因此它会明确指出：

>>> Agent(name="x", instructions="i", run_on="e2b")
TypeError: Agent(run_on='e2b') is not valid: run_on= places the whole agent
-- model calls, loop and tools -- on a managed runtime, and 'e2b' runs
commands but cannot host an agent loop.
  To run only the tools there:  Agent(tools_run_on='e2b')

要在其他位置运行一段代码，只需在调用时指定位置：

agent.execute_code_sync("print(6 * 7)", run_in="sandlock")   # kernel-enforced

查看正在运行的内容并回收闲置资源：

praisonai managed ps          # list running sandboxes
praisonai managed stop --all  # reclaim them

沙箱会在闲置时自动关闭（auto_shutdown、idle_timeout_s），并重复使用设置完成后的快照，因此下次运行时会跳过镜像拉取和依赖安装。提交 .praisonai/environment.yaml 后，环境便会随代码库一起保存。

📖 20 个可运行示例 · 使用 praisonai managed sessions list <agent-id> 或 praisonai managed sessions resume <session-id> "<prompt>" 管理会话

_{技术栈的阐述方式改编自 Agent 五层技术栈 和 Agent 执行框架与 Orbs。}

🌌 PraisonAI 生态系统

从核心 SDK 轻松入门，准备好后再扩展到完整的可视化构建器和仪表板。

• 核心 SDK（praisonaiagents）：适用于纯 Python 开发。pip install praisonaiagents
• 💻 PraisonAI CLI（praisonai）：适用于基于终端的开发者。pip install praisonai
• 🦞 Claw 仪表板：将 Agent 直接连接到 Telegram、Slack 或 Discord。pip install "praisonai[claw]"
• 🔗 Flow 可视化构建器：通过拖放创建工作流。pip install "praisonai[flow]"
• 🤖 PraisonAI UI：简洁的聊天界面。pip install "praisonai[ui]"

JavaScript SDK

npm install praisonai

🧠 支持的提供商与功能

由 100 多种大模型提供支持（OpenAI、Anthropic、Gemini 和本地模型）。

“Grok 3 客户支持”——埃隆·马斯克引用 PraisonAI 的教程

🌟 为什么选择 PraisonAI？

📘 使用 Python 代码

不确定结果是错误还是模型随机性导致的？请查看 SDK 行为矩阵，了解 stream、记忆预取、结构化输出、团队和 AG-UI。

1. 单个 Agent

from praisonaiagents import Agent
agent = Agent(instructions="You are a helpful AI assistant")
agent.start("Write a movie script about a robot in Mars")

2. 多个 Agent

from praisonaiagents import Agent, Agents

research_agent = Agent(instructions="Research about AI")
summarise_agent = Agent(instructions="Summarise research agent's findings")
agents = Agents(agents=[research_agent, summarise_agent])
agents.start()

3. MCP（Model Context Protocol）

from praisonaiagents import Agent, MCP

# stdio - Local NPX/Python servers
agent = Agent(tools=MCP("npx @modelcontextprotocol/server-memory"))

# Streamable HTTP - Production servers
agent = Agent(tools=MCP("https://api.example.com/mcp"))

# WebSocket - Real-time bidirectional
agent = Agent(tools=MCP("wss://api.example.com/mcp", auth_token="token"))

# With environment variables
agent = Agent(
    tools=MCP(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-brave-search"],
        env={"BRAVE_API_KEY": "your-key"}
    )
)

📖 完整 MCP 文档 — stdio、HTTP、WebSocket、SSE 传输方式

4. 自定义工具

from praisonaiagents import Agent, tool

@tool
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

@tool
def calculate(expression: str) -> float:
    """Safely evaluate a numeric arithmetic expression."""
    import ast
    import operator
    
    # Define allowed operations
    _OPS = {
        ast.Add: operator.add,
        ast.Sub: operator.sub,
        ast.Mult: operator.mul,
        ast.Div: operator.truediv,
        ast.Pow: operator.pow,
        ast.USub: operator.neg,
        ast.UAdd: operator.pos,
    }
    
    def _safe_eval(node):
        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
            return node.value
        elif isinstance(node, ast.BinOp) and type(node.op) in _OPS:
            return _OPS[type(node.op)](_safe_eval(node.left), _safe_eval(node.right))
        elif isinstance(node, ast.UnaryOp) and type(node.op) in _OPS:
            return _OPS[type(node.op)](_safe_eval(node.operand))
        else:
            raise ValueError("Unsupported expression")
    
    try:
        return _safe_eval(ast.parse(expression, mode="eval").body)
    except (ValueError, SyntaxError, TypeError, ZeroDivisionError, OverflowError):
        raise ValueError("Invalid arithmetic expression")

agent = Agent(
    instructions="You are a helpful assistant",
    tools=[search, calculate]
)
agent.start("Search for AI news and calculate 15*4")

⚠️ **安全提示：**切勿在处理大模型生成或用户提供输入的工具函数中使用 eval()、exec() 或 subprocess。务必验证并清理输入，以防止代码注入攻击。 📖 完整工具文档 — BaseTool、工具包、100 多种内置工具

5. 持久化（数据库）

from praisonaiagents import Agent, db

agent = Agent(
    name="Assistant",
    memory={
        "db": db(database_url="postgresql://localhost/mydb"),
        "session_id": "my-session",
    },
)
agent.chat("Hello!")  # Auto-persists messages, runs, traces

📖 完整持久化文档 — PostgreSQL、MySQL、SQLite、MongoDB、Redis 等 20 多种数据库

6. PraisonAI Claw 🦞（仪表板 UI）

通过一条命令，将你的 AI Agent 连接到 Telegram、Discord、Slack、WhatsApp 等平台。

pip install "praisonai[claw]"
praisonai claw

必需的环境变量

将 .env.example 复制为 .env，并配置以下变量：

打开 http://localhost:8082 — 仪表板内置 13 个页面：聊天、Agent、记忆、知识库、频道、护栏、Cron 等。可直接在 UI 中添加消息频道。

📖 Claw 完整文档 — 平台令牌、CLI 选项、Docker 和 YAML Agent 模式

7. Langflow 集成 🔗（可视化流程构建器）

在 Langflow 中使用拖放式组件，以可视化方式构建多 Agent 工作流。

pip install "praisonai[flow]"
praisonai flow

打开 http://localhost:7861 — 使用 Agent 和 Agent Team 组件创建顺序或并行工作流。连接 Chat Input → Agent Team → Chat Output，即可快速搭建多 Agent 流水线。

📖 完整流程文档 — 可视化 Agent 构建、组件参考和部署

8. PraisonAI UI 🤖（简洁聊天）

为你的 AI Agent 提供轻量级聊天界面。

pip install "praisonai[ui]"
praisonai ui

📄 使用 YAML（无需代码）

示例 1：两个 Agent 协同工作

创建 agents.yaml：

framework: praisonai
topic: "Write a blog post about AI"

agents:
  researcher:
    role: Research Analyst
    goal: Research AI trends and gather information
    instructions: "Find accurate information about AI trends"
    
  writer:
    role: Content Writer
    goal: Write engaging blog posts
    instructions: "Write clear, engaging content based on research"

运行命令：

praisonai agents.yaml

Agent 会自动按顺序协同工作

示例 2：带自定义工具的 Agent

在同一文件夹中创建两个文件：

agents.yaml：

framework: praisonai
topic: "Calculate the sum of 25 and 15"

agents:
  calculator_agent:
    role: Calculator
    goal: Perform calculations
    instructions: "Use the add_numbers tool to help with calculations"
    tools:
      - add_numbers

tools.py：

def add_numbers(a: float, b: float) -> float:
    """
    Add two numbers together.
    
    Args:
        a: First number
        b: Second number
    
    Returns:
        The sum of a and b
    """
    return a + b

运行命令：

praisonai agents.yaml

💡 提示：

• 在工具列表中使用函数名（例如 add_numbers），不要使用文件名
• 系统会自动发现 tools.py 中的工具
• 函数的文档字符串有助于 AI 理解如何使用该工具

🎯 CLI 快速参考

📖 CLI 完整参考

✨ 主要功能

💻 使用 JavaScript 代码

npm install praisonai
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx

const { Agent } = require('praisonai');
const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
agent.start('Write a movie script about a robot in Mars');

⚡ 性能

PraisonAI 将框架开销控制在微秒级：在我们 2026-10-15 的测试中，创建一个 Agent（一个工具，不调用大模型）的平均耗时为 46 μs，因此在多 Agent 工作负载中，与模型延迟相比，每个 Agent 的初始化开销可以忽略不计。

方法、比较结果和复现方式：benchmarks/BENCHMARK_RESULTS.md · 文档

⭐ Star 历史

* export TAVILY_API_KEY=xxxxx

🔍 Langfuse 追踪

pip install "praisonai[langfuse]"
praisonai langfuse

🎓 视频教程

通过我们全面的视频系列了解 PraisonAI：

查看全部 22 个视频教程

主题	视频
具备自我反思能力的 AI Agent
推理数据生成 Agent
具备推理能力的 AI Agent
多模态 AI Agent
AI Agent 工作流
异步 AI Agent
迷你 AI Agent
具备记忆功能的 AI Agent
重复执行型 Agent
简介
工具概览
自定义工具
Firecrawl 集成
用户界面
Crawl4AI 集成
聊天界面
代码界面
Mem0 集成
训练
实时语音界面
通话界面
推理提取 Agent

👥 参与贡献

欢迎贡献！Fork 此仓库，创建分支并提交 PR → 贡献指南。

❓ 常见问题与故障排查

pip install praisonaiagents

export OPENAI_API_KEY=your_key_here

# Start Ollama and pull a model
ollama serve
ollama pull llama3.2

from praisonaiagents import Agent

agent = Agent(instructions="You are a helpful assistant", llm="ollama/llama3.2")
agent.start("Why is the sky blue?")

export OPENAI_MODEL_NAME=ollama/llama3.2

agent = Agent(instructions="...", llm="ollama/llama3.2", base_url="http://192.168.1.10:11434")

from praisonaiagents import Agent, db

agent = Agent(
    name="Assistant",
    memory={
        "db": db(database_url="postgresql://localhost/mydb"),
        "session_id": "my-session",
    },
)

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    # Enables file-based memory (no extra deps!)
    memory={"user_id": "user123"},
)

from praisonaiagents import Agent, Agents

agent1 = Agent(instructions="Research topics")
agent2 = Agent(instructions="Summarize findings")
agents = Agents(agents=[agent1, agent2])
agents.start()

from praisonaiagents import Agent, MCP

agent = Agent(
    tools=MCP("npx @modelcontextprotocol/server-memory")
)

获取帮助

• 📚 完整文档
• 🐛 报告问题
• 💬 讨论