AI Agents & Memory

MachinaOs provides two types of AI agents for different use cases, plus a memory node for conversation context.

Agent Types

Agent	Purpose	Special Features
AI Agent	Complex reasoning with tool calling	LangGraph execution, iterative reasoning
Chat Agent	Conversational AI with skills	Skill-driven behavior, multi-turn chat
Simple Memory	Conversation history storage	Markdown format, long-term vector storage

Specialized Agents

Pre-configured agents for specific domains. Same AI configuration as base agents with domain-focused defaults.

Agent	Description	Color
Android Control Agent	Android device control	Green
Coding Agent	Code execution	Cyan
Web Control Agent	Web automation	Red
Task Management Agent	Task automation	Purple
Social Media Agent	Social messaging	Green

AI Agent Node

The AI Agent uses LangGraph for structured execution with tool calling and iterative reasoning.

Input Handles

Handle	Position	Purpose
Main Input	Left	User prompt/data from upstream nodes
Memory	Bottom-left (diamond)	Connect Simple Memory
Tools	Bottom-right (diamond)	Connect Tool nodes

Parameters

provider

select

required

AI provider: openai, anthropic, gemini, openrouter, groq, cerebras

model

select

required

Model to use (options based on provider)

systemPrompt

string

Instructions that define the agent’s behavior and personality

prompt

string

required

The user message. Supports template variables like {{nodeName.field}}

maxIterations

number

default:"5"

Maximum reasoning iterations for complex tasks

Output

{
  "response": "The agent's final response",
  "thinking": "Reasoning process (if thinking enabled)",
  "iterations": 2,
  "tool_calls": [
    {"tool": "calculator", "input": {"operation": "add", "a": 5, "b": 3}, "output": 8}
  ]
}

Tool Calling

Connect Tool nodes to the input-tools handle (bottom-right diamond) to give the agent capabilities:

[Calculator Tool] --+
                    +--> [AI Agent] --> [Output]
[Web Search Tool] --+

The agent will automatically use tools when needed based on the user’s request.

Chat Agent Node

The Chat Agent is designed for conversational interactions with skill-based behavior extension.

Input Handles

Handle	Position	Purpose
Main Input	Left	User message (e.g., from Chat Trigger)
Memory	Bottom-left (diamond)	Connect Simple Memory
Skills	Bottom-right (diamond)	Connect Skill nodes
Tools	Bottom (diamond)	Connect Tool nodes

Parameters

provider

select

required

AI provider: openai, anthropic, gemini, openrouter, groq, cerebras

model

select

required

Model to use (options based on provider)

systemPrompt

string

Base system instructions (extended by connected skills)

prompt

string

User message. If empty, reads from connected input node’s message, text, or content field.

Skill Support

Connect Skill nodes to the input-skill handle to extend the Chat Agent’s capabilities:

[WhatsApp Skill] --+
                   +--> [Chat Agent] --> [Response]
[Maps Skill] ------+

Skills provide domain-specific instructions and allowed tools to the Chat Agent.

Input Methods

Template Variable (Explicit):
```
Prompt: {{chatTrigger.message}}
```
Auto-Fallback (Implicit): Leave Prompt empty - the agent reads from the connected input node automatically.

Output

{
  "response": "Chat Agent's response",
  "thinking": "Reasoning (if enabled)",
  "model": "claude-3-5-sonnet",
  "provider": "anthropic"
}

Simple Memory Node

Stores conversation history in markdown format for AI agents.

Connection

Simple Memory connects to the memory handle (diamond shape on bottom-left):

[Simple Memory] ---(diamond)---> [AI Agent or Chat Agent]

Connect to the diamond handle, not the main input. The main input is for data flow.

Parameters

sessionId

string

default:"default"

Unique identifier for the conversation session. Use dynamic values for multi-user scenarios.

windowSize

number

default:"10"

Number of message pairs to keep in short-term memory

memoryContent

string

Editable conversation history in markdown format. View and edit directly in the parameter panel.

longTermEnabled

boolean

default:"false"

Archive old messages to vector DB for semantic retrieval

retrievalCount

number

default:"3"

Number of relevant memories to retrieve from long-term storage (shown when longTermEnabled is true)

Memory Format

Conversation history is stored in markdown:

# Conversation History

### **Human** (2025-01-30 14:23:45)
What is the weather like today?

### **Assistant** (2025-01-30 14:23:48)
I don't have access to real-time weather data...

Memory Flow

Agent reads memoryContent markdown from connected Simple Memory node
Parses markdown to LangChain message format
(If enabled) Retrieves relevant context from vector store
Executes with conversation history
Appends new messages to markdown
Trims to keep last N pairs (windowSize)
Archives removed messages to vector store (if longTermEnabled)
Saves updated markdown back to node parameters

Dynamic Session IDs

For multi-user scenarios, use template variables:

Session ID: {{webhookTrigger.body.user_id}}

This creates separate memory for each user.

Building Agent Workflows

Basic AI Agent with Tools

