This release is a pre-release and may not be stable for production use.
ovos-agentic-loop
Agent-loop ChatEngine plugins for OVOS. This package implements seven agentic reasoning patterns: ReAct, Plan-and-Execute, Reflexion, Self-Ask, Chain-of-Thought, CRITIC, and Tree-of-Thoughts. It also ships five built-in toolboxes, SKILL.md integration, and AGENTS.md context management. All components ship as standard OPM plugins.
Features
- 7 loop architectures: from simple Chain-of-Thought to full Reflexion and Tree-of-Thoughts beam search
- 5 built-in toolboxes: filesystem, shell, web search, clock, math (calculator + unit conversion + statistics)
- SKILL.md toolbox: turns any installed SKILL.md file into an agent tool
- AGENTS.md context manager: loads structured system prompts from AGENTS.md files at runtime
- No LLM bundled: wire any OPM
ChatEngineas the inner brain - No persona bundled: compose your own persona using the provided primitives
Installation
pip install ovos-agentic-loop
# Optional: web search support
pip install 'ovos-agentic-loop[web]'
Quick Start
Minimal ReAct agent with a calculator
from ovos_agentic_loop.react import ReActLoopEngine
from ovos_agentic_loop.tools.math import MathToolBox
from ovos_plugin_manager.templates.agents import AgentMessage, MessageRole
# Wire a local LLM as the brain (any OPM ChatEngine works)
engine = ReActLoopEngine({
"brain": "ovos-chat-openai-plugin",
"ovos-chat-openai-plugin": {
"api_url": "http://localhost:11434/v1/chat/completions",
},
"max_iterations": 8,
})
engine.load_toolboxes([MathToolBox()])
response = engine.continue_chat([
AgentMessage(role=MessageRole.USER, content="What is 17 * 23 + sqrt(144)?")
])
print(response.content)
Persona JSON (all-in-one config)
{
"name": "MyAgent",
"solvers": ["ovos-react-loop"],
"ovos-react-loop": {
"brain": "ovos-chat-openai-plugin",
"ovos-chat-openai-plugin": {
"api_url": "http://localhost:11434/v1/chat/completions"
},
"toolboxes": ["ovos-math-tools", "ovos-web-search-tools", "ovos-clock-tools"],
"max_iterations": 10
}
}
Loop Architectures
| Entry point | Class | Best for |
|---|---|---|
ovos-react-loop |
ReActLoopEngine |
General tool-using Q&A |
ovos-plan-execute-loop |
PlanAndExecuteEngine |
Multi-step tasks requiring a plan |
ovos-reflexion-loop |
ReflexionEngine |
Tasks requiring self-critique and retry |
ovos-self-ask-loop |
SelfAskEngine |
Compositional questions needing sub-questions |
ovos-chain-of-thought-loop |
ChainOfThoughtEngine |
Reasoning without tools (math, logic) |
ovos-critic-loop |
CRITICEngine |
Factual tasks requiring claim verification |
ovos-tree-of-thoughts-loop |
TreeOfThoughtsEngine |
Exploration-heavy problems (beam search) |
Built-in Toolboxes
| Entry point | Class | Tools |
|---|---|---|
ovos-math-tools |
MathToolBox |
evaluate_expression, unit_convert, statistics_summary, solve_equation |
ovos-filesystem-tools |
FileSystemToolBox |
read_file, write_file, list_directory, search_in_files, find_files |
ovos-shell-tools |
ShellToolBox |
run_command (disabled by default; set allow_shell: true to enable) |
ovos-web-search-tools |
WebSearchToolBox |
web_search (requires ovos-agentic-loop[web]) |
ovos-clock-tools |
ClockToolBox |
get_current_datetime |
ovos-skill-md-toolbox |
SkillMDToolBox |
One tool per installed SKILL.md |
SKILL.md Integration
Any package that ships a SKILL.md file is automatically discovered and exposed as an agent tool:
---
name: my-skill
description: Does something useful.
---
You are a helpful assistant specialised in...
The tool name is the slugified name field. The SKILL.md body becomes the system prompt for a sub-LLM call.
AGENTS.md Context Management
AgentsMDContextManager assembles system prompts from AGENTS.md files at runtime. These are the same files Claude Code reads at dev-time:
from ovos_agentic_loop.context.agents_md import AgentsMDContextManager
ctx = AgentsMDContextManager({
"agents_md_sources": ["auto"], # auto-discover from installed packages
"include_sections": ["Rules", "Style"], # filter to specific headings
})
messages = ctx.build_conversation_context(utterance, session_id="s1")
Security Notes
ShellToolBox:allow_shelldefaults toFalse. Only enable with fully-trusted LLMs. The command string is passed directly to/bin/sh.FileSystemToolBox: setroot_pathto restrict file access to a subtree. Without it, the agent can read any world-readable file.MathToolBox: usesast.parsewith an allowlist.eval()is never called.
Documentation
- docs/loop-architectures.md: all 7 loop engines with algorithm details
- docs/react-loop.md: ReAct prompt format and parsing
- docs/toolboxes.md: all toolbox schemas and config keys
- docs/skill-md.md: SKILL.md authoring and packaging guide
- docs/agents-md.md: AGENTS.md context manager reference
- docs/opm-integration.md: OPM entry points and persona wiring
License
Apache 2.0. See LICENSE.
Credits
Developed by TigreGotico for OpenVoiceOS.
Funded by NGI0 Commons Fund / NLnet under grant agreement No 101135429, through the European Commission's Next Generation Internet programme.
Metadata
Release files for ovos-agentic-loop 0.2.4a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ovos_agentic_loop-0.2.4a1.tar.gz | 74.8 kB | Without provenance | Details for ovos_agentic_loop-0.2.4a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ovos_agentic_loop-0.2.4a1-py3-none-any.whl | Python 3 | none | any | Details for ovos_agentic_loop-0.2.4a1-py3-none-any.whl |
Total release size: 147.2 kB
Release files / ovos_agentic_loop-0.2.4a1.tar.gz
| Download URL | ovos_agentic_loop-0.2.4a1.tar.gz |
|---|---|
| Size | 74.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
007d46a8e6f1e34451e003d847d1e8edf68c47aef03e5b02096cac7f2b5c4d67
|
|
BLAKE2b-256 checksum How to use checksums |
71315ccb8fec21b3c64eecb3ed902b06c4f51c996b4c0b52bc291b7116405c70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ovos_agentic_loop-0.2.4a1-py3-none-any.whl
| Download URL | ovos_agentic_loop-0.2.4a1-py3-none-any.whl |
|---|---|
| Size | 72.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3bce93c6cc2d5443357a5c28157296d8083f51f20dc1fc495fb7ffb176b96ab7
|
|
BLAKE2b-256 checksum How to use checksums |
5a097004d332b4aef8ff0e0e9bea9fdf094917db5aebf61a4474f986da97b2d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for ovos-agentic-loop 0.2.4a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.