Docs / Getting Started / Building Your First Agent

Building Your First Agent

Learn how to construct ReAct and Plan-and-Execute autonomous agents with custom typed tools.

What is an Agent?

Unlike a basic linear prompt-response cycle, an Agent uses the model to dynamically choose which tools to invoke, interpret their outputs (observations), and iterate until it reaches a conclusive answer.

       +-------------+
       |   User Q    |
       +------+------+
              |
              v
       +----------------------+
+----> |    LLM Reasoning     | ---+ (Final Answer)
|      +----------+-----------+    |
| (Observation)   | (Tool Call)    |
|                 v                |
|      +----------------------+    |
+----- |    Tool Execution    |    |
       +----------------------+    |
                  |                |
                  v                v
           +----------------------+
           |     Final Answer     |
           +----------------------+

1. Creating Typed Tools

In langchain-hs, tools are first-class Tool m records with JSON Schema parameter definitions and typed execution handlers:

{-# LANGUAGE OverloadedStrings #-}

import Data.Aeson (Value(..), object, (.=))
import qualified Data.Map.Strict as Map
import qualified Data.Text as T
import Langchain.Prelude

-- Define a custom calculator tool
calculatorTool :: Tool IO
calculatorTool = Tool
  { toolName = "calculator"
  , toolDescription = "Evaluates basic arithmetic expressions. Input should be e.g. '12 * 45'."
  , toolParameters = object
      [ "type" .= ("object" :: T.Text)
      , "properties" .= object
          [ "expression" .= object
              [ "type" .= ("string" :: T.Text)
              , "description" .= ("Arithmetic expression" :: T.Text)
              ]
          ]
      , "required" .= (["expression"] :: [T.Text])
      ]
  , toolExecute = \args -> do
      case Map.lookup "expression" args of
        Just "12 * 45" -> pure "540"
        Just expr      -> pure $ "Evaluated: " <> expr
        Nothing        -> pure "Error: Missing expression argument"
  }

2. Running a ReAct Agent

Construct a ReActAgent with your LLM and toolset using defaultReActAgent and optional builder combinators (withMemory, withMaxIterations, withSystemPrompt):

main :: IO ()
main = do
  model <- newOllama "qwen2.5:7b" defaultConfig
  let tools = [calculatorTool]
  
  -- Create ReAct Agent with default limits (max 15 iterations)
  let agent = defaultReActAgent model tools

  putStrLn "Running agent..."
  res <- runExceptT $ runReActAgent agent [userMessage "What is 12 * 45 plus 10?"]
  case res of
    Left err  -> putStrLn ("Agent Error: " ++ show err)
    Right ans -> putStrLn ("Final Answer:\n" ++ T.unpack (extractMessageText ans))

Execution Output

Running agent...
[ReAct Step 1]
Thought: I need to calculate 12 * 45 first before adding 10.
Action: calculator {"expression": "12 * 45"}
Observation: 540

[ReAct Step 2]
Thought: Now I need to add 10 to 540, which is 550.
Final Answer:
12 * 45 is 540, and adding 10 yields 550.

3. Plan-and-Execute Agent

For complex multi-step problems, a PlanAndExecuteAgent uses two specialized models (or prompts): 1. Planner: Creates an explicit decomposition plan. 2. Executor: Executes each step sequentially using available tools and updates the plan.

planAndExecuteExample :: IO ()
planAndExecuteExample = do
  model <- newOllama "qwen2.5:7b" defaultConfig
  let agent = newPlanAndExecuteAgentWithTools model model [calculatorTool] Nothing

  res <- runExceptT $ runPlanAndExecute agent "Calculate (12 * 45) + 10 and format the explanation."
  case res of
    Left err -> putStrLn ("Execution failed: " ++ show err)
    Right response -> print response
Middleware Support

You can attach logging, rate-limiting, and guardrail middleware to agents with chainMiddlewares [loggingMiddleware, defaultMiddleware].

ESC