llm.rb

What does this agent do, and when should you use it?

llm.rb (repository r-uby-dev/llm) is a runtime for building agentic AI applications on CRuby, with zero runtime dependencies by default and a single coherent API spanning 14+ providers including Anthropic, OpenAI, DeepSeek, Google, Ollama, and llama.cpp. Its high-level interface, LLM::Agent, automatically manages tool execution, guards against infinite loops, and maintains conversation state, while LLM::Stream exposes structured callbacks for content, reasoning, tool calls, and compaction. The runtime ships first-class MCP and A2A protocol support, LLM::Schema structured outputs, LLM::Guard tool-call policy hooks, LLM::Transformer message rewriting, LLM::Compactor context-window management, and OpenTelemetry-based observability. Persistence ranges from filesystem JSON to ActiveRecord and Sequel (with PostgreSQL b optimization), and a curses-based interactive console plus an llm.rb CLI are bundled. It is MIT-licensed and also mirrored on the Radicle network.

After gem install llm.rb, developers create a provider via class-level factories (e.g. LLM.deepseek, LLM.openai), hand it to LLM::Agent, and drive turns with agent.talk. The agent can execute: Ruby tools as LLM::Tool subclasses (with a built-in catalog of filesystem, search, and shell tools, run under one of six concurrency strategies: :async/:thread/:fiber/:fork/:ractor/:sequential); markdown-defined Skills that spawn a fresh, stateless subagent per call; tools from MCP servers via LLM::MCP.stdio/.http; and remote A2A agent skills via LLM::A2A.rest. LLM::Schema yields validated JSON structured outputs, LLM::Guard can let through, cancel, block, or answer tool calls (LLM::Guard::Loop protection is on by default), LLM::Transformer rewrites outgoing messages, LLM::Compactor::Truncate keeps conversations within the context window, and 429s and timeouts are retried automatically up to retry_budget (default five). LLM::Agent#interrupt! aborts a request mid-stream from any thread and interrupts running tools. The embedding API (llm.embed) supports RAG with sqlite-vec/pgvector; OpenAI, Google, xAI, and DeepInfra generate images, and DeepSeek generates SVG graphics through its text model.

1. Ruby/Rails developers who need to integrate multiple LLM providers and switch between them with a one-line change.
2. Teams building agents that use filesystem, shell, or search tools and require concurrent or parallel tool execution.
3. Teams with an ActiveRecord/Sequel stack that want database-backed chatbots (as the r.uby.dev chatbot does with acts_as_agent and b).
4. Integrations that need remote MCP servers or A2A agents exposed as local agent tools.
5. Budget-conscious developers using cheap models like DeepSeek while gaining structured outputs and image (SVG) generation as runtime enhancements.
6. Developers who want to debug agents, test tools, and manage sessions interactively via the curses console or the llm.rb CLI.

What are this agent's strengths and limitations?

How do you install or deploy this agent?

Install the gem:

gem install llm.rb

For the full console experience, install optional dependencies separately:

gem install unicode-display_width curses kramdown xchan.rb test-cmd.rb

Set API keys via environment variables (e.g. DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY); local providers (Ollama, llama.cpp) typically need no key.

How do you use this agent?

Minimal example:

require "llm"

llm = LLM.deepseek(key: ENV["KEY"])
agent = LLM::Agent.new(llm, stream: $stdout)
agent.talk "hello world"

Add custom tools by defining LLM::Tool subclasses (name/description/parameter/required, implement call) and passing tools:. Persistence: LLM::Agent.new(llm, path: "session.") saves and restores sessions automatically. Database persistence: require "llm/active_record" and use acts_as_agent(format: :b) on a model. CLI: run llm.rb (auto-detects provider from env vars), llm.rb -p openai to pick a provider, llm.rb -t for a temporary session; sessions persist under ~/.llm.rb/. MCP: mcp = LLM::MCP.stdio(argv: ["ruby", "server.rb"]) then pass mcp.tools to the Agent.

How does this agent compare with similar options?

FAQ