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’s State

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

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

Data Passing: Agent → Tool → Agent Cycle

The most common data flow in an AI system is the following:

  1. The Agent receives an input: For example, a JSON object like {"input": "Search for the last email from John"}.
  2. The Agent decides to use a tool: It analyzes the input and determines it must 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, e.g., {"from": "John", "limit": 1}.
  4. The tool returns a result: The Get Emails tool executes and returns a JSON object with the email data, e.g., {"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 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)

This is the most fundamental data type. It’s the basis for user inputs, LLM responses, and most API interactions.

Files (Binary)

An Agent doesn’t handle files directly from a chat input; instead, it uses Tools to interact with them. For example, you can connect a component like Google Drive Loader as a tool to your agent.

  • The Process:
    1. The Agent receives an instruction like “summarize the document ‘annual-report.pdf’ in my Drive.”
    2. The Agent identifies the need to access Google Drive and calls the Google Drive Loader tool, passing it the file name.
    3. The tool handles searching for, downloading, and converting the file (PDF, DOCX, etc.) into plain text.
    4. The tool returns the extracted text to the Agent so it can process it (summarize it, analyze it, etc.).

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

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 sentiment of “frustration” or “anger,” the Agent can decide to invoke the “Escalate to Human” tool. If it detects a “technical question,” it will invoke the “Search Knowledge Base” tool.

Cognitive Merging (Synthesis)

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

  • Practical Example:
    1. User: “What will the weather be like in Barcelona tomorrow and is my flight on time?”
    2. The Agent calls the Weather Tool and gets {"ciudad": "Barcelona", "previsión": "lluvia"}.
    3. The Agent calls the Flight Tool and gets {"vuelo": "IB123", "estado": "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 takes decisions that are executed by non-AI components.

  • Practical Example: Automated Sales Report
    1. A Scheduler runs the flow every day at 9 AM.
    2. A SQL component queries your database and gets 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.