Enterprise AI
Table of contents
Official Content
  • This documentation is valid for:

This API allows you to manage AI Agents within a project in Globant Enterprise AI. You can create, get, update, and delete agents, as well as define their model, reasoning strategy, and tools.

Check the Globant Enterprise AI API Reference for generic variables needed to use the API.

Endpoints

Method Path Description
POST /agents/ Creates a new Agent definition within a specific organization and project.
PUT /agents/{idOrName}/upsert Creates the Agent if it doesn't exist; otherwise, updates its definition using the provided id or name.
PUT /agents/{idOrName} Updates Agent details.
POST /agents/{idOrName}/publish-revision Publishes a specific revision of an Agent.
GET /agents/{idOrName} Gets Agent details.
GET /agents Gets the list of Agents.
DELETE /agents/{idOrName} Deletes an Agent.

Authentication

All endpoints require authentication using one of the following:

  • Authorization: Bearer $SAIA_APITOKEN
  • Authorization: Bearer $OAuth_accesstoken

For $OAuth_accesstoken, you must also include the header: ProjectId: $SAIA_PROJECT_ID

Some endpoints may require additional headers such as:

  • Content-Type: application/json
  • Accept: application/json

POST/agents/

This endpoint allows you to create a new Agent definition within a specific organization and project.

Parameters

Name Type Description
automaticPublish boolean Controls whether an Agent is automatically published after it is created or updated (optional).
If set to true, the Agent is validated and published in a single operation.
If omitted or set to false, the Agent is created as a draft and not published.

Request

  • Method: POST
  • Path: $BASE_URL/v2/agents

Request Body

{
  "agentDefinition": {
    "name": "string",                         // Agent name (unique per project)
    "accessScope": "string",                  // "private" | "public"
    "jobDescription": "string",               // Short role description
    "avatarImage": "string",                  // URL of the avatar image
    "description": "string",                  // Human-readable summary
    "agentData": {
      "strategyName": "string",               // Reasoning strategy (e.g., "Chain of Thought")
      "prompt": {
        "context": "string", 
        "instructions": "string" 
      },
      "llmConfig": {
        "maxTokens": integer,                 // Maximum tokens per response
        "timeout": integer,
        "sampling": {
          "temperature": number
        }
      },
      "models": [
        { "name": "string" }                  // LLM name (e.g., "gpt-4o")
      ],
      "resourcePools": [
        {
          "name": "string", 
          "tools": [
            { "name": "string" }
          ]
        }
      ]
    }
  }
}

Response

A successful Agent creation returns a 201 Created status code along with the full Agent details in the response. This includes the Agent's id, name, publicName, description, prompt settings, models, and status.

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,
      "sampling": { "temperature": number },
      "timeout": integer
    },
    "models": [ { "name": "string" } ],
    "prompt": {
      "context": "string",
      "instructions": "string"
    },
    "resourcePools": [
      {
        "isExternal": boolean,
        "name": "string",
        "tools": [ { "name": "string" } ]
      }
    ],
    "strategyName": "string"               // Reasoning strategy (e.g., "Chain of Thought")
  },
  "description": "string",
  "id": "string",                             // Agent GUID
  "isDraft": boolean,
  "jobDescription": "string",
  "name": "string",            // Agent name (unique per project)
  "revision": integer,
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

curl -X POST "$BASE_URL/v2/agents?automaticPublish=true" \
  -H "Authorization: Bearer $SAIA_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentDefinition": {
      "name": "DeepResearcher2",
      "accessScope": "private",
      "jobDescription": "Web Researcher & Knowledge Synthesizer",
      "avatarImage": "http://miserver.com/micontenido/logo.png",
      "description": "A specialized agent designed to perform thorough, multi-layered web searches to answer user questions. It gathers data, synthesizes information, and presents comprehensive results.",
      "agentData": {
        "strategyName": "Chain of Thought",
        "prompt": {
          "context": "Your objective is to conduct deep and meticulous web searches to answer user questions with detailed, evidence-based responses.",
          "instructions": "When a query is presented you should (1)identify and retrieve information from reputable sources. ...etc"
        },
        "llmConfig": {
          "maxTokens": 5000,
          "timeout": 0,
          "sampling": { "temperature": 0.5 }
        },
        "models": [ { "name": "gpt-4o" } ],
        "resourcePools": [
          {
            "name": "Main",
            "tools": [
              { "name": "com.globant.geai.web_scraper" },
              { "name": "com.globant.geai.web_search" }
            ]
          }
        ]
      }
    }
  }'

