Building a Weather Agent with Jido Agent SDK

Mix.install([
  {:jido, "~> 1.1.0-rc.2"},
  {:jido_ai, "~> 0.5.1"},
  {:jido_tools, "~> 0.1.1"},
])

Introduction

The Jido Agent SDK makes it easy to build AI-powered agents in Elixir. In this guide, we’ll create a Weather Agent that can respond to natural language queries about weather conditions in different locations.

Our Weather Agent will:

Process natural language questions about weather
Use a weather tool to fetch data
Respond in the style of an enthusiastic weather reporter

Setup

Before we can use our agent, we need to set up API keys:

# Check if OpenAI API key is set
openai_api_key = System.get_env("LB_OPENAI_API_KEY") || System.get_env("OPENAI_API_KEY")

if is_nil(openai_api_key) do
  IO.puts("OpenAI API key not found. Click the 'Add Secret' button below to add it.")
  System.fetch_env!("LB_OPENAI_API_KEY")
else
  "OpenAI API key configured successfully!"
end

# The OpenWeather API key is optional for this demo since we'll use test data
weather_api_key = System.get_env("LB_OPENWEATHER_API_KEY") || System.get_env("OPENWEATHER_API_KEY")

if is_nil(weather_api_key) do
  "No OpenWeather API key found. We'll use test data for our examples."
else
  "OpenWeather API key configured successfully!"
end

Quick Demo

Let’s create and use our Weather Agent right away:

defmodule WeatherAgent do
  use Jido.Agent, name: "weather_agent"

  def start_link(_opts \\ []) do
    Jido.AI.Agent.start_link(
      agent: __MODULE__,
      # log_level: :info,
      ai: [
        model: {:openai, model: "gpt-4o-mini"},
        prompt: """
        You are an enthusiastic weather reporter.
        <%= @message %>
        """,
        tools: [
          Jido.Tools.Weather
        ],
        # verbose: true
      ]
    )
  end

  defdelegate chat_response(pid, message), to: Jido.AI.Agent
  defdelegate tool_response(pid, message), to: Jido.AI.Agent
end

# Start the Weather Agent
{:ok, pid} = WeatherAgent.start_link()

This block defines our agent and starts the GenServer to run our Agent. With this now started, we can request a response via the tool_response/2 method. This default implementation uses test data from the Weather API.

# Ask for the weather in Tokyo
WeatherAgent.tool_response(pid, "What is the weather like in Tokyo right now?")

That’s it! With just a few lines of code, we’ve created an AI agent that can answer weather questions.

Core Components

Let’s explore the key components that make our Weather Agent work:

Weather Tool

The Weather Tool provides our agent with the ability to fetch weather data. Here’s a simplified view of its structure:

# This is not executable code, just for demonstration
defmodule Jido.Tools.Weather do
  use Jido.Action,
    name: "weather",
    description: "Get the weather for a given location via the OpenWeatherMap API",
    schema: [
      location: [type: :string, doc: "The location to get the weather for"],
      units: [type: :string, doc: "Units to use (metric/imperial)", default: "metric"],
      hours: [type: :integer, doc: "Number of hours to forecast", default: 24],
      format: [type: :string, doc: "Output format (text/map)", default: "text"],
      test: [type: :boolean, doc: "Whether to use test data instead of real API", default: true]
    ]

  def run(params, _context) do
    # Fetch weather data from OpenWeather API or use test data
    # Format and return the response
  end
end

The Weather Tool:

Accepts parameters like location and units
Can use either real API data or test data
Formats the weather information into readable text

Jido AI Keyring

The Keyring manages access to environment variables like API keys:

# This is not executable code, just for demonstration
defmodule Jido.AI.Keyring do
  # Get a value from the keyring
  def get(key, default \\ nil) do
    # Check session values first
    # Then environment variables
    # Then application config
    # Finally fall back to default
  end

  # Special support for Livebook environment variables
  def get_env_value(key, default \\ nil) do
    # First try normal key (OPENAI_API_KEY)
    # If not found, try Livebook key (LB_OPENAI_API_KEY)
  end
end

The Keyring helps our agent access the OpenWeather API key securely.

Jido AI Agent

The AI Agent is the core of our system:

