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:

1. Input resolution — Data from previous nodes or the trigger is resolved and mapped to the agent's input
2. Knowledge retrieval — If knowledge bases are attached, context is retrieved (auto mode: single-shot injection; agentic mode: search tool available throughout execution)
3. Memory retrieval — If Mem0 memory is enabled, relevant memories are retrieved and added to context
4. Prompt construction — The system prompt is built from the agent's persona, instructions, retrieved KB context, tool hints, and KB hints
5. DSPy structured execution — The agent runs through DSPy with either TypedPredict (direct) or ChainOfThought (reasoning) to produce validated structured output
6. 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
7. Output validation — Output is validated against the configured output schema
8. Variable storage — The validated output is stored in the variable store for downstream nodes

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:

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.

System tools

Beyond MCP tools, an agent can be granted a selectable set of built-in system tools via enabled_system_tools — a list of tool names. An explicit list (including an empty list, meaning "none") is authoritative; when it is left unset, the agent falls back to the legacy all-or-nothing switch.

The individually selectable system tools are:

The file tools (read, write, edit, glob, grep) operate on file artifacts in the project, so an agent can discover, search, read, and produce files as part of its reasoning. Because grep and read work over pre-extracted text, an agent can locate specific content in a large PDF or spreadsheet without loading the whole document into its prompt.

Ask a human mid-run

When allow_human_input is enabled, the agent gets a request_human_input tool it can call mid-loop to pause and ask a specific person for clarification or missing information. The loop suspends until the assigned person responds, then the answer is fed back into the conversation (fenced and redacted as untrusted input) and the agent continues.

This is clarification-only — it does not branch on approve/reject. For approval gating with routing, use a standalone Human task node.

Two settings are required when allow_human_input is on:

• human_task_assignee_id — the user who receives the request. The agent cannot choose an assignee; it is fixed per agent.
• human_task_timeout_minutes — how long to wait before the loop fails. There is no indefinite wait: the value is bounded by the workflow's own lifespan, so a wait longer than the parent workflow can outlive is rejected.

Blackboard recall

When can_query_blackboard is enabled, the agent gets a __query_blackboard tool that recalls the full result of something it already did earlier in the same run (a prior search, page fetch, or query) instead of repeating the tool call. It searches only the current execution's artifacts, never another run's. See Execution artifacts and the Debugger for what is stored, how the action ledger stops repeated work, and how to inspect a run.

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 — {{input.document_url}}
• Previous agent output — {{previous_agent.analysis}}
• Tool results — {{api_call.response}}
• Static values — Hardcoded strings or numbers for consistent context

Example input mapping:

{
  "document_text": "{{document_processor.extracted_text}}",
  "document_type": "{{input.type}}",
  "customer_context": "{{crm_lookup.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}}",
  "risk_score": "{{agent.risk_score}}",
  "requires_review": "{{agent.requires_human_review}}"
}

Automatic retries

MagOneAI runs agent activities on Temporal, which retries a failed activity automatically. The default is up to 3 attempts, a platform-level setting rather than a per-node option. Retries cover transient failures such as LLM rate limits, timeouts, and temporary service errors, so an agent execution recovers from a hiccup without failing the whole workflow. A call that exceeds the request timeout fails and is subject to the same retry behavior.

Request timeout

In the agent node's Advanced settings you can set a per-LLM-call timeout — the maximum time a single model request may take before it fails. This bounds an individual call within the agent's reasoning loop, not the agent's total run time.

• Field — request_timeout_seconds
• Range — 1 to 600 seconds
• Default — uses the LLM config's defaults (typically 120s for text calls and 300s for vision calls) when left blank

If a model request exceeds the timeout, it fails and the agent's automatic retries determine whether the call is retried. Setting a per-call timeout is useful when you want to fail fast on a stuck provider rather than wait for the provider's much longer default.

Model selection and overrides

By default an Agent node uses the agent's own model (its LLM Config), and the workflow's default LLM config fills in when the node specifies none. You can override both the model and its sampling parameters at the node level.

Pin a model at this node:

• llm_config_id — the LLM config this node should use, overriding the workflow default.
• force_llm_config — when true and llm_config_id is set, this node's model is pinned so that a per-message chat model pick cannot override it. Use it to keep a node (for example a confidentiality gate, or a per-role agent) on a specific self-hosted model regardless of the user's selection.

Override model parameters at this node:

• temperature and top_p — sampling controls for this activity.
• max_tokens — cap on output tokens for this activity.
• thinking_enabled / thinking_effort — turn on extended thinking and set its depth (low, medium, or high). This is translated to provider-specific reasoning budgets (for example a reasoning effort for OpenAI o-series, a thinking block for Anthropic, thinkingConfig for Gemini).
• prompt_cache_ttl — prompt-cache lifetime for this node's LLM calls: unset means the default (a 5-minute cache, on), 1h extends it to one hour (higher one-time write cost), and off disables explicit caching. It applies to API providers (Anthropic honors the duration); self-hosted models cache automatically.

How context flows

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

Input flow

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

Output flow

1. The agent completes reasoning and produces output
2. Output mapping transforms or extracts specific fields
3. Mapped output is stored in the variable store
4. 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_url": "{{input.document_url}}"
}

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

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

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

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

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

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

{
  "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:

Tool-calling loop

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

Best practices

Next steps