Agent node

Purpose

The Agent node executes an AI agent as a workflow step. The agent receives input from previous nodes, performs LLM reasoning with its configured persona and instructions, optionally calls tools or retrieves from knowledge bases, and produces structured output. Agent nodes are the intelligence layer of your workflows. They interpret context, make decisions, analyze data, and perform complex reasoning tasks that would be difficult or impossible with traditional code.

How it works

When execution reaches an Agent node:

Input resolution — Data from previous nodes or the trigger is resolved and mapped to the agent’s input
Knowledge retrieval — If knowledge bases are attached, context is retrieved (auto mode: single-shot injection; agentic mode: search tool available throughout execution)
Memory retrieval — If Mem0 memory is enabled, relevant memories are retrieved and added to context
Prompt construction — The system prompt is built from the agent’s persona, instructions, retrieved KB context, tool hints, and KB hints
DSPy structured execution — The agent runs through DSPy with either TypedPredict (direct) or ChainOfThought (reasoning) to produce validated structured output
Tool loop — If the agent has tools, it enters a tool-calling loop where it can iteratively call MCP tools and KB search (agentic mode), up to max_iterations or max_token_budget
Output validation — Output is validated against the configured output schema
Variable storage — The validated output is stored in the variable store for downstream nodes

Each Agent node is a single agent execution. For multi-agent patterns, chain multiple Agent nodes or use Parallel nodes to run agents simultaneously.

Configuration

Configure an Agent node to execute the right agent with the right context and behavior.

Select an agent

Choose which agent from your project will execute in this node. The agent’s configuration determines:

Model — Which LLM to use (GPT-4, Claude, Gemini, etc.) via LLM Config
Persona — The agent’s name, role, and detailed instructions
Available tools — MCP tools the agent can call during its reasoning loop
Knowledge bases — Vector stores the agent can query for context (auto or agentic mode)
Capabilities — Tool execution, KB search mode, HyDE, memory, iteration limits, and token budgets
Output schema — Structured output validation via DSPy

You can select any agent created in MagOneAI Studio’s agent configuration.

Agent capabilities

Each agent has configurable capabilities that control its behavior:

Capability	Description	Default
`can_execute_tools`	Whether the agent can call MCP tools	`true`
`can_search_knowledge`	Whether the agent can search knowledge bases	`true`
`use_memory`	Enable Mem0 conversational memory	`false`
`max_iterations`	Maximum tool-calling loop iterations	`10`
`max_token_budget`	Max total tokens for tool loop (unlimited if not set)	None
`kb_retrieval_mode`	`"auto"` (single-shot injection) or `"agentic"` (iterative search tool)	`"auto"`
`max_kb_searches`	Max KB search calls per execution in agentic mode	`10`
`hyde_enabled`	Enable HyDE query expansion for KB search	`false`

Structured output with DSPy

Agent nodes use DSPy for structured, validated output generation. You can configure:

Output schema — JSON Schema that defines the expected output fields and types
Module type — TypedPredict (direct generation) or ChainOfThought (step-by-step reasoning before output)

DSPy ensures the agent’s output conforms to your schema, making it reliable for downstream nodes that expect specific data structures.

Input mapping

Map data from the variable store to the agent’s input. The agent receives this data as context for its reasoning. Common input mappings:

Trigger data — {{trigger.input.document_url}}
Previous agent output — {{previous_agent.output.analysis}}
Tool results — {{api_call.output.response}}
Static values — Hardcoded strings or numbers for consistent context

Example input mapping:

{
  "document_text": "{{document_processor.output.extracted_text}}",
  "document_type": "{{trigger.input.type}}",
  "customer_context": "{{crm_lookup.output.customer_profile}}"
}

Output mapping

Define how the agent’s output is stored in the variable store. You can:

Store the entire response under a custom variable name
Extract specific fields from structured output
Transform the output before storing

Example output mapping:

{
  "analysis_result": "{{agent.output}}",
  "risk_score": "{{agent.output.risk_score}}",
  "requires_review": "{{agent.output.requires_human_review}}"
}

Retry settings

Configure how the system handles agent execution failures:

Number of retries — How many times to retry on failure (default: 3)
Backoff strategy — Fixed delay or exponential backoff between retries
Retry on — Which error types trigger retries (rate limits, timeouts, model errors)

Agent executions can fail due to LLM rate limits, timeouts, or temporary service issues. Proper retry configuration ensures resilience.

Timeout

Set a maximum execution time for the agent. If the agent doesn’t complete within this time:

The execution is terminated
The retry policy determines whether to retry
The workflow can handle the timeout with error handling logic

Recommended timeouts:

Simple analysis tasks: 30-60 seconds
Complex reasoning with multiple tool calls: 2-5 minutes
Document processing: 1-3 minutes

Set realistic timeouts based on your agent’s expected behavior. Agents with many tool calls or large knowledge bases may need longer timeouts.

How context flows

Understanding how data flows into and out of Agent nodes is crucial for building effective workflows.

Input flow

Previous activities store their outputs in the variable store
You define input mapping to select which variables the agent receives
The agent receives mapped data as context
The agent processes the context with its persona and instructions

Output flow

The agent completes reasoning and produces output
Output mapping transforms or extracts specific fields
Mapped output is stored in the variable store
Downstream nodes can access the stored data

Context accumulation

As workflows execute, context accumulates in the variable store. Downstream agents can access outputs from all previous nodes:

{
  "trigger": {
    "document_url": "https://...",
    "customer_id": "12345"
  },
  "document_extractor": {
    "text": "...",
    "metadata": {...}
  },
  "compliance_agent": {
    "is_compliant": true,
    "risk_score": 0.3,
    "findings": [...]
  },
  "financial_agent": {
    "amount": 50000,
    "currency": "AED",
    "requires_approval": true
  }
}

Each agent builds on the work of previous agents, creating rich, contextualized reasoning.

Example: Document processing workflow

Let’s build a complete document processing workflow using Agent nodes.

Scenario

Process incoming contracts: extract text, analyze compliance, assess risk, and generate a summary report.

Workflow structure

Document extraction agent

Receives the document URL from the trigger. Uses vision model to extract text and metadata.Input:

{
  "document_url": "{{trigger.input.document_url}}"
}

Output:

{
  "extracted_text": "...",
  "document_type": "contract",
  "metadata": {
    "pages": 12,
    "language": "en"
  }
}

Compliance analysis agent

Analyzes the extracted text for compliance with company policies. Has access to compliance knowledge base.Input:

{
  "document_text": "{{document_extractor.output.extracted_text}}",
  "document_type": "{{document_extractor.output.document_type}}"
}

Output:

{
  "is_compliant": true,
  "risk_score": 0.3,
  "findings": [
    "All required clauses present",
    "Standard payment terms",
    "No unusual liability provisions"
  ],
  "requires_legal_review": false
}

Financial analysis agent

Extracts and analyzes financial terms, amounts, and obligations.Input:

{
  "document_text": "{{document_extractor.output.extracted_text}}"
}

Output:

{
  "contract_value": 250000,
  "currency": "AED",
  "payment_terms": "Net 30",
  "duration_months": 24,
  "auto_renewal": true
}

Summary report agent

Synthesizes all previous analyses into an executive summary.Input:

{
  "compliance_analysis": "{{compliance_agent.output}}",
  "financial_analysis": "{{financial_agent.output}}",
  "document_metadata": "{{document_extractor.output.metadata}}"
}

Output:

{
  "summary": "24-month contract worth AED 250,000...",
  "key_findings": [...],
  "recommendation": "Approved for signature",
  "next_steps": [...]
}

Result

Each agent builds on the previous agent’s work, creating a comprehensive document analysis pipeline. The variable store accumulates context, and the final report agent synthesizes everything into actionable insights.

Agent types

MagOneAI automatically classifies agents based on their configuration:

