Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

ovos-agentic-loop

PyPI License Python

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 ChatEngine as 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_shell defaults to False. Only enable with fully-trusted LLMs. The command string is passed directly to /bin/sh.
  • FileSystemToolBox: set root_path to restrict file access to a subtree. Without it, the agent can read any world-readable file.
  • MathToolBox: uses ast.parse with an allowlist. eval() is never called.

Documentation


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)

Source distribution for ovos-agentic-loop 0.2.4a1
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)

Table of built distributions (wheels) for ovos-agentic-loop 0.2.4a1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page