PUT /agents/{idOrName}/upsert

This endpoint allows you to create or update (upsert) an Agent definition identified by its id or name within a specific project.

Parameters

Name Type Description
automaticPublish boolean Controls whether an Agent is automatically published after it is created or updated (optional).
If set to true, the Agent is validated and published in a single operation.
If omitted or set to false, the Agent is created as a draft and not published.

Request

  • Method: PUT
  • Path: $BASE_URL/v2/agents/{idOrName}/upsert

Request Body

{
  "agentDefinition": {
    "name": "string",                         // Agent name (unique within the project)
    "accessScope": "string",                  // "private" | "public"
    "jobDescription": "string",               // Short role description
    "avatarImage": "string",                  // URL of the avatar image
    "description": "string",                  // Human-readable summary
    "agentData": {
      "strategyName": "string",               // Reasoning strategy (e.g., "Chain of Thought")
      "prompt": {
        "context": "string",
        "instructions": "string"
      },
      "llmConfig": {
        "maxTokens": integer,                 // Maximum tokens per response
        "timeout": integer,
        "sampling": {
          "temperature": number
        }
      },
      "models": [
        { "name": "string" }                  // LLM name (e.g., "gpt-4o")
      ],
      "resourcePools": [
        {
          "name": "string",
          "tools": [
            { "name": "string" } 
          ]
        }
      ]
    }
  }
}

Response

A successful request returns a 201 status code and the details of the created or updated Agent.

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,
      "sampling": { "temperature": number },
      "timeout": integer
    },
    "models": [ { "name": "string" } ],
    "prompt": {
      "context": "string",
      "instructions": "string"
    },
    "resourcePools": [
      {
        "isExternal": boolean,
        "name": "string",
        "tools": [ { "name": "string" } ]
      }
    ],
    "strategyName": "string"               // Reasoning strategy (e.g., "Chain of Thought")
  },
  "description": "string",
  "id": "string",                             // Agent GUID
  "isDraft": boolean,
  "jobDescription": "string",
  "name": "string",                          // Agent name (unique per project)
  "revision": integer,
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

curl -X PUT "$BASE_URL/v2/agents/DeepResearcher/upsert?automaticPublish=true" \
  -H "Authorization: Bearer $SAIA_APITOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "ProjectId: $SAIA_PROJECT_ID" \
  -d '{
    "agentDefinition": {
      "name": "DeepResearcher",
      "accessScope": "private",
      "jobDescription": "Web Researcher & Knowledge Synthesizer",
      "avatarImage": "http://miserver.com/micontenido/logo.png",
      "description": "A specialized agent designed to perform thorough, multi-layered web searches to answer user questions. It gathers data, synthesizes information, and presents comprehensive results.",
      "agentData": {
        "strategyName": "Chain of Thought",
        "prompt": {
          "context":"Your objective is to conduct deep and meticulous web searches to answer user questions with detailed, evidence-based responses.",
          "instructions": "When a query is presented you should (1)identify and retrieve information from reputable sources. ...etc "
        },
        "llmConfig": {
          "maxTokens": 5000,
          "timeout": 0,
          "sampling": { "temperature": 0.5 }
        },
        "models": [ { "name": "gpt-4o" } ],
        "resourcePools": [
          {
            "name": "Main",
            "tools": [
              { "name": "com.globant.geai.web_scraper" },
              { "name": "com.globant.geai.web_search" }
            ]
          }
        ]
      }
    }
  }'

PUT/agents/{idOrName}

This endpoint updates the details of an existing Agent, identified by its id or name.

Parameters

Name Type Description
automaticPublish boolean Controls whether an Agent is automatically published after it is created or updated (optional).
If set to true, the Agent is validated and published in a single operation.
If omitted or set to false, the Agent is created as a draft and not published.

