Knowledge Base
Knowledge Base
  • Login
Font Size:
Ask Joget AI

Agent API

Introduction

The Agent API allows you to interact with AI Agents from the AI Agent Builder within the current app context in Joget. This API supports various operations, including fetching and retrieving agents.

Plugin information

The Agent API plugin is an addon plugin for the API Builder that enables you to expose agent functionality as REST endpoints within the Joget application. This API interacts with the agent selected in the current app context, allowing external systems and workflows to trigger agents seamlessly through REST calls.

Get started

Prerequisites

  • The AI Agent Builder addon builder plugin installed and configured with an API key.
  • An AI Agent configured with a File Upload element.
  • Agent API Addon plugin.

Where to get the plugin

The plugin is coming soon to the Joget Marketplace.

How to install

Upload the plugin to Joget by navigating to Settings > Manage Plugins > Upload Plugin as admin.

How to use it

AI Agent Builder

  1. In AI Agent Builder, create an agent and configure the Role, Backstory, and Prompt.
  2. In the Settings tab, configure two input types: text and file query. You may add additional file inputs as needed with a different name and label. 
  3. Click Save.

API Builder

  1. Within the same app, create a new API under API Builder in the App Composer.
  2. Drag and drop the Agent API from the Palette to the Canvas.
  3. Select the Agent created in AI Agent Builder.
  4. Enter Short Description (optional).
  5. Select the endpoints.

Fields to configure:

  • Agent: Select any Agebt present in the current app for interaction with the API.
  • Short Description: Any description.
  • Ignore form Permission: Check this option to fetch the agent & run the agent for current users when retrieving form data.

List of API Endpoints

Run AI file preview

Run the agent with the provided parameters.

URL: /agent/AI-file_preview/run

HTTP Method: POST

Path Parameters

N/A

Body Parameters

Possible responses:

Code Description
200 Operation successful
404 Not found
500 Internal server error

The parameters required here are highly dependent on the form data schema of the specified form.

Sample Response

For example, this is the 200 response when asking the agent to analyze an image of a city skyline:

{
  "created": 1766991114,
  "usage": {
    "completion_tokens": 59,
    "prompt_tokens": 1131,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 1190
  },
  "model": "gpt-4o-2024-08-06",
  "service_tier": "default",
  "id": "<id>",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "role": "assistant",
        "refusal": null,
        "annotations": [],
        "content": "The image you've provided is of a city skyline at sunset with tall buildings reflecting in a body of water. If you have specific text or topics from a PDF you want summarized, feel free to provide the details!"
      },
      "logprobs": null
    }
  ],
  "system_fingerprint": "fp_deacdd5f6f",
  "object": "chat.completion"
}
JSON
 

Get AI file preview

Get the agent definition.

URL: /agent/AI-file_preview

HTTP Method: GET

Path Parameters

N/A

Body Parameters

Possible responses:

Code Description
200 Operation successful
404 Not found
500 Internal server error

The parameters required here are highly dependent on the form data schema of the specified form.

Sample Response

The 200 response when executed successfully:

{
  "id": "AI-file_preview",
  "name": "File Preview",
  "description": null,
  "definition": {
    "agent": {
      "llm": [
        {
          "className": "org.joget.ai.agent.lib.OpenAIAgentLLM",
          "properties": {
            "apiKey": "",
            "apiUrl": "",
            "model": "gpt-4o",
            "id": "583D28EE3192453626DA7A3C0241C4A7"
          }
        }
      ],
      "prompt": []
    },
    "className": "org.joget.ai.agent.AgentBuilder",
    "prompt": [
      {
        "className": "org.joget.ai.agent.lib.PersonaAgentPrompt",
        "properties": {
          "backstory": "Your writing is insightful, well-researched, and future-oriented, with a focus on:\n- Technical deep dives\n- Industry impact analyses\n- Ethical and societal discussions\n- Comparative studies\nYour goal is to educate and inspire businesses, researchers, and enthusiasts about ${query}.",
          "role": "Research Analyst & Tech Writer",
          "id": "74697FE1DF7E4F1762015652C36E6426"
        }
      }
    ],
    "properties": {
      "agentDebugMode": "",
      "inputs": [
        {
          "name": "query",
          "description": "An image or file for LLM Agent to read.",
          "label": "Query",
          "type": "textfield"
        },
        {
          "name": "file",
          "description": "Upload an image",
          "label": "File",
          "type": "file"
        }
      ],
      "name": "File Preview",
      "description": "",
      "logo": "",
      "id": "AI-file_preview"
    },
    "tasks": [
      {
        "enhancer": [],
        "prompt": [
          {
            "className": "org.joget.ai.agent.lib.TextPromptAgentPrompt",
            "properties": {
              "msgRole": "USER",
              "id": "C824CAC6C75D442B5D490AA36D988482",
              "prompt": "Explain or summarize the ${query}."
            }
          },
          {
            "className": "org.joget.ai.agent.lib.FileAgentPrompt",
            "properties": {
              "msgRole": "USER",
              "purpose": "To read the contents of the pdf for previewing",
              "source": "app",
              "id": "D7B0886B191D4E62D09E7672E5775682",
              "appResorce": "citySkyline.png",
              "fileType": "IMAGE"
            }
          }
        ],
        "properties": {
          "id": "9ddf223d-7289-4f54-9548-d5043f70b9f1",
          "label": "First Task"
        },
        "tool": []
      }
    ]
  }
}
JSON
Created by Debanraj Ravindran Last modified by Debanraj Ravindran on Dec 29, 2025
Tags:
Previous API Element NextApp API