Agent Type	Description
TOOL	Agent has MCP tools but no knowledge bases. Focuses on tool execution.
HYBRID	Agent has both MCP tools and knowledge bases. Most powerful — can reason, search, and act.
KB-only	Agent has knowledge bases but no tools. Focuses on knowledge retrieval and analysis.
Basic	Agent with no tools or knowledge bases. Pure LLM reasoning with persona and instructions.

Tool-calling loop

When an agent has tools available, it enters an iterative tool-calling loop:

Initial reasoning

The agent receives the prompt with persona, instructions, input, and any KB context. It decides whether to call a tool or generate a final answer.

Tool execution

If the agent decides to call a tool, the tool is executed via the MCP protocol. In agentic RAG mode, the __kb.search tool is also available for iterative knowledge base queries.

Result integration

Tool results are added to the conversation. The agent reasons about the results and decides whether to call another tool or generate a final answer.

Loop termination

The loop ends when:

The agent generates a final answer (no more tool calls)
max_iterations is reached
max_token_budget is exceeded

The tool loop enables agents to perform multi-step reasoning: search a knowledge base, call an external API based on the results, then synthesize everything into a structured answer.

Best practices

Keep agent scope focused

Design each agent to do one thing well. Instead of a single “analyze everything” agent, use multiple focused agents: compliance checker, financial analyzer, risk assessor, etc.Focused agents are easier to test, debug, and reuse across workflows.

Use descriptive variable names

When mapping outputs, use clear, descriptive names that indicate the source and content.Good: compliance_agent.risk_assessment Poor: result1Future you (and your teammates) will thank you.

Validate agent outputs

Use Condition nodes after Agent nodes to validate outputs meet your criteria. Route to error handling or human review if validation fails.This prevents invalid data from propagating through your workflow.

Provide rich context

The more context you provide to agents, the better their reasoning. Map all relevant data from previous nodes, even if it seems redundant.Agents perform best when they have complete information.

Set appropriate timeouts

Balance between allowing enough time for thorough reasoning and preventing stuck executions. Monitor actual execution times and adjust.Most agent executions complete in 30-90 seconds, but complex tasks with many tool calls may need more time.

Use Parallel nodes to run multiple Agent nodes simultaneously when they’re analyzing the same input from different perspectives. This dramatically reduces total workflow execution time.

Next steps

Tool node

Execute tools directly without agent reasoning

Parallel execution

Run multiple agents simultaneously

Condition node

Route based on agent output

Memory system

Understand how context flows between agents

Getting Started

Platform Guide

Agents

Workflow Builder

Tools & Integrations

Models & Providers

Cookbooks

Security & Administration

Purpose

How it works

Configuration

Select an agent

Agent capabilities

Structured output with DSPy

Input mapping

Output mapping

Retry settings

Timeout

How context flows

Input flow

Output flow

Context accumulation

Example: Document processing workflow

Scenario

Workflow structure

Result

Agent types

Tool-calling loop

Best practices

Next steps

Tool node

Parallel execution

Condition node

Memory system

Getting Started

Platform Guide

Agents

Workflow Builder

Tools & Integrations

Models & Providers

Cookbooks

Security & Administration

​Purpose

​How it works

​Configuration

​Select an agent

​Agent capabilities

​Structured output with DSPy

​Input mapping

​Output mapping

​Retry settings

​Timeout

​How context flows

​Input flow

​Output flow

​Context accumulation

​Example: Document processing workflow

​Scenario

​Workflow structure

​Result

​Agent types

​Tool-calling loop

​Best practices

​Next steps

Tool node

Parallel execution

Condition node

Memory system

Purpose

How it works

Configuration

Select an agent

Agent capabilities

Structured output with DSPy

Input mapping

Output mapping

Retry settings

Timeout

How context flows

Input flow

Output flow

Context accumulation

Example: Document processing workflow

Scenario

Workflow structure

Result

Agent types

Tool-calling loop

Best practices

Next steps