Active Agent

Appearance

Tools and Actions ​

Active Agent supports tool/function calling, allowing agents to interact with external services and perform actions.

Tool Support ​

Agents can define and use tools to extend their capabilities:

ruby
class SupportAgent < ApplicationAgent
  layout "agent"
  generate_with :openai, model: "gpt-4o-mini", instructions: "You're a support agent. Your job is to help users with their questions."

  def get_cat_image
    prompt(content_type: "image_url", context_id: params[:context_id]) do |format|
      format.text { render plain: CatImageService.fetch_image_url }
    end
  end
end

Tool Usage Example ​

Here's how an agent uses tools to fulfill user requests:

ruby
message = "Show me a cat"
prompt = SupportAgent.with(message: message).prompt_context

Tool Call Response ​

When a tool is called, the response includes the tool's output in the conversation:

ruby
response = prompt.generate_now
Response Example

activeagent/test/agents/support_agent_test.rb:20

ruby
# Response object
#<ActiveAgent::GenerationProvider::Response:0x350c
  @message=#<ActiveAgent::ActionPrompt::Message:0x3520
    @action_id=nil,
    @action_name=nil,
    @action_requested=false,
    @charset="UTF-8",
    @content="Here is a cat for you!\n\n![Cat](https://cataas.com/cat/wC7CCD0kGtXmyXVF?position=center&width=100)",
    @role=:assistant>
  @prompt=#<ActiveAgent::ActionPrompt::Prompt:0x3534 ...>
  @content_type="text/plain"
  @raw_response={...}>

# Message content
response.message.content # => "Here is a cat for you!\n\n![Cat](https://cataas.com/cat/wC7CCD0kGtXmyXVF?position=center&width=100)"

Tool Response Structure ​

When tools are used, the response includes:

  • System Message: Initial instructions for the agent
  • User Message: The original user request
  • Assistant Message: The agent's decision to use a tool
  • Tool Message: The result from the tool execution

The final response contains 4 messages showing the complete tool interaction flow.

Implementing Tools ​

Tools are defined as methods in your agent class. The tool's JSON schema is defined in the corresponding view template:

Tool Implementation ​

ruby
class SupportAgent < ApplicationAgent
  layout "agent"
  generate_with :openai, model: "gpt-4o-mini", instructions: "You're a support agent. Your job is to help users with their questions."

  def get_cat_image
    prompt(content_type: "image_url", context_id: params[:context_id]) do |format|
      format.text { render plain: CatImageService.fetch_image_url }
    end
  end
end

Tool Schema Definition ​

erb
<%= {
  type: :function,
  function: {
    name: 'get_cat_image',
    description: "This action takes no params and gets a random cat image and returns it as a base64 string.",
    parameters: {
      type: :object,
      properties: {}
    }
  }
}.to_json.html_safe %>

See how tools are called and executed in multi-turn conversations →