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 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

Built-in Toolboxes

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

• 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.