OpenAPI Agent

⚠️ DEPRECATION WARNING

This component is deprecated and will be removed in a future version of Nappai. Please migrate to the recommended alternative components.

The OpenAPI Agent is designed to help you automate interactions with external services without writing code. It uses an AI model to understand your data requirements, automatically generates the necessary requests, and returns the results to your workflow. Think of it as a virtual assistant that reads a technical guide (API specification) and uses it to communicate with other systems on your behalf.

How it Works

This component acts as a bridge between your Nappai workflow and external APIs. When you run it, the agent follows these simple steps:

Reads the API Guide: It loads the specification file you provide, which explains how the external system organizes its data and what actions it can perform.
Uses the AI Brain: Your selected Language Model analyzes the specification to understand exactly what needs to be done.
Makes Safe Requests: Based on your instructions, the agent prepares and sends the appropriate requests to the external API.
Returns Results: Once the external system responds, the agent formats the data and passes it along to the next step in your workflow.

Inputs

The following fields are available to configure this component.

Model: The AI model that powers the agent’s reasoning and decision-making process.
File Path: The location of the external API’s specification file (OpenAPI v2/v3) that defines available endpoints and data structures.
Allow Dangerous Requests: A security toggle that determines whether the agent can perform potentially risky or restricted HTTP operations.
Handle Parse Errors: Controls how the component handles and reports issues when reading or processing data formats.
Input: The initial data or instructions passed into the agent to start its processing.
Max Iterations: Sets the maximum number of decision cycles the agent can perform before stopping.
Verbose: Enables detailed logging to help you track exactly what the agent is doing during execution.

Outputs

Agent: The fully configured agent ready to be triggered by your workflow. It acts as an executable node that processes requests and returns results.
Response: The final output or message generated after the agent successfully communicates with the external API.

Output Data Example (JSON)json

{ “status”: “success”, “data”: { “endpoint”: “/api/v1/users”, “records”: [ { “id”: 101, “name”: “Example User”, “role”: “admin” } ], “metadata”: { “total_records”: 1, “fetched_at”: “2024-01-15T10:30:00Z” } } }

Connectivity

This component is typically placed after a file upload or configuration node and before data processing, database update, or notification nodes. It works best when connected to:

Input/Trigger Nodes: To start the workflow with specific instructions or data.
Data Processors/Transformers: To clean or format the JSON responses returned by external APIs.
Output/Action Nodes: Such as email senders, database writers, or dashboard updaters that need the fetched data.

Usage Example

Imagine you need to automatically fetch the latest customer records from a third-party CRM system and add them to your internal dashboard.

Upload your CRM’s OpenAPI specification file to the File Path input.
Connect your preferred AI model to the Model input.
Set Allow Dangerous Requests to False for standard read-only operations.
Pass a simple instruction like "Fetch the last 50 customers" into the Input field.
The agent will automatically generate the correct API call, retrieve the data, and output a structured response that you can directly map to a table or reporting node.

Important Notes

🔒 Use Secure Endpoints 🔴 When the agent calls external APIs, ensure those endpoints require proper authentication. Avoid exposing sensitive credentials in the spec or the environment.

⚠️ Only JSON or YAML Spec Files 🟡 The component will only load OpenAPI specifications that are in JSON or YAML format. Spec files in other formats will cause an error during initialization.

⚠️ Dangerous Request Control 🟡 If the “Allow Dangerous Requests” toggle is set to true, the agent can send any HTTP method, including potentially destructive ones. Use this option only with trusted specs and controlled environments.

📋 Compatible Language Model Required 🟢 You must provide a language model (LLM) that the component can use for generating API calls. The model must support the prompt templates used by LangChain.

💡 Validate the OpenAPI Spec First 🟢 Before loading the spec, run it through an OpenAPI validator to catch errors early. A valid spec ensures the agent can correctly construct API calls.

💡 Keep Spec Files Manageable 🟢 Large OpenAPI specifications can slow down agent startup. If possible, trim unused paths or use a focused spec to improve performance.

⚙️ Check the Max Iterations Setting 🟡 The agent’s “max_iterations” parameter controls how many decision cycles it can perform. A very high value may increase runtime, while a low value could stop the agent prematurely.

Tips and Best Practices

Always start with a read-only API spec to safely test the agent’s behavior before allowing write or delete operations.
Keep your API specification files up to date so the agent doesn’t attempt to use deprecated endpoints.
Use the Verbose input during testing to get detailed logs that help troubleshoot unexpected behavior.
If you experience timeouts or incomplete responses, reduce the Max Iterations or simplify the instruction passed to the agent.

Security Considerations

This component handles external API communications, so security should be your priority. By default, Allow Dangerous Requests is turned off (False), which restricts the agent to standard, safe HTTP operations. Only enable it if you are fully confident in the safety and source of your external API. Never share sensitive API keys or credentials through the specification file; instead, rely on Nappai’s secure credential management. Regularly audit the data flows generated by this agent to ensure no unauthorized access occurs.