# This is not executable code, just for demonstration
defmodule Jido.AI.Agent do
  use Jido.Agent,
    name: "jido_ai_agent",
    description: "General purpose AI agent powered by Jido",
    category: "AI Agents",
    tags: ["AI", "Agent"],
    vsn: "0.1.0"

  @default_opts [
    skills: [Jido.AI.Skill],
    agent: __MODULE__
  ]

  @impl true
  def start_link(opts) do
    opts = Keyword.merge(@default_opts, opts)
    Jido.Agent.Server.start_link(opts)
  end

  def tool_response(pid, message) do
    {:ok, signal} = build_signal("jido.ai.tool.response", message)
    call(pid, signal)
  end

  # Other caller methods
end

The AI Agent:

Processes natural language queries
Decides which tools to use based on the query
Formats the response according to its prompt

Jido AI Skill

The AI Skill organizes functionality for the agent:

# This is not executable code, just for demonstration
defmodule Jido.AI.Skill do
  use Jido.Skill,
    name: "jido_ai_skill",
    description: "General purpose AI skill powered by Jido"

  # The router translates the Signal.type to an %Instruction
  def router(_opts \\ []) do
    [
      {"jido.ai.chat.response", %Instruction{action: Jido.AI.Actions.Instructor.ChatResponse}},
      {"jido.ai.tool.response", %Instruction{action: Jido.AI.Actions.Langchain.ToolResponse}}
    ]
  end

  def handle_signal(%Signal{type: "jido.ai.tool.response"} = signal, skill_opts) do
    # Process the signal using the configured tools
    {:ok, signal}
  end
end

The AI Skill:

Manages the agent’s AI capabilities
Handles routing of different signal types
Connects the agent to its tools

Tool Response Action

The Tool Response Action executes tool operations:

# This is not executable code, just for demonstration
defmodule Jido.AI.Actions.Langchain.ToolResponse do
  use Jido.Action,
    name: "generate_tool_response",
    description: "Generate a response using LangChain to coordinate with tools/functions",
    schema: [
      model: [
        type: {:custom, Jido.AI.Model, :validate_model_opts, []},
        doc: "The AI model to use (defaults to Claude 3.5 Haiku)",
        default: {:anthropic, [model: "claude-3-5-haiku-latest"]}
      ],
      prompt: [
        type: {:custom, Jido.AI.Prompt, :validate_prompt_opts, []},
        required: true,
        doc: "The prompt to use for the response"
      ],
      tools: [
        type: {:list, :atom},
        default: [],
        doc: "List of Jido.Action modules to use as tools"
      ],
      temperature: [type: :float, default: 0.7, doc: "Temperature for response randomness"],
      timeout: [type: :integer, default: 30_000, doc: "Timeout in milliseconds"],
      verbose: [type: :boolean, default: false, doc: "Verbose output"]
    ]

  def run(params, _context) do
    # Extract the model, prompt, and tools
    # Process the query using the AI model
    # Execute the appropriate tools
    # Return the formatted response
  end
end

This component:

Takes the user’s query and the available tools
Asks the AI model which tool to use and with what parameters
Executes the tool and returns the result

Pulling It All Together

Here’s how all the components work together when you ask “What’s the weather in Tokyo?”:

Your message goes to the tool_response function in the AI Agent
The agent passes your message to the large language model (GPT-4o-mini)
The model understands you’re asking about weather in Tokyo
The Tool Response Action executes the Weather Tool with “Tokyo” as the location
The Weather Tool fetches data (either test data or from the API via the Keyring)
The model formats the response in the style of an enthusiastic weather reporter
You receive the friendly, informative answer

The beauty of Jido is that this complex flow is hidden behind just a few lines of code in our WeatherAgent module.

Complete Agent Showcase

Let’s ask our agent a few more questions:

# Ask about tomorrow's weather
WeatherAgent.tool_response(pid, "Will I need an umbrella in Paris tomorrow?")

# Ask about multiple locations
WeatherAgent.tool_response(pid, "Compare the weather in New York and San Francisco today.")

# Ask a more complex weather question
WeatherAgent.tool_response(pid, "Is it a good day for hiking in the mountains near Seattle?")

Additional Resources

Website: https://agentjido.xyz
Documentation: https://hexdocs.pm/jido

Weather Agent