OmniAgents

OmniAgents provides a lightweight wrapper around the OpenAI Agents library. It offers several ways to run your assistant:

• Web – React-based web UI with optional realtime voice controls
• Ink – React Ink terminal UI
• Server – expose an agent through a JSON‑RPC WebSocket API

Agents are described using a small YAML file which lists available tools and where to load them from. You can also build an agent directly in Python and run it with the same interface.

Installation

Quick Install:

pip install --upgrade --index-url https://pypi.fury.io/ericmichael/ --extra-index-url https://pypi.org/simple "omniagents[all]"

Requirements:

• Python 3.11+
• Node.js and npm (for Ink TUI and Web UI backends)

See the installation guide for detailed instructions.

Configuration

Most examples expect an OpenAI API key which can be provided via the OPENAI_API_KEY environment variable. Additional fields defined in your YAML file are persisted locally. Conversation history for sessions is stored in sessions.db.

Defining an agent

A minimal YAML specification might look like:

name: DemoAgent
instructions_file: instructions.md
# tools directory is scanned automatically
tools: [get_current_time, flip_coin]
use_safe_agent: true
# Optional UI layout: "tabs" separates conversation and tool logs
layout: tabs

Each tool is a Python function decorated with @function_tool from omniagents.core. See examples/basic_python/tools.py for reference.

Running

Web mode (default)

Run the web UI:

omniagents run -P path/to/project.yml --mode web

Use --dev to run with hot reload during development.

Voice mode is available in web UI. To switch the server-side voice implementation, set voice_backend in your agent YAML (realtime (default) or pipeline). Pipeline voice requires omniagents[voice].

Ink TUI mode

Terminal UI using React Ink:

omniagents run -P path/to/project.yml --mode ink

Official wheels include a prebuilt bundle; from source, the backend can auto-build if Node/npm are available.

Server mode

JSON-RPC WebSocket API:

omniagents run -P path/to/project.yml --mode server --host 0.0.0.0 --port 8000

Use --session-id <id> to resume a previous conversation stored in sessions.db.

Studio

Serve the Studio web UI for viewing and managing traces:

omniagents studio serve --project <name>

Production builds serve packaged static assets; use --dev to run the web dev server (requires Node/npm).

This launches a FastAPI app exposing a WebSocket endpoint at /ws. The protocol is described in docs/remote_agent_protocol.md. A client can connect using RemoteAgentProxy from this package or any JSON‑RPC library.

Examples

• examples/basic_python – build an agent directly in Python
• examples/basic_yaml – define the agent in YAML
• examples/safe_agent_python and safe_agent_yaml – require approval before running tools
• examples/remote_agent – run the server and connect from another process

Development

Run the test suite with:

pytest -q

Run coverage locally with:

make coverage-all

Individual coverage targets:

• make coverage-python – Python agents, FastAPI server, and backends
• make coverage-web – React Studio UI via Vitest