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.5a1

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.5a1
File Size Uploaded Provenance Actions
ovos_agentic_loop-0.2.5a1.tar.gz 75.1 kB Without provenance Details for ovos_agentic_loop-0.2.5a1.tar.gz

Built distribution (wheel)

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

Total release size: 147.7 kB

Release files / ovos_agentic_loop-0.2.5a1.tar.gz

Download URL ovos_agentic_loop-0.2.5a1.tar.gz
Size 75.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6a2409da921d490af3506002a7348b226600a5316613edf680bf35ab9221d085
BLAKE2b-256 checksum
How to use checksums
9e4f32e6479e67d522084b7a86d59398a6c8afe9ed700141fd1436a6542c3632
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.5a1-py3-none-any.whl

Download URL ovos_agentic_loop-0.2.5a1-py3-none-any.whl
Size 72.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
470825ff2cbc140fd828554f0a4c20dc44e6f9e90536eaed8d195fb5a4cb6426
BLAKE2b-256 checksum
How to use checksums
af772c6ac6d4909beb0f9f5f165cb5e53aaa1f9c245f640d0e4519477c22238d
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.5a1

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