Request

  • Method: PUT
  • Path: $BASE_URL/v2/agents/{idOrName}

Request body

{
  "agentDefinition": {
    "name": "string",                         // Agent name (unique per project)
    "accessScope": "string",                  // "private" | "public"
    "jobDescription": "string",               // Short role description for end-users
    "avatarImage": "string",                  // URL of the avatar image
    "description": "string",                  // Human-readable summary
    "agentData": {
      "strategyName": "string",               // Reasoning strategy (e.g., "Chain of Thought")
      "prompt": {
        "context": "string",
        "instructions": "string" 
      },
      "llmConfig": {
        "maxTokens": integer,             // Agent name (unique per project)
        "timeout": integer,
        "sampling": {
          "temperature": number
        }
      },
      "models": [
        { "name": "string" }                  // LLM name (e.g., "gpt-4o")
      ],
      "resourcePools": [
        {
          "name": "string",
          "tools": [
            { "name": "string" }
          ]
        }
      ]
    }
  }
}

Response

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,
      "sampling": { "temperature": number },
      "timeout": integer
    },
    "models": [ { "name": "string" } ],
    "prompt": {
      "context": "string",
      "instructions": "string"
    },
    "resourcePools": [
      {
        "isExternal": boolean,
        "name": "string",
        "tools": [ { "name": "string" } ]
      }
    ],
    "strategyName": "string"               // Reasoning strategy (e.g., "Chain of Thought")
  },
  "description": "string",
  "id": "string",                             // Agent GUID
  "isDraft": boolean,
  "jobDescription": "string",
  "name": "string",            // Agent name (unique per project)
  "revision": integer,
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

curl -X PUT "$BASE_URL/v2/agents/DeepResearcher?automaticPublish=true" \
  -H "Authorization: Bearer $SAIA_APITOKEN" \
  -H "Content-Type: application/json" \
  -H "ProjectId: " \
  -d '{
    "agentDefinition": {
      "name": "DeepResearcher",
      "accessScope": "private",
      "jobDescription": "Web Researcher & Knowledge Synthesizer",
      "avatarImage": "http://miserver.com/micontenido/logo.png",
      "description": "A specialized agent designed to perform thorough, multi-layered web searches to answer user questions. It gathers data, synthesizes information, and presents comprehensive results.",
      "agentData": {
        "strategyName": "Chain of Thought",
        "prompt": {
          "context":"Your objective is to conduct deep and meticulous web searches to answer user questions with detailed, evidence-based responses.",
          "instructions": "When a query is presented you should (1)identify and retrieve information from reputable sources. ...etc "
        },
        "llmConfig": {
          "maxTokens": 5000,
          "timeout": 0,
          "sampling": { "temperature": 0.5 }
        },
        "models": [ { "name": "gpt-4o" } ],
        "resourcePools": [
          {
            "name": "Main",
            "tools": [
              { "name": "com.globant.geai.web_scraper" },
              { "name": "com.globant.geai.web_search" }
            ]
          }
        ]
      }
    }
  }'

POST /agents/{idOrName}/publish-revision

This endpoint publishes a specific revision of an Agent, identified by either its id or name.

Request

  • Method: POST
  • Path: $BASE_URL/v2/agents/{idOrName}/publish-revision

Request body

{
  "revision": integer                        // Revision number to publish
}

Response

A successful request returns a 200 status code and the published Agent’s details. 

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,
      "sampling": { "temperature": number },
      "timeout": integer
    },
    "models": [
      { "name": "string" } 
    ],
    "prompt": {
      "context": "string",
      "instructions": "string"
    },
    "resourcePools": [
      {
        "isExternal": boolean,
        "name": "string",
        "tools": [
          { "name": "string" } 
        ]
      }
    ],
    "strategyName": "string"
  },
  "avatarImage": "string",                    // URL of the avatar image
  "description": "string",                    // Human-readable summary
  "id": "string",                             // Agent GUID
  "isDraft": false,                           // Always false after publishing
  "jobDescription": "string",
  "name": "string",
  "revision": integer,                        // Published revision number
  "version": integer,                         // New public version number
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

