Agent

Agent

The Agent is the most powerful and flexible AI orchestration component of the NappAI platform. Its modular design allows for the construction of custom agents capable of executing complex logic, interacting with external tools, and operating under strict control and security policies.

Unlike standard components that follow a fixed execution path, the Agent acts as a reasoning system that analyzes requests, designs an action plan, and utilizes the resources at its disposal to reach a goal.

Main Use Cases

Use the Agent to develop solutions that require:

• Multi-Tool Orchestration: When an agent needs to access various data sources or APIs and decide which one to use based on the context.
• Cost and Resource Control: To implement precise limits on the use of language models (LLMs) and external tools.
• Supervision and Security: In workflows where certain critical actions (e.g., modifying a database) require human approval or where sensitive information must be protected.
• High Reliability: To build resilient systems that can handle network failures or external service errors through retry policies and fallback models.

---

Fundamental Configuration

These parameters form the basis of any Agent's behavior.

Parameter	Technical Description	Purpose in the Flow
Input	The initial message or payload that triggers the agent’s execution.	Represents the user’s request or the input data that the agent must process.
System Prompt	The persistent instruction that defines the role, behavioral rules, and main goal of the agent. This prompt is sent to the Language Model (LLM) in each reasoning cycle.	Acts as the agent’s “constitution,” guiding all its decisions and ensuring its behavior is consistent and aligned with its purpose.
Model (llm)	The connection to the Language Model (LLM) component that the agent will use for its reasoning cycle.	It is the main “cognitive engine.” The agent delegates the task of understanding the request, planning the steps, and deciding which tools to use to this model.
Tools	A list of external components or functionalities that the agent is allowed to invoke.	They constitute the agent’s “team of specialists.” Each tool represents a specific capability (e.g., searching the web, querying an API, accessing a database).
Use short term memory	Activates the conversational memory system based on a checkpointer.	Enables the agent to remember past interactions within the same session, allowing for the construction of coherent and contextual dialogues.

---

Advanced Features (Plug in advanced features)

By activating this switch, a set of “middlewares” (intermediary software layers) is deployed to intercept and modify the agent’s behavior. These capabilities are organized by functional categories.

Agent Capabilities: Improving Reasoning

• Add Planning (TodoList): Provides the agent with an internal task management tool. Before executing a complex plan, the agent can create a list of steps (To-Do list). This not only structures its own reasoning but also offers visibility into its progress. It is ideal for tasks requiring multiple sequential actions.

Supervision and Security: Control and Human Approval

• Human-in-the-Loop (HITL): Implements a breakpoint for human supervision. You can configure which specific tools require human approval before execution. For each tool, you can define the allowed decisions (approve, edit, reject). This functionality is critical for sensitive operations such as mass communication, modifying master data, or executing financial transactions.

• Enable PII Detection: Activates a Personally Identifiable Information (PII) detection and treatment module. This middleware inspects input and output data to identify sensitive information (emails, credit cards, IPs, etc.). You can configure a treatment strategy for each type of detected data:

  • block: Stops execution.
  • redact: Replaces information with a generic marker.
  • mask: Partially masks the data.
  • hash: Replaces data with a deterministic hash.

Resource and Cost Control: Consumption Management

• Tool call limit: Sets a limit on the number of times a tool can be invoked. This limit can be global (for all tools) or specific to a particular tool. It helps prevent unwanted loops and control costs associated with third-party APIs.

• Model call limit: Limits the total number of LLM calls the agent can perform during a single execution. It is an essential security measure to prevent uncontrolled token consumption and ensure costs stay within expectations.

Reliability: Building a Fail-Safe Agent

• Enable Model Fallback: Configures a chain of fallback models. If the main model fails, the agent will automatically attempt to execute the same task with secondary models in the priority order you define.

• Model retry / Tool retry: Defines an automatic retry policy for failed model or tool calls. You can configure the maximum number of attempts, initial wait time, and exponential backoff factor to manage transient network failures or service overloads.

Tool Optimization: Fine-Tuning Tool Usage

• Optimize tool selection: When an agent has a large number of tools, this feature uses a secondary LLM to pre-select the most relevant subset of tools for the current request. This reduces the size of the context sent to the main LLM, which can improve decision accuracy and reduce token costs.

• LLM tool emulator: Allows for simulating a tool’s response using an LLM. This capability is designed for development and debugging. It allows testing an agent’s reasoning logic without needing to execute the real tools, speeding up development cycles and avoiding costs in test environments.

Context and Memory: Advanced Context Management

• Context editing: Implements an automatic memory pruning strategy. It allows configuring rules to clean the conversation history when it exceeds a token threshold. For example, you can define that the last 3 tool results are always kept and the rest are deleted, optimizing the context sent to the LLM.

• Custom State: Allows extending the agent’s internal state with custom memory fields. Through a JSON schema, you can define additional variables that the agent can read and write during its execution (e.g., task_id, customer_name). This enables the construction of highly stateful and personalized workflows.

You can see a video showing the Agent with human intervention in the flow here.