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

# The brain used in the examples below
pip install ovos-openai-plugin

# 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",
        "allow_system_prompts": True,
    },
    "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)

api_url is the /v1 root of the server. The brain adds /chat/completions itself. The loop sends its tool instructions as a system message, and ovos-chat-openai-plugin discards system messages unless allow_system_prompts is true. Without it, the model never sees the tool list and answers without calling a tool.

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",
      "allow_system_prompts": true
    },
    "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.4a3

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.4a3
File Size Uploaded Provenance Actions
ovos_agentic_loop-0.2.4a3.tar.gz 75.1 kB Without provenance Details for ovos_agentic_loop-0.2.4a3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ovos-agentic-loop 0.2.4a3
File Interpreter ABI Platform Actions
ovos_agentic_loop-0.2.4a3-py3-none-any.whl Python 3 none any Details for ovos_agentic_loop-0.2.4a3-py3-none-any.whl

Total release size: 147.7 kB

Release files / ovos_agentic_loop-0.2.4a3.tar.gz

Download URL ovos_agentic_loop-0.2.4a3.tar.gz
Size 75.1 kB
Tags Source
SHA-256 checksum
How to use checksums
374da485d8e6bca3f88a601a2225ec9e1f8626a08fcbb1462bb0691af830df8a
BLAKE2b-256 checksum
How to use checksums
2fcfced19c1aa2aac519cae6e8c9a77a704a167f28b17d73fa7cf35d6680d860
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ovos_agentic_loop-0.2.4a3-py3-none-any.whl

Download URL ovos_agentic_loop-0.2.4a3-py3-none-any.whl
Size 72.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c7892ebbae2ff0dde6c67ed4b28aa5adc2041a79c1a0fa246f5a90482106c436
BLAKE2b-256 checksum
How to use checksums
b5db54282a53dda1fdd2097f65e01d3fa067393ce5b489934b3855d68ee48627
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ovos-agentic-loop 0.2.4a3

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