
# SOE Guide: Chapter 5 - Agent Nodes

## Introduction to Agent Nodes

The **Agent Node** is a convenience wrapper that encapsulates the **ReAct pattern** (Reasoning + Acting) into a single, configurable component.

In the previous chapter, you learned how to build custom agent loops using Tool, LLM, and Router nodes. The Agent Node does the same thing—but packaged for common use cases where you want a "hands-off" tool-using agent.

### Why Use Agent Nodes?

| Building Custom (Ch. 4) | Using Agent Node |
|------------------------|------------------|
| Full control over each step | Quick to configure |
| Custom reasoning patterns | Standard ReAct loop |
| Explicit debugging points | Batteries included |
| Any architecture you want | Opinionated but effective |

**Use Agent Node when**: You need a straightforward tool-using agent and don't need custom reasoning patterns.

**Use custom workflows when**: You need chain-of-thought, metacognition, voting, or other advanced patterns.

**Note**: Agent nodes can also be used for other patterns (routing, summarization, etc.), but they involve more LLM calls than specialized nodes. Use the right node type for your use case.

### The Agent Loop

The Agent Node runs this loop internally:

1.  **Router Stage**: The agent decides what to do (Call a Tool or Finish)
2.  **Parameter Stage**: If calling a tool, it generates the arguments
3.  **Execution Stage**: The tool is executed
4.  **Loop**: The results are fed back into the history, and the agent decides again

This is exactly what you built manually in Chapter 4's "Custom ReAct Loop" pattern—but as a single node.

### Multiple Tool Calls

The agent can call multiple tools in sequence during a single node execution:

1. Agent decides to call Tool A → executes → sees result
2. Agent decides to call Tool B → executes → sees result
3. Agent decides to call Tool A again → executes → sees result
4. Agent decides to Finish

**Exhaustive tool calling**: The agent will keep calling tools until it decides to finish. There's no hard limit on tool calls—the agent uses its judgment. To prevent runaway loops, use operational limits (see [Operational Features](advanced_patterns/operational.md)).

## Configuring Tools

Agents have access to the tools you provide in their `tools` list.

> [!IMPORTANT]
> **Tool Restriction**: Agent nodes can ONLY call tools explicitly listed in their `tools` configuration, even if a tool is a SOE built-in. If you want an agent to be able to use a built-in tool like `soe_inject_node`, you must include it in the `tools` list for that node.

### Example: Tool Restriction

```yaml
MyAgent:
  node_type: agent
  tools:
    - calculate_total     # User tool
    - soe_inject_node     # Built-in tool (MUST be listed here)
```

### The Workflow

```yaml
example_workflow:
  CalculatorAgent:
    node_type: agent
    event_triggers: [START]
    prompt: "You are a calculator. Solve the user's math problem: &#123;&#123; context.problem &#125;&#125;"
    tools: [calculator]
    output_field: result
    event_emissions:
      - signal_name: CALCULATION_DONE
```

### How It Works

1.  **`tools`**: We give the agent a list of tools (e.g., `[calculator]`).
2.  **The Loop**:
    *   The agent sees the prompt: "Solve... {{ context.problem }}"
    *   It decides to call `calculator(5, 3, 'add')`.
    *   The tool returns `8`.
    *   The agent sees the result and decides to **Finish**.
3.  **Output**: The final answer is stored in `context.result`.

## Advanced Configuration: Multiple Tools

Agents can handle complex tasks with multiple tools.

### The Workflow

```yaml
example_workflow:
  ResearchAgent:
    node_type: agent
    event_triggers: [START]
    prompt: "Research the topic: &#123;&#123; context.topic &#125;&#125;"
    tools: [search_web, summarize_text]
    output_field: report
    event_emissions:
      - signal_name: REPORT_READY
```

### Robustness Features

-   **Tool Selection**: The agent intelligently chooses between `search_web` and `summarize_text` based on the goal.
-   **Error Recovery**: If a tool fails (throws an exception), the agent sees the error and can try again or try a different strategy.

## Agent Signal Selection

Like LLM nodes, Agent nodes can select which signal to emit based on their analysis:

### The Workflow

```yaml
example_workflow:
  AnalysisAgent:
    node_type: agent
    event_triggers: [START]
    prompt: "Analyze the data and determine if it needs human review: &#123;&#123; context.data &#125;&#125;"
    tools: [analyze_data]
    output_field: analysis
    event_emissions:
      - signal_name: AUTO_APPROVE
        condition: "The analysis shows the data is clearly valid"
      - signal_name: NEEDS_REVIEW
        condition: "The analysis shows the data requires human review"
      - signal_name: REJECT
        condition: "The analysis shows the data is clearly invalid"
```

The agent completes its task, then the signal selection works the same as LLM nodes:
- **Plain text conditions**: LLM chooses semantically
- **Jinja conditions**: Evaluated programmatically

## When to Choose Agent vs Custom Workflow

### Use Agent Node For:

- **Quick prototyping**: Get a tool-using agent running fast
- **Standard tasks**: Research, calculation, data gathering
- **Simple tool orchestration**: When tool selection is the main complexity

### Build Custom Workflows For:

- **Chain-of-thought reasoning**: Explicit step-by-step thinking
- **Metacognition**: Self-review and refinement loops
- **Parallel/voting patterns**: Multiple analyses combined
- **Hybrid logic**: Mixing deterministic gates with AI
- **Audit requirements**: When you need to log/inspect each decision
- **Custom termination conditions**: Beyond simple "finish" detection

Remember: The Agent Node is **syntactic sugar** for a common pattern. Everything it does, you can build yourself with the three core node types.

## Next Steps

Now that you understand both custom workflows and the Agent Node, let's explore [Schemas](guide_06_schema.md) for structured LLM output →
