Build AI features that feel at home in Ruby

LittleGhost is a Ruby library for building AI features with agents and composable assemblies. With OPENROUTER_API_KEY set, start with one class, give it a prompt, and call it like the rest of your application code:

require "little_ghost"

class CustomerSupportAgent < LittleGhost::Agent
  model "openrouter:openai/gpt-5.6-luna"
  system_prompt "Answer customer questions clearly and concisely."
end

run = CustomerSupportAgent.ask("Draft a friendly greeting for a customer.")
run.response
# One possible response: Hi! How can I help today?

That small definition is already a complete agent. LittleGhost makes the model call, tracks usage, supports streaming, and closes the resources it creates for the request. Add a tool when the agent needs something from your application. Bring in more agents when the work grows.

Model requests may send system instructions, caller input, conversation history, tool results, and attachments to the selected external provider. Model wording can vary between runs. Choose providers and the data you send them with the same care as any other external service.

Install the gem

LittleGhost requires Ruby 3.3 or newer. Add it to your bundle and provide a provider credential:

gem "little_ghost"

$ bundle install
$ export OPENROUTER_API_KEY="..."

OpenRouter keeps the first setup to one credential. It is not required: LittleGhost also includes adapters for OpenAI-compatible APIs, Anthropic, Gemini, Vertex AI, and Bedrock. Running in Production shows how to configure providers and give model choices application-facing names.

LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI, or service. If you want a conventional layout, start with app/agents, app/assemblies, app/prompts, and app/tools.

Give an agent real capabilities

Tools let an agent call focused parts of your application:

class HelpCenterLookupTool < LittleGhost::Tool
  description "Look up a help center entry by topic."
  input_schema(
    type: "object",
    properties: {topic: {type: "string"}},
    required: ["topic"],
    additionalProperties: false
  )

  def call(input)
    {"refunds" => "Refunds are available within 30 days."}
      .fetch(input.fetch("topic"), "No help center entry found.")
  end
end

class CustomerSupportAgent < LittleGhost::Agent
  model "openrouter:openai/gpt-5.6-luna"
  system_prompt "Check the help center before stating company guidance."
  tools HelpCenterLookupTool
end

The schema checks the shape of the input. Your Ruby code still decides whether the operation is allowed and safe. The result goes back to the model as context.

Grow without changing the caller

An agent owns one model loop. An assembly is one or more agents working as a unit. You call either one the same way:

CustomerSupportAgent.ask(question)
ResponseWorkflow.ask(question)
ProblemSolverSwarm.ask(question)
SupportFlowGraph.ask(question)

Choose the coordination style that matches who should control the next step:

• A subagent lets a model delegate an addressable task.
• A workflow uses ordinary Ruby for ordering and branching.
• A swarm lets configured agents choose permitted handoffs.
• A graph makes allowed routes explicit as nodes and edges.

A Workflow or Graph can contain agents, other assemblies, or both. Named classes are the clearest place to begin. Builders are there when your application discovers the participants or routes at runtime.

request ──> CustomerSupportAgent

request ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent

request ──> ProblemSolverSwarm ──> TriageAgent ──handoff──> BillingAgent

request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseAgent

The result stays familiar too. Every call returns a Run with the response, outcome, usage, and any final error. A coordinated assembly also records which participants ran. Use .stream_ask to watch the work as it happens.

Growing in public. LittleGhost is under active development, and interfaces may evolve between releases. Pin the gem version and review release notes when upgrading.

Keep going

• Getting Started takes you from installation to a tool-backed, streaming agent.
• Core Concepts builds the mental model from Agent to Assembly.
• Compose Agents walks through workflows, swarms, graphs, nesting, and builders.
• Prompts as Views gives growing instructions, shared pieces, and application values a natural home.
• Running in Production covers configuration, sessions, execution, observability, and trust boundaries.
• API reference provides exact signatures and lifecycle contracts.

For contributors

See the contributing guide, Code of Conduct, and security policy.

$ bundle install
$ bundle exec rake test
$ bundle exec standardrb --no-fix

LittleGhost is available under the MIT License.