curl -X POST "$BASE_URL/v2/agents/DeepResearcher/publish-revision" \
  -H "Authorization: Bearer $SAIA_APITOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": 2
  }'

GET /agents/{idOrName}

This endpoint is used to retrieve the definition of a specific Agent by providing its id or name. You can optionally specify a revision and version, and allow drafts to be retrieved.

Parameters

Name Type Description
revision integer Revision number to retrieve (optional).
If omitted, the endpoint returns the latest published revision.
version integer Version number to retrieve (optional).
If omitted, the endpoint returns the latest published version.
allowDrafts boolean Enables retrieval of draft revisions (optional).
If true, the endpoint may return a draft when the requested revision is a draft.
Default is false.

Request

  • Method: GET
  • Path: $BASE_URL/v2/agents/{idOrName}
  • Body: Empty

Response

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,
      "sampling": { "temperature": number },
      "timeout": integer
    },
    "models": [                           // LLMs used by the agent
      { "name": "string" }                    // e.g., "gpt-4o"
    ],
    "prompt": {
      "context": "string",                    // System-level context for the LLM
      "instructions": "string"                // Detailed step-by-step instructions
    },
    "resourcePools": [
      {
        "isExternal": boolean,
        "name": "string",                     // Logical pool name
        "tools": [
          { "name": "string" }                // Fully-qualified tool name
        ]
      }
    ],
    "strategyName": "string"                  // Reasoning strategy
  },
  "avatarImage": "string",                    // URL of the avatar image
  "description": "string",                    // Human-readable summary
  "id": "string",                             // Agent GUID
  "isDraft": boolean,                         // true if this is a draft
  "jobDescription": "string",
  "name": "string",
  "revision": integer,                        // Current revision number
  "version": integer,                         // Published version number (omitted if draft)
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

curl -X GET "$BASE_URL/v2/agents/DeepResearcher?revision=2&version=1&allowDrafts=true" \
  -H "Authorization: Bearer $SAIA_APITOKEN" \
  -H "Accept: application/json"

GET /agents

This endpoint retrieves a list of Agents within a specific project, optionally filtering by status, pagination, access scope, and inclusion of drafts or external Agents.

Parameters

Name Type Description
status string Filter by Agent status (active, inactive).
Optional – omit to return all statuses.
start integer Zero-based index of the first record to return (pagination).
Optional – default = 0.
count integer Maximum number of records to return (pagination).
Optional – default = 20.
accessScope string Filter by access scope (public, private).
Optional – omit to return both scopes.>
allowDrafts boolean When true, each Agent is returned with its latest revision even if that revision is a draft.
Optional – default = false.
includeExternal boolean When true, includes Agents created outside the current project.
Optional – default = false.

Request

  • Method: GET
  • Path: $BASE_URL/v2/agents
  • Body: Empty

Response

{
  "agents": [
    {
      "accessScope": "string",                // "private" | "public"
      "description": "string",                // Human-readable summary
      "id": "string",                         // Agent GUID
      "isDraft": boolean,                     // true if latest revision is a draft
      "name": "string",
      "revision": integer,                    // Latest revision number returned
      "status": "string",                     // "active" | "inactive"
      "version": integer                      // Latest published version (omitted when draft)
    }
  ]
}

cURL Sample

curl -X GET "$BASE_URL/v2/agents?status=active&start=0&count=10&accessScope=public&allowDrafts=true&includeExternal=false" \
  -H "Authorization: Bearer $SAIA_APITOKEN"

DELETE /agents/{idOrName}

Deletes an existing Agent identified by its id or name.

Request

  • Method: DELETE
  • Path: $BASE_URL/v2/agents/{idOrName}
  • Body: Empty

Response

  • 204 No Content: Agent was successfully deleted.
  • 404 Not Found: No Agent was found with the given idOrName.

cURL Sample

curl -X DELETE "$BASE_URL/v2/agents/DeepResearcher" \
  -H "Authorization: Bearer $SAIA_APITOKEN"

Availability

Since May 2025 release.

—
Last update: 10 June 2025 by slinares
Last update: March 2025 | © GeneXus. All rights reserved. GeneXus Powered by Globant