OmniCoreAgent
Open Python Agent Harness and Runtime for Production AI Agents
Everything around the model: parallel tool batches, structured observations, loop detection, memory, workspace files, MCP tools, subagents, background tasks, and serving.
Quick Start -
Choose Your Path -
What Makes It Different -
Install -
Cookbook -
Features -
Docs
快速开始```bash
pip install omnicoreagent
bash
export LLM_API_KEY=your_api_keypython
import asyncio
from omnicoreagent import OmniCoreAgent
agent = OmniCoreAgent(
name="assistant",
system_instruction="You are a helpful assistant.",
model_config={"provider": "openai", "model": "gpt-4o"},
)
async def main():
result = await agent.run("Research the top 3 open-source agent runtimes and summarize them.")
print(result["response"])
await agent.cleanup()
asyncio.run(main())
这是最小的路径:一个代理、一个模型、线束循环、会话内存,
护栏、工作区文件、错误处理和每次运行的指标。
上下文管理、工具输出卸载、BM25工具检索、子代理、技能、,
云工作区存储和生产后端是可选择的,因此一个小型代理可以保留
小。
> 准备好更深入了吗?这 食谱 有进步的例子
> hello world到生产部署。
______________________________________________________________________
## 选择你的道路
|目标|从这里开始|
|------|------------|
|建立你的第一个代理| 快速开始 |
|添加Python工具| 当地工具烹饪书 |
|连接MCP服务器工具| MCP工具食谱 |
|管理内存和上下文| 入门食谱 |
|保存文件、工件和大型工具结果| 工具卸载食谱 |
|构建多步骤工作流| 工作流程食谱 |
|通过HTTP/SSE提供代理| OmniServe食谱 |
|了解运行时内部| 实施图 |
______________________________________________________________________
## 是什么让它与众不同
大多数代理库都停留在“LLM+工具循环”上。OmniCoreAgent是围绕
之后出现的运行时问题:顺序工具速度慢、噪音大
观察、卡住循环、上下文耗尽、MCP服务器工具、耐用
工作空间文件和运行时服务。
### 1.代理分批调用工具,而不是强制序列
通常的工具循环如下:```text
LLM -> call tool A -> wait -> result -> LLM -> call tool B -> wait -> result
OmniCoreAgent允许模型一起请求独立的工具:```text
LLM -> [tool A + tool B + tool C in parallel] -> one structured observation -> LLM
模型在再次推理之前会获得批次的一个完整视图。A失败了
工具显示在成功的工具旁边,而不是默默地折叠
整个步骤。
本机函数调用本身不是运行时。OmniCoreAgent使用自己的
工具调用契约、解析器、解析器、并行运行器和结果格式化器
线束控制整个执行路径。
### 2.工具结果变成结构化观察
原始工具输出通常太嘈杂,无法进行下一步推理。大有效载荷,
错误、无关字段和提示注入内容都会扭曲循环。
OmniCoreAgent通过观察管道路由工具结果:```text
tool output -> parse -> format -> guardrail check -> offload when configured -> observation -> model
模型接收继续任务所需的信号,而不是无限转储
工具返回的每个字节。启用刀具卸载时,输出量大
被写入活动工作区,模型收到可读的预览
加上它以后可以使用的路径。
3.循环检测使用超出步数的签名
max_steps 它仍然有用,但它是一种钝器。它阻止了一个代理人
正在取得进展,就像陷入困境一样快。
OmniCoreAgent在整个循环中跟踪SHA256支持的工具调用签名。每
签名基于调用的工具名称、输入和输出。运行时
检测:
- 连续循环:同一个工具调用重复返回相同的结果。
- 图案循环:同一个工具重复一个小的交互模式。
当线束停止循环时,代理会得到一个原因。这使得调试
代理行为比“达到最大迭代次数”容易得多
4.线束已经组装好
OmniCoreAgent作为可工作的代理工具发货,而不是一袋断开连接的部件:```text
model + prompt + loop + tools + memory + context + workspace + guardrails + events
对于简单的特工,保持其较小的尺寸,然后在出现以下情况时打开较重的安全带
工作量需要他们:MCP工具、BM25工具检索、动态子代理、技能、,
云工作空间存储、Redis/Postgres/MongoDB内存、事件流和
OmniServe。
### 5.在模型调用之前管理上下文
启用上下文管理后,OmniCoreAgent会检查活动消息
每次LLM请求前的历史记录。如果超过配置的阈值
在调用模型之前,harness会自动应用所选策略:```text
messages -> threshold check -> truncate or summarize+truncate -> LLM
系统提示被保留,最近的消息被保留,旧的中间
根据配置,历史记录会被总结或删除。如果你设置
如果预算低于模型的实际上下文窗口,则线束将在
提供者拒绝了该请求。
在行动中看到它```python
import asyncio
from omnicoreagent import MemoryRouter, OmniCoreAgent, ToolRegistry
tools = ToolRegistry()
@tools.register_tool("search_web")
def search_web(query: str) -> dict:
"""Search the web for information."""
return {"results": [f"Result for: {query}"]}
@tools.register_tool("read_file")
def read_file(path: str) -> dict:
"""Read a local project file."""
return {"path": path, "content": f"Contents of {path}"}
agent = OmniCoreAgent(
name="research-agent",
system_instruction=(
"You are a research assistant. Use tools in parallel when the calls are "
"independent and you can reason over the results together."
),
model_config={"provider": "openai", "model": "gpt-4o"},
local_tools=tools,
memory_router=MemoryRouter("in_memory"),
agent_config={
"max_steps": 20,
"context_management": {"enabled": True},
"tool_offload": {"enabled": True},
"enable_subagents": True,
"enable_advanced_tool_use": True,
},
)
async def main():
result = await agent.run(
"Search for recent AI agent papers and read notes.md. Do both at once "
"if neither depends on the other."
)
print(result["response"])
await agent.cleanup()
asyncio.run(main())
运行时接受 `search_web` 和 `read_file` 在同一批中,返回两者
将结果放在一起,并从一个结构化的观察中继续。
______________________________________________________________________
## 只安装您需要的东西```bash
pip install omnicoreagent # Core runtime
pip install "omnicoreagent[redis]" # Redis memory + event streams
pip install "omnicoreagent[postgres]" # PostgreSQL / SQL memory
pip install "omnicoreagent[mongodb]" # MongoDB memory
pip install "omnicoreagent[s3]" # S3 / R2 workspace storage
pip install "omnicoreagent[serve]" # OmniServe REST/SSE API
pip install "omnicoreagent[all]" # Everything
生产后端是可安装的额外组件。仅安装代理实际安装的内容
使用。
特性
| 功能 | 它做什么 |
|---|---|
| 并行批处理工具执行 | 同时执行独立的工具调用,并向模型返回一个组合观察结果。 |
| 结构化观测管道 | 在模型看到之前配置时,分析、格式化、护栏检查和卸载工具结果。 |
| 基于签名的循环检测 | 检测重复的SHA256支持的工具调用签名和超过步数耗尽的重复工具交互模式。 |
| MCP原生工具 | 通过stdio、SSE和Streamable HTTP连接MCP服务器,包括支持OAuth的远程服务器。 |
| 本地工具注册表 | 将Python函数注册为具有推断模式和异步/同步执行支持的工具。 |
| 多层存储器 | 通过内存路由器使用内存、Redis、MongoDB或SQL支持的会话历史记录。 |
| 运行时后端切换 | 配置后,在运行时切换内存和事件后端。 |
| 工作区文件 | 为代理提供本地、S3或R2支持的文件工作区,用于笔记、草稿、工件和工具卸载。 |
| 语境工程 | 在每次模型调用之前检查上下文,并在超过配置的预算阈值时自动截断或汇总。 |
| 刀具输出卸载 | 将大型工具结果写入工作区文件,并为模型提供预览和文件引用。 |
| 动态子代理 | 让主代理生成具有隔离上下文和共享工作区输出的专注工作者。 |
| 代理技能 | 加载用Python、Bash或Node.js实现的打包功能。 |
| BM25工具检索 | 从大型工具集中选择相关工具,使提示保持焦点。 |
| 护栏 | 在观察路径内添加具有可配置行为的快速注射筛查。 |
| 事件系统 | 为代理运行、工具调用和流式集成发出结构化运行时事件。 |
| 工作流程编排 | 为多步骤应用程序工作流提供顺序、并行和路由器代理。 |
| 后台代理 | 支持基于时间间隔的工作负载的计划自主任务。 |
| 通用模型 | 通过LiteLLM路由到OpenAI、Anthropic、Gemini、Groq、Ollama、DeepSeek、Mistral、OpenRouter、Azure和Cencori |
| OmniServe | 将代理转换为具有生命周期管理和度量的REST/SSE服务。 |
实施图
OmniCoreAgent的功能由具体的运行时模块支持:
| 能力 | 它住在哪里 |
|---|---|
| 并行工具批次 | core/tools/tool_batch_runner.py |
| XML工具调用契约 | core/agents/xml_parser.py |
| 结构化观察 | core/tools/tool_observation.py |
| 工具输出卸载 | core/workspace/artifacts.py |
| 自动上下文控制 | core/agents/llm_step.py, core/context_manager.py |
| 工作区文件 | core/workspace/tools.py, core/workspace/storage.py |
| 动态子代理 | core/subagents.py |
| 回路检测 | core/agents/loop_detection.py |
| MCP服务器工具 | mcp_clients_connection/client.py |
| OmniServe | serve/ |
看 Agent Harness文档
查看完整的实施图。
食谱
所有的例子都在 食谱 并按用例进行组织。
| 类别 | 你将构建什么 |
|---|---|
| 入门指南 | 第一代理、工具、记忆、事件 |
| 工作流 | 顺序、并行、路由器代理 |
| 后台代理 | 计划自主任务 |
| 生产 | 护栏、服务和生产模式 |
配置
环境变量
对于第一次运行,大多数托管模型提供程序只需要 LLM_API_KEY.
OmniCoreAgent默认内存和事件为内存存储,工作区文件为
在配置之前,本地磁盘和可选的生产集成将保持关闭状态
他们。```bash
export LLM_API_KEY=your_api_key
仅当您选择使用Redis、MongoDB、SQL时,才添加后端特定变量
数据库存储、S3、R2或OmniServe部署设置。
### 完整线束配置示例
默认设置使第一个代理保持较小:工作区文件和护栏打开,
对话记忆在记忆中,高级安全带会一直关闭,直到
你启用它们。此示例显示了生产样式的切换。```python
agent_config = {
"max_steps": 15,
"tool_call_timeout": 30,
"request_limit": 0, # 0 = unlimited
"total_tokens_limit": 0, # 0 = unlimited
"memory_config": {
"mode": "sliding_window",
"value": 10000,
"summary": {"enabled": False},
},
"enable_workspace_files": True, # Default on
"guardrail_mode": "full", # Default
"context_management": {"enabled": True}, # Default off
"tool_offload": {"enabled": True}, # Default off
"enable_advanced_tool_use": True, # Default off
"enable_subagents": True, # Default off
"enable_agent_skills": True, # Default off
}
当 enable_subagents 如果为true,工作区文件将自动启用,因此
子代理将输出、笔记、待办事项和工件写入活动
工作空间。
> 完整参考: 配置指南
发展```bash
git clone https://github.com/omnirexflora-labs/omnicoreagent.git
cd omnicoreagent
uv venv && source .venv/bin/activate
uv sync --dev
pytest tests/ -v
pytest tests/ --cov=src --cov-report=term-missing
______________________________________________________________________
## 故障排除
|错误|修复|
|-------|-----|
| `Invalid API key` |出口 `LLM_API_KEY` 在中选择了提供者的密钥 `model_config`. |
| `ModuleNotFoundError` 对于Redis/Postgres/MongoDB/S3 |安装匹配的额外组件,例如 `pip install "omnicoreagent[redis]"`. |
| `Redis connection failed` |启动Redis或使用 `MemoryRouter("in_memory")`. |
| `MCP connection refused` |启动代理之前,请确保MCP服务器正在运行。 |
> 更多帮助: 基本使用指南
______________________________________________________________________
## 贡献```bash
git clone https://github.com/omnirexflora-labs/omnicoreagent.git
cd omnicoreagent
uv venv && source .venv/bin/activate
uv sync --dev
pre-commit install
看 贡献.md 作为指导方针。欢迎PR。
许可证
麻省理工学院-见 许可证.
作者
建造于 阿比奥拉·阿德希纳.
- GitHub: @Abiorh001
- X(推特): @芒果
- 电子邮件: abiolaadedayo1993@gmail.com
OmniRexFlora生态系统
| 项目 | 描述 |
|---|---|
| OmniMemory | 自主代理的自我进化记忆 |
| OmniCoreAgent | 生产代理线束(本项目) |
| OmniDaemon | 事件驱动的运行时,用于将代理作为受监督的自主基础设施服务运行 |
建立在
轻量级LLM - 快速API - 瑞迪斯 - 派丹蒂克
Star on GitHub -
Report Bug -
Request Feature -
Documentation