[Webhook Trigger] --> [AI Agent] --> [Webhook Response]
                          ^
                          |
                   [Simple Memory]

                   [Calculator Tool]
                          |
                          v
                     [AI Agent]

Chat Agent with Skills

[Chat Trigger] --> [Chat Agent] --> [Console]
                        ^
                        |
                 [Simple Memory]

                 [WhatsApp Skill]
                        |
                        v
                   [Chat Agent]

Step-by-Step Setup

Add AI Agent or Chat Agent from AI Agents category
Add Simple Memory and connect to memory handle (diamond)
Add Tools/Skills and connect to respective handles
Add Trigger (Webhook, Chat, WhatsApp) connected to main input
Add Response node connected to agent output

AI Agent vs Chat Agent

Feature	AI Agent	Chat Agent
Primary Use	Complex reasoning tasks	Conversational interactions
Tool Calling	Yes (LangGraph)	Yes (LangGraph)
Memory Support	Yes	Yes
Skill Support	Yes	Yes
Bottom Handles	Skill, Tools	Skill, Tools
Left Handles	Input, Memory	Input, Memory
Best For	Task automation, reasoning	Chat interfaces, multi-turn dialog

Async Agent Delegation

Agents can delegate tasks to other agents connected via the input-tools handle. The parent agent continues immediately while the child works in the background.

How It Works

Connect a specialized agent to a parent agent’s input-tools handle
Parent agent calls delegate_to_<agent_type>(task="...", context="...")
Child agent spawns as background task
Parent receives {"status": "delegated", "task_id": "..."} immediately
Child executes independently with its own tools

Example

[AI Agent] <--tools-- [Android Control Agent] <--tools-- [Battery Monitor]
                                              <--tools-- [WiFi Automation]

When the AI Agent needs Android control:

Calls delegate_to_android_agent(task="Check battery and enable WiFi if low")
Android Agent spawns in background with its own connected tools
AI Agent continues with other work

Multi-Turn Conversation Example

First Request

curl -X POST http://localhost:3010/webhook/chat \
  -d '{"user_id": "user123", "message": "My name is Alex"}'

Response: “Nice to meet you, Alex! How can I help you today?”

Second Request

curl -X POST http://localhost:3010/webhook/chat \
  -d '{"user_id": "user123", "message": "What is my name?"}'

Response: “Your name is Alex, as you told me earlier.”

Tips

Use descriptive system prompts to define agent behavior clearly.

Set Max Iterations based on task complexity. Simple Q&A: 1-2, Complex reasoning: 3-5.

Use unique Session IDs per user/conversation for proper isolation.

Connect Skills to Chat Agent for domain-specific behavior (WhatsApp, Maps, HTTP, etc.).

Long conversations with large window sizes can exceed model context limits. Use appropriate windowSize for your use case.

Troubleshooting

Agent doesn't remember previous messages

Verify Simple Memory is connected to diamond handle (not main input)
Check Session ID is consistent across requests
Ensure workflow is deployed (not just saved)

Agent doesn't use connected tools

Verify Tool nodes are connected to the input-tools diamond handle
Check tool node has proper schema/description
Ensure the prompt requires tool usage

Skills not affecting Chat Agent behavior

Verify Skill nodes are connected to input-skill handle
Check skill SKILL.md content is valid
Ensure skill’s allowed-tools match connected tool nodes

Memory grows too large

Reduce windowSize setting (10-20 messages recommended)
Enable long-term memory to archive old messages
Consider clearing sessions periodically

AI Models

6 AI providers with thinking modes

AI Skills

10 skill nodes for Chat Agent

AI Tools

Tool nodes for AI agents

AI Tutorial

Step-by-step agent tutorial

Getting Started

Tutorials

Node Catalog

Deployment

FAQ

​AI Agents & Memory

​Agent Types

​Specialized Agents

​AI Agent Node

​Input Handles

​Parameters

​Output

​Tool Calling

​Chat Agent Node

​Input Handles

​Parameters

​Skill Support

​Input Methods

​Output

​Simple Memory Node

​Connection

​Parameters

​Memory Format

​Memory Flow

​Dynamic Session IDs

​Building Agent Workflows

​Basic AI Agent with Tools

​Chat Agent with Skills

​Step-by-Step Setup

​AI Agent vs Chat Agent

​Async Agent Delegation

​How It Works

​Example

​Multi-Turn Conversation Example

​First Request

​Second Request

​Tips

​Troubleshooting

​Related

AI Models

AI Skills

AI Tools

AI Tutorial

AI Agents & Memory

Agent Types

Specialized Agents

AI Agent Node

Input Handles

Parameters

Output

Tool Calling

Chat Agent Node

Input Handles

Parameters

Skill Support

Input Methods

Output

Simple Memory Node

Connection

Parameters

Memory Format

Memory Flow

Dynamic Session IDs

Building Agent Workflows

Basic AI Agent with Tools

Chat Agent with Skills

Step-by-Step Setup

AI Agent vs Chat Agent

Async Agent Delegation

How It Works

Example

Multi-Turn Conversation Example

First Request

Second Request

Tips

Troubleshooting

Related