Agent Tool

Early Alpha Version

AI Agents are in early alpha. Node interfaces, behaviors, and APIs are subject to change.

The Agent Tool node defines a callable tool that an AI agent can use. When the agent decides to call the tool, it fires a signal with the parameters the agent passed — letting you handle the request with any XGENIA logic.

How Tools Work

1. You define a tool with a Name, Description, and Parameters Schema
2. The agent sees the tool in its available tools list
3. When the agent decides to use the tool, the Tool node's Execute signal fires
4. Your logic reads the Input Data, processes it, and sets the Result
5. You fire the Done signal to return the result to the agent

Inputs

Input	Type	Default	Description
Tool Name	String	—	Unique name for the tool (e.g. search_products, get_weather)
Description	String (multiline)	—	What the tool does — the agent reads this to decide when to use it
Parameters Schema	JSON	See below	JSON Schema defining the tool's expected parameters
Result	Any	—	The result to return to the agent (set this before firing Done)
Done	Signal	—	Fire this after processing to return the result to the agent

Outputs

Output	Type	Description
Tool Definition	Object	The tool definition object (wire to Agent's Tools input, or use auto-discovery)
Execute	Signal	Fires when the agent calls this tool
Input Data	Object	The parameters the agent passed when calling the tool
Tool Info	String	Summary of the tool's name and description
Error	String	Error message if the tool definition is invalid

Parameters Schema

The Parameters Schema uses JSON Schema format. Here's the default example:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query"
    }
  },
  "required": ["query"]
}

More Examples

No parameters:

{
  "type": "object",
  "properties": {}
}

Multiple parameters:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature unit"
    }
  },
  "required": ["city"]
}

Auto-Discovery

When placed in the same component as an AI Agent with Auto-Discover Tools enabled, the Tool node is automatically registered — no manual wiring needed.

If you prefer explicit wiring, connect the Tool Definition output → Agent's Tools input.

Execution Flow

Agent calls tool → Execute signal fires
                 → Your logic reads Input Data
                 → Your logic sets Result
                 → Done signal fires
                 → Result returned to Agent

Timeout: If the Done signal is not fired within 30 seconds, the tool returns a timeout error to the agent.

Usage Tips

• Write clear descriptions — the agent uses the description to decide when to call the tool. "Search the product catalog by name or category" is better than "Search."
• Keep schemas simple — fewer parameters means less chance of the agent passing incorrect values.
• Always fire Done — if you forget to fire the Done signal, the tool call will time out after 30 seconds.
• You can use any XGENIA logic to handle the Execute signal: query a database, call a REST API, run a calculation, etc.