Skip to content
Nappai Documentation

The AI Data Structure

In NappAI, especially when working with Agents, the “data structure” is often a dynamic JSON object that represents the state of the conversation.

The Agent State

Think of the Agent as a brain that maintains a working “memory.” This memory is an object that contains key information:

  • The user’s input.
  • The conversation history.
  • The results of the tools it has used.
  • Its “plan” or next steps.

Data Flow: Agent → Tool → Agent

The most common data flow in an AI system is as follows:

  1. The Agent receives an input: For example, an object {"input": "Search for Juan's last email"}.
  2. The Agent decides to use a tool: It analyzes the input and determines that it should use the Get Emails tool.
  3. The Agent prepares the data for the tool: It creates a new object with the parameters the tool needs, for example {"from": "Juan", "limit": 1}.
  4. The tool returns a result: The Get Emails tool executes and returns a JSON object with the email data, for example {"subject": "Weekly Report", "body": "..."}.
  5. The Agent synthesizes the response: The Agent receives this result, processes it, and generates a final response in natural language.

Understanding this cycle is key to debugging flows and designing agents that can handle complex tasks.

Working with AI Data

Learn how to handle the most common data types in AI flows, from text and files to embeddings.

An AI Agent is only as good as the data it can understand. In NappAI, you can work with a variety of data types, each with a specific purpose.

Text (String)

It is the most fundamental data type. It is the basis for user inputs, LLM responses, and most interactions with APIs.

Files (Binary and their Transport)

An Agent does not handle files directly but delegates this task to specialized Tools, such as a Google Drive Loader.

  • The Conceptual Process:
    1. The Agent receives an order like “summarize the document ‘annual-report.pdf’”.
    2. The Agent calls the Google Drive Loader tool with the file name.
    3. The tool searches for, downloads, and converts the file to plain text.
    4. The tool returns the text to the Agent for processing.

The Handling of Formats: Base64 and Binary

Here is where an important technical step occurs:

  • Download in Base64: When a component like Google Drive File Manager downloads a file, it converts it to Base64 format. Base64 is a way to encode binary data into plain text, which facilitates its transmission through APIs and within the NappAI flow.
  • Processing in Binary: The Base64 text is sent to the next component in the flow (for example, a Parse Data or a Loader). This receiving component is designed to automatically decode the Base64 and process the content as binary data to extract the relevant text or information.

In summary, although files are transmitted as Base64 between components, file processing components are built to understand and work with the original binary content. As a user, you generally do not need to worry about this conversion, but it is useful to know for debugging issues or building custom flows.

Lists (Arrays) and Iterations

It is very common for a tool or an API not to return a single piece of data, but a list (or array) of them. For example, a file search can return 10 documents, or a database query can return 50 customer records. In NappAI, you have two main methods to process each element of a list:

  • Batch Mode Processing
  • Iterations with Loops (Loop Component)

Structured Data (JSON)

JSON (JavaScript Object Notation) is the universal language for data exchange between APIs, tools, and components in NappAI. While plain text is simple, JSON allows sending rich and nested information.

  • What is it?: It is a text format that organizes data into key: value pairs, allowing complex structures. For example, instead of just “Madrid,” an API might return: {"city": "Madrid", "country": "Spain", "temperature": 25}.
  • How is it used?: When an Agent uses a tool, it will almost always return its result in JSON format. To access a specific piece of data, you need to “navigate” its structure. For example, to get the city from the previous JSON, you would access the city key.
  • Key Tool in NappAI: The Parse Data component is your main ally for working with JSON. It allows you to extract specific values from a complex structure (e.g., user.address.city), transform them, and pass them to other components in the format you need.

Embeddings (Vectors)

This is an advanced but crucial concept in AI.

  • What are they?: An “embedding” is a numerical representation (a vector) of the semantic meaning of a text. Texts with similar meanings will have close numerical vectors.
  • What are they used for?: They are the basis of similarity search. In a RAG (Retrieval-Augmented Generation) flow, you convert your documents into embeddings and store them in a Vector Database. When a user asks a question, you convert the question into an embedding and search the database for the text fragments with the closest vectors, thus finding the most relevant information to answer.

Intelligent Branching (Routing)

As detailed in the Flow Logic guide, an Agent can make dynamic decisions. Instead of an “IF” based on a simple rule, the Agent can route the flow based on the user’s intent.

  • Practical Example: A customer service agent receives a message. If the LLM detects a feeling of “frustration” or “anger,” the Agent can decide to invoke the “Escalate to a Human” tool. If it detects a “technical question,” it will invoke the “Search Knowledge Base” tool.

This routing pattern is implemented in NappAI by combining a classifying Agent with the Switch component, which directs the flow to the correct path according to the word generated by the Agent.

Cognitive Merging (Synthesis)

This is one of the superpowers of Agents. An Agent can consult multiple tools and, instead of simply merging the data, it synthesizes it into a unified response.

  • Practical Example:
    1. User: “What will the weather be like tomorrow in Barcelona and is my flight on time?”
    2. The Agent invokes the Weather Tool and obtains {"city": "Barcelona", "forecast": "rain"}.
    3. The Agent invokes the Flights Tool and obtains {"flight": "IB123", "status": "on time"}.
    4. Synthesis: The Agent does not show you the two JSONs. It generates a natural response: “Your flight IB123 to Barcelona is scheduled on time, but I recommend taking an umbrella because rain is expected.”

Hybrid Automations

Combine AI with traditional tools.

The most valuable use cases often combine the intelligence of AI with the business tools you already use.

Hybrid Automation: AI + External Tools

A hybrid automation is a flow where an AI Agent makes decisions that are executed by non-AI components.

  • Practical Example: Automated Sales Report
    1. A Scheduler executes the flow every day at 9 AM.
    2. A SQL component queries your database and obtains the previous day’s sales.
    3. An AI Agent receives the sales data in JSON format. Its task is to analyze the data and write an executive summary in natural language highlighting the key trends.
    4. A Slack Sender component takes the summary generated by the agent and posts it to the team’s #sales channel.