OmniAgent

OmniAgent is a Rails engine gem for building application-native AI agents with tools. It provides a small DSL to define agents, model/provider settings, prompt templates, tool schemas, and generation lifecycle callbacks.

What It Includes

• OmniAgent::Agent runtime with provider abstraction and tool-calling loop
• OmniAgent::Tool DSL with JSON-schema-style input definitions
• Structured, validated agent output declared with the same DSL as tool input
• Stock agents: ready-made agents shipped with the gem that projects subclass and customize
• Prompt composition from ERB files in app/agents/<agent_name>/
• Agent callbacks (before_generation, after_generation)
• Agent and tool tags to support filtering strategies
• OpenAI provider integration out of the box, plus an Ollama provider for local models
• RAG: has_embedding models, has_chunks documents (PDF, Markdown, HTML) and searches tools over pgvector, sqlite-vec, MariaDB or Meilisearch
• MCP server support: expose tools and whole agents to Claude Code, Claude Desktop, Cursor and other MCP clients
• Rake tasks and Rails generators for scaffolding

Installation

Add these lines to your application's Gemfile:

gem "omni_agent"

Add the provider you're using to the Gemfile as well:

gem "openai"

The ollama provider also depends on the openai gem — it talks to Ollama's OpenAI-compatible endpoint, so no separate gem is needed.

Then run:

bundle install

Quick Start

1. Install base directories and the initializer:

bundle exec rails generate omni_agent:install

This also adds an OmniAgent section to AGENTS.md (and CLAUDE.md, if present) that points coding agents at the bundled docs. Pass --skip-agents-md to leave those files alone.

2. Generate an agent scaffold:

bundle exec rails generate omni_agent:agent ResearchAgent --model gpt-4.1-mini --with-tools WeatherLookup Summarize

3. Add your API key in .env:

OPENAI_ACCESS_TOKEN=your_api_key_here

To use Ollama instead, set config.default_provider = :ollama (see below) and, if needed, override its endpoint/model:

OLLAMA_HOST=http://localhost:11434   # defaults to this
OLLAMA_MODEL=llama3.1                # defaults to this; pick a tool-calling-capable model
OLLAMA_API_KEY=ollama                # unused by Ollama, but required by the openai client

4. Implement your agent prompt and optional tools under:

app/agents/
	research_agent.rb
	research_agent/
		prompt.md.erb
		tools/

Agent Example

class ResearchAgent < OmniAgent::Agent
	use_model "gpt-4o-mini"

	before_generation :set_current_user

	def set_current_user
		@user = "Test User"
	end
end

Tool Example

module ResearchAgent::Tools
	class GetWeather < OmniAgent::Tool
		description "Get current weather for a city"
		tags :weather
		metadata category: :utility

		input do
			string :city, description: "City name"
		end

		def execute(city:)
			"Sunny in #{city}"
		end
	end
end

Structured Output

Declare an output block, using the same DSL as tool input, to get a validated object back instead of free text:

class InvoiceAgent < OmniAgent::Agent
	output do
		string :invoice_number
		number :total, min: 0
		enum :currency, values: %w[USD EUR]
	end
end

InvoiceAgent.new.run(invoice_text).structured_output
# => { invoice_number: "A-1042", total: 120.5, currency: "USD" }

The schema is sent to the provider (as a json_schema response_format for OpenAI and Ollama), and the final answer is parsed and validated with the same rules as tool input. Invalid JSON or a schema mismatch raises OmniAgent::StructuredOutputError.

Stock Agents

Stock agents are ready-made agents shipped with the gem under OmniAgent::StockAgents. Subclass one in your app and declare the output you need; the subclass keeps the stock prompt, model and tools:

rails generate omni_agent:stock_agent InvoiceOcr --from=ocr --fields=invoice_number:string total:number

class InvoiceOcr < OmniAgent::StockAgents::OCR
	output do
		string :invoice_number
		number :total
	end
end

InvoiceOcr.new.run([ Pathname("page1.jpg"), Pathname("page2.jpg") ]).structured_output

The OCR stock agent reads images and PDFs from paths, uploaded files, ActiveStorage attachments or URLs, one at a time or several pages together.

To add a stock agent to the gem itself, run bin/rake "stock_agent:new[name]" from the gem repository.

Multi-Agent Delegation

delegate_to turns an agent into a supervisor: it wraps another agent class as a tool, so the supervisor's LLM can decide when to hand off to it. The delegated agent is a normal, independently defined agent (e.g. app/agents/research_agent.rb) — no manual tool file needed.

class SupervisorAgent < OmniAgent::Agent
	use_model "gpt-4o"

	delegate_to ResearchAgent, as: :research,  description: "Look up factual info"
	delegate_to MathAgent,     as: :calculate, description: "Do arithmetic"
end

Each delegated agent runs in isolation (its own fresh instance, no shared context) and returns its final answer as the tool result. Delegation depth is capped by OmniAgent.configuration.max_delegation_depth (default 5) to guard against runaway recursive delegation; exceeding it raises OmniAgent::MaxDelegationDepthError.

Pass run_alias: to call a run_aliases method (or any zero-arg run entrypoint) on the delegated agent instead of its default #run — useful when the sub-agent should render a different prompt file for delegated calls:

class SupervisorAgent < OmniAgent::Agent
	delegate_to SupportAgent, as: :triage_ticket, run_alias: :triage
end

Pass forward: to share part (or all) of the supervisor's context with the delegated agent — an array of context keys, or true to forward everything. Omitted keys, and the default (forward: []), keep the delegated agent fully isolated:

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