Skip to content
Nappai Documentation

Basic Agent

The Basic Agent is a conversational AI component designed to help you answer questions and complete tasks within your Nappai workflow. Think of it as a smart assistant that reads your instructions, checks if it needs outside information to answer correctly, and then provides a clear, text-based response.

It works similarly to a chat interface: you give it a prompt, it thinks about the answer (potentially using connected tools like a web search or database), and returns the result to you. This component is currently in the development phase, meaning it is very useful for building prototypes and testing, but its behavior may change slightly as it is refined.

How it Works

When you connect this component to your workflow, it acts as the “brain” for a specific task. Here is the simple process it follows:

  1. Receives Input: You provide a question or instruction in the Input field. You can also provide the Chat History so the agent understands context from previous messages.
  2. Decides on Action: The agent analyzes your request. If you have connected Tools (like a calculator or web search), it decides whether to use them.
  3. Generates Response:
    • If no tools are needed, it answers directly based on its knowledge.
    • If tools are needed, it briefly pauses to fetch the data, then combines that data into a final answer.
  4. Updates Memory: The conversation (your question and its answer) is saved to the Updated Chat History, allowing you to ask follow-up questions in subsequent steps.

Connection & Credentials

This component requires a connection to an AI model to function. Before using this node, you must configure a credential in your Nappai panel:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential for the AI provider you are using (e.g., OpenAI, Anthropic, etc.) and fill in the required API keys.
  3. In your workflow, click on the Basic Agent component and select your saved credential in the Model input field.

Without a valid Model credential, the agent will not be able to generate responses.

Operations

This component does not have distinct “operations” to select. It operates as a single conversational agent by default. Simply connect it and provide your input.

Inputs

The following fields are available to configure this component. Each field may be visible in different operations:

  • External Checkpointer: A handle that allows you to save the state of your conversation externally. If you provide this, it overrides the internal memory system, which is useful for saving complex chat states across different sessions.
  • Model: The specific AI language model to use for generating answers (e.g., GPT-4, Llama-3). You must connect a valid Model credential here.
  • Tools: Optional tools that the agent can use to perform actions (like searching the web or calculating numbers). Connect external tool components here if you want the agent to perform tasks beyond just talking.
  • Agent Description: A short description of what this agent does. This is primarily used when you call this agent as a tool from another part of your workflow.
  • Agent Name: The name of the agent when it is used as a tool by other components.
  • Input: The main question or instruction you want the agent to answer. This is the most critical input.
  • Memory Limit: The maximum number of past messages the agent remembers. Use -1 for unlimited history. Lowering this limit can help with performance if your conversations become very long.
  • Stream: Enable this to see the answer appear word-by-word in real-time rather than waiting for the entire answer to be generated at once.
  • System Prompt: Advanced instructions that tell the agent how to behave (e.g., “Be polite,” “Only answer in Spanish”). You usually don’t need to change this.
  • Use Memory: A toggle to enable or disable conversation memory. If enabled, the agent remembers previous messages in the Chat History to provide context-aware answers.

Outputs

The component produces two main outputs that you can use in the rest of your workflow:

  • Agent: The compiled agent structure itself. This is primarily used if you need to pass this agent instance to other complex components.
  • Response: The actual text answer generated by the agent. You will typically connect this output to other components that need to process or display the answer.
  • Tool: The tool representation of the agent, allowing it to be used as a sub-task within other workflows.

Output Data Example (JSON)

Here is an example of the Response output you might receive after asking “What is the weather in London?”: json { “content”: “The current weather in London is partly cloudy with a temperature of 15°C.”, “role”: “assistant”, “metadata”: { “used_tool”: “web_search”, “tool_result_summary”: “Weather data retrieved from external service” } }

Connectivity

In a typical workflow, this component connects as follows:

  • From: It receives input from Chatbot Nodes, Text Inputs, or other agents that need an answer.
  • To: It sends its Response to Text Output Components, Email/Slack Integrations, or further Data Processing Agents that refine the answer.
  • Loop: The Updated Chat History output often loops back into the Chat History input of the same component (or a following instance) to maintain conversation continuity.

Usage Example

Scenario: You want to build a support assistant that answers customer FAQs but checks the latest product prices from a database before answering.

  1. Setup: Connect your AI API Credential to the Model field.
  2. Tools: Connect a “Database Search Tool” to the Tools field.
  3. Input: In the Input field, enter: “How much does Product X cost?”
  4. Process: The agent sees the Tool, decides it needs to look up the price, executes the search, and then formats the final answer.
  5. Result: The Response output will contain: “Product X currently costs $50.00.”
  6. Flow: Connect this response to a Send Email node to reply to the customer.

Important Notes

🔒 External Data Transmission The agent may send your questions and any retrieved data to external services (e.g., LLM providers). Be mindful of sharing sensitive or personal information during interactions.

⚠️ Development-Mode Instability The Basic Agent is marked as in development, which means it may not consistently produce correct or complete answers and can occasionally fail to load tools. Users might notice unexpected responses or errors during use.

📋 Configure External Tools and API Keys Before using the agent, ensure that any required tools (e.g., web search, database access) are properly configured and that necessary API keys for the LLM are set. Without these, the agent will be unable to answer questions that need external information.

⚙️ Enable Internet Access for Tool Functionality Tools such as web search require outbound network connectivity. Make sure your environment allows the agent to connect to the internet; otherwise, tool-based answers will fail.

💡 Ask Clear, Specific Questions To get the most accurate and helpful responses, phrase your questions concisely and include any relevant details. Vague queries can cause the agent to use unnecessary tools or produce generic answers.

ℹ️ Potential Delays When Using Tools When the agent needs to retrieve information from external tools, it may take several seconds or more to return a response. Patience is advised during these moments to allow the agent to gather and process the data.

Tips and Best Practices

  • Keep Inputs Short: For the best results, keep your Input questions direct and clear.
  • Use Tools Wisely: Only connect tools you actually need. Too many tools can confuse the agent and slow down the response.
  • Monitor Memory Usage: If your conversations get very long, consider adjusting the Memory Limit to keep the workflow fast and efficient.
  • Test in Development: Since this component is in development mode, test it thoroughly in a sandbox environment before using it for critical automated tasks.

Security Considerations

  • Data Privacy: Since this component interacts with external LLM providers, avoid inputting personally identifiable information (PII) or sensitive business secrets unless you have verified the privacy policies of the connected model.
  • Tool Access: Be cautious when connecting tools. If you connect a tool that writes to a database, ensure you have the appropriate permissions to prevent accidental data deletion or modification.