Building AI Agents in Ruby with the Anthropic SDK
An AI agent is a language model that actually does things. You hand it a goal and a set of tools (functions it is allowed to call), and it decides which to use, runs them, reads the results, and keeps going until the task is done. That loop of deciding, acting, and observing is what separates an agent from a single prompt. A support agent that looks up customer invoices and drafts a reply, or an internal tool that pulls from three systems to answer a question, is an agent in this sense.
The official Anthropic Ruby SDK ships with streaming, connection pooling, and a tool runner that handles the agent loop for you. This post covers what an agent actually is, how to structure one in Rails, how to design tools the model can use reliably, and the production concerns that make the difference between a demo and something you can actually ship.
What an Agent Actually Is
The concept is simple. In Anthropic's words, "agents are typically just LLMs using tools based on environmental feedback in a loop" (Building Effective Agents). The model receives a goal, decides whether it needs to call a tool, you execute the tool and feed the result back, and the loop repeats until the model stops asking for tools.
The same article draws a distinction worth understanding before you write any code. "Workflows are systems where LLMs and tools are orchestrated through predefined code paths," while "agents are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks." Workflows are predictable and consistent; agents are flexible at the cost of higher latency, higher token spend, and the potential for compounding errors. Which of these you actually need is the call that matters here, and the honest answer is usually "less agent than you think."
Anthropic's own guidance is to find "the simplest solution possible, and only increasing complexity when needed." For many features, a single well-prompted model call with good context beats an autonomous agent: cheaper, faster, and easier to debug. Reach for a true loop only when the task is open-ended enough that you genuinely cannot predict the steps in advance.
The Minimal Agent Loop in Ruby
Start with the official gem:
# Gemfile<br>gem "anthropic"
The client is threadsafe and maintains its own connection pool, so create it once and reuse it. An initializer is the natural home:
# config/initializers/anthropic.rb<br>ANTHROPIC = Anthropic::Client.new(<br>api_key: ENV.fetch("ANTHROPIC_API_KEY")
A single model call looks like this:
message = ANTHROPIC.messages.create(<br>model: "claude-sonnet-4-6",<br>max_tokens: 1024,<br>messages: [{ role: "user", content: "Summarize Q1 in one sentence." }]
puts message.content
That is not yet an agent, because there is no loop and no tools. The loop is what makes it agentic: send the conversation to the model, check whether it wants to use a tool, run the tool, append the result to the conversation, and repeat until it stops asking for tools. Written by hand, the loop is only a dozen lines, and it is worth seeing once before you let the SDK handle it, because understanding what is under the abstraction is what lets you debug it when it breaks.
def run_agent(client:, tools:, messages:, model: "claude-sonnet-4-6")<br>loop do<br>response = client.messages.create(<br>model: model,<br>max_tokens: 1024,<br>tools: tools.map(&:definition),<br>messages: messages
# The model is done when it stops asking to use tools.<br>break response if response.stop_reason != "tool_use"
messages { role: "assistant", content: response.content }
tool_results = response.content<br>.select { |block| block.type == "tool_use" }<br>.map { |block| execute_tool(tools, block) }
messages { role: "user", content: tool_results }<br>end<br>end
This is the core of every agent. Everything else is refinement: better tools, streaming, error handling, observability, and guardrails. The model drives, your code executes the tools, and each result feeds back so the model can judge its own progress.
Designing Tools the Model Can Actually Use
You will spend more time on your tools than on your prompts. When Anthropic built their own coding agent, they spent more time optimizing the tools than the overall prompt. A tool definition is an interface, and the model is the consumer of that interface. A confusing tool produces a confused agent.
Anthropic frames this as the agent-computer interface, or ACI: "Think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good agent-computer interfaces (ACI)." A tool definition should read like a docstring written for a competent new engineer with no other context: what it does, when to use it, what each parameter means, and where the edges are.
The official SDK lets you define tools as Ruby classes with a typed input schema:
class LookupInvoicesInput Anthropic::BaseModel<br>required :customer_id, Integer<br>optional...