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

The Agents API allows you to manage AI Agents within a project in Glob.AI OS. You can create, get, update, and delete Agents, as well as configure their model, reasoning strategy, and tools.

For generic variables needed to use the API, see the API Reference.

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.
GET /agents/{ToolId} Retrieves information of Agents associated with a specific Tool.
DELETE /agents/{idOrName} Deletes an Agent.
GET /agents/{idOrName}/export Exports a single Agent into a transportable package (labPackage).
POST /agents/import Imports one or more Agents, Tools, Tool Plugins, and Tool Groups from into a transportable package (labPackage).
DELETE /agents/{idOrName}/drafts/{revision} Deletes the last draft created.
GET /agents/{idOrName}/versions Retrieves paginated list of an Agent versions.
POST /agents/{idOrName}/revert Reverts an Agent to a specified target revision.
POST /agents/{idOrName}/versions/{versionNumber}/deprecate Deprecates the specified version of an Agent.
PUT /agents/{idOrName}/versions/{versionNumber} Updates the specified Agent version’s metadata.
GET /agents/{idOrName}/drafts Retrieves the paginated list of draft revisions for a given Agent.
GET /agents/{idOrName}/export Exports the specified Agent as a JSON.

Authentication

All endpoints require authentication using one of the following:

  • Authorization: Bearer $GEAI_APITOKEN
  • Authorization: Bearer $OAuth_accesstoken

For $OAuth_accesstoken, you must also include the header: ProjectId: $GEAI_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/v4/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",                  // Prompt context
        "instructions": "string"              // Prompt instructions
      },
      "llmConfig": {
        "maxTokens": integer,                 // Maximum tokens per response
        "timeout": integer,                   // Timeout for LLM response
        "sampling": {
          "temperature": number               // Sampling temperature for LLM
        },
      },
      "models": [
        {
          "name": "string"                    // Model provider name (e.g., "gpt-4o")
        }
      ],
      "resourcePools": [
        {
          "name": "string",                   // Resource pool name
          "isExternal": boolean,              // When True, Tools are not validated.
          "tools":[
            {
              "name": "string",               // Tool name
              "id": "string"                  // Tool unique identifier
            }
          ]
        }
      ]
    }
  }
}

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.

If parameter automaticPublish is set as true and model is not authorized by the organization a 400 Bad request status code will be returned. When an Agent is published, the API validates whether the selected model is authorized for the organization. If the model is not permitted, the publication fails and the API returns an error with the field: "description": "Model not authorized name={model name}"

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,                   // Maximum tokens per response
      "sampling": {
        "temperature": number                 // Sampling temperature for LLM
      },
      "timeout": integer                      // Timeout for LLM response
    },
    "models":[
      {
        "name": "string"                      // Model provider name (e.g., "gpt-4o")
      }
    ],
    "prompt": {
      "context": "string",                    // Prompt context
      "instructions": "string"                // Prompt instructions
    },
    "resourcePools": [
      {
        "isExternal": boolean,                // When true, tools are not validated
        "name": "string",                     // Resource pool name
        "tools": [
          {
            "name": "string",                 // Tool name
            "id": "string"                    // Tool unique identifier
          }
        ]
      }
    ],
    "strategyName": "string"                  // Reasoning strategy (e.g., "Chain of Thought")
  },
  "description": "string",                    // Human-readable summary
  "id": "string",                             // Agent GUID
  "isDraft": boolean,                         // Indicates if the agent is a draft (true/false)
  "jobDescription": "string",                 // Short role description
  "name": "string",                           // Agent name (unique per project)
  "revision": integer,                        // Revision number of the agent
  "sharingScope": "string",                   // "none" | "organization" | "everybody" (default "organization")
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

curl -X POST "$BASE_URL/v4/agents?automaticPublish=true" \
  -H "Authorization: Bearer $GEAI_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": [
              { "id": "0ac5cd1d-c70e-47d2-a11a-81a0a2751d55" },
              { "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/v4/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",                  // Prompt context
        "instructions": "string"              // Prompt instructions
      },
      "llmConfig": {
        "maxTokens": integer,                 // Maximum tokens per response
        "timeout": integer,                   // Timeout for LLM response
        "sampling": {
          "temperature": number               // Sampling temperature for LLM
        },
      },
      "models": [
        {
          "name": "string"                    // LLM provider (e.g., "gpt-4o")
        }
      ],
      "resourcePools":[
        {
          "name": "string",                   // Resource pool name
          "tools":[
            {
              "name": "string",               // Tool name
              "id": "string"                  // Tool unique identifier
            }
         ]
        }
     ]
    }
  }
}

Response

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

If parameter automaticPublish is set as true and model is not authorized by the organization a 400 Bad request status code will be returned. When an Agent is published, the API validates whether the selected model is authorized for the organization. If the model is not permitted, the publication fails and the API returns an error with the field: "description": "Model not authorized name={model name}"

{
  "accessScope": "string",                    // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,                   // Maximum tokens per response
      "sampling": {
        "temperature": number                 // Sampling temperature for LLM
      },
      "timeout": integer                      // Timeout for LLM response
},
    "models": [
      {
        "name": "string"                      // Model provider name (e.g., "gpt-4o")
      }
    ],
    "prompt": {
      "context": "string",                    // Prompt context
      "instructions": "string"                // Prompt instructions
    },
    "resourcePools": [
      {
        "isExternal": boolean,                // When true, tools are not validated
        "name": "string",                     // Resource pool name
        "tools": [
          {
            "name": "string",                 // Tool name
            "id": "string"                    // Tool unique identifier
          }
       ]
      }
   ],
    "strategyName": "string"                  // Reasoning strategy (e.g., "Chain of Thought")
  },
  "description": "string",                    // Human-readable summary
  "id": "string",                             // Agent GUID
  "isDraft": boolean,                         // Indicates if the agent is a draft (true/false)
  "jobDescription": "string",                 // Short role description
  "name": "string",                           // Agent name (unique per project)
  "revision": integer,                        // Revision number of the agent
  "sharingScope": "string",                   // "none" | "organization" | "everybody" (default "organization")
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

 -X PUT "$BASE_URL/v4/agents/DeepResearcher/upsert?automaticPublish=true" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "ProjectId: $GEAI_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": [
              { "id": "0ac5cd1d-c70e-47d2-a11a-81a0a2751d55" },
              { "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/v4/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",                  // Prompt context
        "instructions": "string"              // Prompt instructions
      },
      "llmConfig": {
        "maxTokens": integer,                 // Maximum tokens per response
        "timeout": integer,                   // Timeout for LLM response
        "sampling": {
          "temperature": number               // Sampling temperature for LLM
        }
      },
      "models": [
          "name": "string"                    // provider name (e.g., "gpt-4o")
        }
      ],
      "resourcePools": [
        {
          "name": "string",                   // Resource pool name
          "tools": [
            {
              "id": "string",                 // Tool unique identifier
              "name": "string"                // Tool name
            }
          ]
        }
      ]
    }
  }
}

Response

If parameter automaticPublish is set as true and model is not authorized by the organization a 400 Bad request status code will be returned. When an Agent is published, the API validates whether the selected model is authorized for the organization. If the model is not permitted, the publication fails and the API returns an error with the field: "description": "Model not authorized name={model name}"

{
  "accessScope": "string", // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxTokens": integer,
      "sampling": { "temperature": integer },
      "timeout": integer
    },
    "models": [
      { "name": "string" }
    ],
    "prompt": {
      "context": "string",
      "instructions": "string"
    },
    "resourcePools": [
      {
        "isExternal": boolean,
        "name": "string",
        "tools": [
          { "id": "string", "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,
  "sharingScope": "string", // values: "none", "organization", "everybody" (default "organization")
  "status": "string" // "active" | "inactive"
}

cURL Sample

curl -X PUT "$BASE_URL/v4/agents/DeepResearcher?automaticPublish=true" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -H "ProjectId: $¨GEAI_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": "0ac5cd1d-c70e-47d2-a11a-81a0a2751d55" },
              { "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.

If parameter automaticPublish is set as true and model is not authorized by the organization a 400 Bad request status code will be returned. When an Agent is published, the API validates whether the selected model is authorized for the organization. If the model is not permitted, the publication fails and the API returns an error with the field: "description": "Model not authorized name={model name}"

{
  "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": [
          {"Id": "string" 
 "name": "string" } 
        ]
      }
    ],
    "strategyName": "string"
  },
  "avatarImage": "string",                    // URL of the avatar image
  "description": "string",                    // Human-readable summary
  "id": "string",                             // Agent GUID
  "isDraft": boolean,                           // Always false after publishing
  "jobDescription": "string",
  "name": "string",
  "revision": integer,                        // Published revision number
  "version": integer,                         // New public version number
  "sharingScope": "string",     // values can be: "none", "organization", "everybody"  (default "organization")  
  "status": "string"                          // "active" | "inactive"
}

cURL Sample

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

GET /agents/{idOrName}

This endpoint retrieves 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/v4/agents/{idOrName}
  • Body: Empty

Response

{
  "accessScope": "string",                      // "private" | "public" — Visibility of the Agent within the project/organization
  "agentData": {
    "llmConfig": {
      "maxRuns": integer,                       // Maximum number of reasoning/iteration runs the Agent may perform
      "maxTokens": integer,                     // Maximum tokens allowed in a single LLM response
      "sampling": {
        "temperature": number                   // Sampling temperature for the model (e.g., 0.0–2.0)
      }
    },
    "models": [
      {
        "llmConfig": {
          "maxTokens": integer,                 // Model-level token limit override
          "sampling": {
            "temperature": number               // Model-level sampling override
          },
          "uploadFiles": "string"               // File upload capability flag (e.g., "on" | "off");  uses the value associated with the model -if present - or the one of the agent when models do not specify a value; showed if no query parameters are included.
        },
        "name": "string"                        // Model identifier (e.g., "openai/gpt-5")
      }
    ],
    "prompt": {
      "context": "string",                      // Global context for the Agent's role and objectives
      "examples": [                             // Few-shot examples to guide the Agent
        {
          "inputData": "string",                // Example input
          "output": "string"                    // Expected output for the example input
        }
      ],
      "instructions": "string"                  // Operating instructions or guidelines for the Agent
    },
    "properties": [
      {
        "dataType": "string",                   // Data type of the property value (e.g., "String")
        "key": "string",                        // Property key (name)
        "value": "string"                       // Property value
      }
    ],
    "resourcePools": [
      {
        "isExternal": boolean,                  // When true, tools/resources may not be validated internally
        "name": "string"                        // Resource pool name
      }
    ],
    "strategyName": "string"                    // Reasoning strategy identifier or name (e.g., GUID or label)
  },
  "description": "string",                      // Human-readable description of the Agent
  "effectivePermissions": {
    "chatSharing": "string",                    // Effective chat-sharing scope (e.g., "none", "organization", "everybody")
    "externalExecution": "string"               // Effective external execution scope (e.g., "organization")
  },
  "id": "string",                               // Agent unique identifier (GUID)
  "isDraft": boolean,                           // True if the Agent is in draft state
  "jobDescription": "string",                   // Short role description of the Agent
  "name": "string",                             // Agent name (unique per project)
  "permissions": {
    "chatSharing": "string",                    // Configured chat-sharing scope
    "externalExecution": "string"               // Configured external execution scope
  },
  "revision": integer,                          // Current revision number of the Agent definition
  "status": "string",                           // Operational status of the Agent (e.g., "active" | "inactive")
  "version": integer                            // Internal version of the Agent definition
}

cURL Sample

curl -X GET "$BASE_URL/v4/agents/DeepResearcher?revision=2&version=1&allowDrafts=true" \
  -H "Authorization: Bearer $GEAI_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/v4/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",                       // Agent name (unique per project)
      "revision": integer,                    // Latest revision number returned
      "status": "string",                     // "active" | "inactive"
      "version": integer                      // Latest published version (omitted when draft)
    }
  ],
  "information": {
    "Duration": integer,                      // Duration of the query or operation
    "Page": integer,                          // Current page number of the result set
    "PageSize": integer,                      // Number of items per page
    "Total": integer                          // Total number of Agents found beyond the pagination
  }
}

cURL Sample

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

GET /agents/{ToolId}

This endpoint retrieves information of a specific Tool based on searches by ToolId. Provides information on duration, number of results, and paging.

Parameters

Name Type Description
allowDrafts boolean Enables retrieval of draft revisions. If true, the endpoint may return a draft when the requested revision is a draft. Default is false.
ToolId string ID of the Tool you wish to retrieve.

Request

  • Method: GET
  • Path: $BASE_URL/v4/agents/{ToolId}
  • Body: Empty

Response

{
  "agents": [
    {
      "accessScope": "string",                  // Access level for the agent (e.g., "private", "public")
      "description": "string",                  // Description of the agent's expertise or purpose
      "effectivePermissions": {
        "chatSharing": "string",                // Level of chat sharing permission (e.g., "none", "organization", "public")
        "externalExecution": "string"           // Permission for external execution (e.g., "none", "organization", "public")
      },
      "id": "string",                           // Unique identifier for the agent (UUID)
      "isDraft": boolean,                       // Indicates if the agent is a draft (true/false)
      "jobDescription": "string",               // Short description of the agent's role
      "name": "string",                         // Name of the agent
      "permissions": {
        "chatSharing": "string",                // Level of chat sharing permission
        "externalExecution": "string"           // Permission for external execution
      },
      "revision": integer,                      // Revision number of the agent
      "status": "string",                       // Current status of the agent (e.g., "active", "inactive")
      "version": integer                      // Version number of the agent
    }
    // ... more agent objects
  ],
  "information": {
    "Duration": integer,                        // Duration of the query or operation (in seconds or milliseconds, depending on context)
    "Page": integer,                            // Current page number of the result set
    "PageSize": integer,                        // Number of items per page
    "Total": integer                            // Total number of items available
  }
}

cURL Sample

  curl -X GET "$BASE_URL/v4/agents?allowDrafts=true&toolId=$ToolId" \
 -H "Authorization: Bearer $GEAI_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 $GEAI_APITOKEN"

GET /v2/agents/{idOrName}/export

Exports a single Agent into a transportable package (labPackage).

Request

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

Response

{
  "labPackage": { // Root lab package container
    "agents": [ // List of agents included in the lab package
      {
        "accessScope": "string", // Access scope of the agent: "private" | "public"
        "agentData": { // Technical configuration of the agent
          "LLMConfig": { // Language model runtime configuration
            "maxTokens": integer, // Maximum tokens allowed in a single response
            "sampling": { // Sampling/decoding configuration
              "temperature": number // Sampling temperature (fractional value, e.g., 0.5)
            }
          },
          "models": [ // Models available to the agent
            {
              "id": "string", // Model unique identifier (GUID or provider-specific)
              "name": "string" // Model name/provider key (e.g., "azure/gpt-4o")
            }
          ],
          "prompt": { // Prompt configuration for the agent
            "context": "string", // Background context to guide the agent
            "instructions": "string" // Operating instructions for the agent
          },
          "strategy": { // Reasoning strategy configuration
            "id": "string", // Strategy unique identifier (GUID)
            "name": "string", // Strategy human-readable name
            "systemPrompt": "string" // System prompt used to guide reasoning
          }
        },
        "chatSharingPermissions": "string", // Chat sharing policy: "none" | "organization" | "everybody"
        "description": "string", // Human-readable description of the agent
        "externalExecutionPermissions": "string", // Who can execute the agent externally: "none" | "organization" | "everybody"
        "id": "string", // Agent unique identifier (GUID)
        "importIndex": integer, // Import ordering index within the package
        "jobDescription": "string", // Short role/mission for the agent
        "name": "string", // Agent name (unique per project)
        "resources": [ // Resource pools and attached tools
          {
            "isExternal": boolean, // When true, tools are not validated by the platform
            "name": "string", // Resource pool name
            "tools": [ // Tools available in this resource pool
              {
                "id": "string", // Tool unique identifier (GUID)
                "name": "string", // Tool name
                "revision": integer, // Tool revision number
                "version": integer // Tool version number
              }
            ]
          }
        ],
        "version": integer // Agent version within the package
      }
    ],
    "info": { // Package metadata
      "majorVersion": integer, // Major version of the lab package format
      "minorVersion": integer, // Minor version of the lab package format
      "moduleRevision": integer, // Package module revision number
      "organizationId": "string", // Organization GUID
      "projectId": "string", // Project GUID
      "timestamp": "string" // ISO 8601 timestamp when the package was generated
    },
    "tools": [ // Tool definitions referenced by the package
      {
        "accessScope": "string", // Tool access scope: "private" | "public"
        "description": "string", // Human-readable description of the tool
        "id": "string", // Tool unique identifier (GUID)
        "isReference": boolean, // True if this is a reference to an external tool definition
        "name": "string", // Internal tool name
        "publicName": "string", // Global public identifier (e.g., "com.globant.geai.web_search")
        "type": "string", // Tool type (e.g., "api")
        "version": integer // Tool version
      }
    ]
  }
}

cURL Sample

curl -X GET "$BASE_URL/v2/agents/{IdOrName}/export" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json"

POST /v2/agents/import

Imports one or more Agents, Tools, Tool Plugins, and Tool Groups from a labPackage. Existing entities may be updated; new ones are created as needed. Import behavior aims to preserve relationships across Agents, Tools, Tool Plugins, and Tool Groups.

Method and URL

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

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/import

Request Body

{
  "labPackage": {                                     // Import package
    "agents": [                                       // One or more Agents to import
      {
        "sharingScope": "string",                     // "organization" | "public" | "private"
        "accessScope": "string",                      // "private" | "public"
        "agentData": {
          "models": [
            {
              "LLMConfig": {                          // Model-level LLM configuration
                "maxTokens": integer,                 // e.g., 2048
                "sampling": {
                  "temperature": number               // e.g., 0.1
                }
              },
              "id": "string",                         // Model ID (UUID in the target project)
              "name": "string"                        // Model name (e.g., "gemini-2.0-flash")
            }
          ],
          "prompt": {
            "context": "string",                      // Optional prompt context
            "examples": [
              { "inputData": "string", "output": "string" } // Few-shot examples
            ],
            "instructions": "string"                  // Main instructions for the Agent
          },
          "strategy": {
            "id": "string",                           // Strategy ID (UUID)
            "name": "string",                         // Strategy name (e.g., "Chain of Thought")
            "systemPrompt": "string"                  // System prompt used by the strategy
          }
        },
        "description": "string",                      // Human-readable description
        "id": "string",                               // Source Agent ID (UUID)
        "importIndex": integer,                       // Import order within the package
        "jobDescription": "string",                   // Short role description
        "name": "string",                             // Agent name
        "version": integer                            // Version from source package
      }
    ],
    "info": {                                         // Package metadata
      "majorVersion": integer,
      "minorVersion": integer,
      "moduleRevision": integer,
      "organizationId": "string",                     // Source organization (UUID)
      "projectId": "string",                          // Source project (UUID)
      "timestamp": "string"                           // ISO-8601 timestamp
    }
  }
}

Response

{
  "accessScope": "string",                             // "private" | "public"
  "agentData": {
    "llmConfig": {                                     // Effective agent-level LLM config (if any)
      "maxTokens": integer,                            // Optional in response
      "sampling": { "temperature": number },           // Optional in response
      "timeout": integer                               // Optional in response
    },
    "models": [
      {
        "llmConfig": {                                 // Effective model-level config
          "maxTokens": integer,
          "sampling": { "temperature": number }
        },
        "name": "string"                               // Model name used by the Agent
      }
    ],
    "prompt": {
      "context": "string",
      "examples": [ { "inputData": "string", "output": "string" } ],
      "instructions": "string"
    },
    "strategyId": "string",                            // Strategy ID (UUID)
    "strategyName": "string"                           // Strategy name or ID (per implementation)
  },
  "description": "string",
  "id": "string",                                      // Imported Agent ID (UUID) in target project
  "isDraft": boolean,                                  // true if not automatically published
  "jobDescription": "string",
  "name": "string",
  "revision": integer,                                 // Created revision
  "sharingScope": "string",                            // "organization" | "public" | "private"
  "status": "string",                                  // "active" | "inactive"
  "version": integer
}

cURL Sample

curl --request POST \
  --url '$BASE_URL/v2/agents/import?automaticPublish=true' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer $GEAI_APITOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "labPackage": {
    "agents": [
      {
        "sharingScope": "organization",
        "accessScope": "private",
        "agentData": {
          "models": [
            {
              "LLMConfig": {
                "maxTokens": 2048,
                "sampling": { "temperature": 0.1 }
              },
              "id": "4c0c02e6-18d5-4103-8077-f611afd536db",
              "name": "gemini-2.0-flash"
            }
          ],
          "prompt": {
            "context": "test",
            "examples": [{ "inputData": "test", "output": "test" }],
            "instructions": "test"
          },
          "strategy": {
            "id": "0a3b039e-25bd-4cf9-ad67-7af2b654874b",
            "name": "Chain of Thought",
            "systemPrompt": "..."
          }
        },
        "description": "Test agent",
        "id": "e97f0029-09b9-4721-85de-b35e737767c4",
        "importIndex": 1,
        "jobDescription": "test agent",
        "name": "Test",
        "version": 1
      }
    ],
    "info": {
      "majorVersion": 1,
      "minorVersion": 1,
      "moduleRevision": 28,
      "organizationId": "58227120-b3d1-42ab-88c4-68a5ff7aac50",
      "projectId": "224bc85e-7ab4-4c9a-af1a-588b4c0fb140",
      "timestamp": "2025-06-10T14:28:50.022"
    }
  }
}'

DELETE /v4/agents/{idOrName}/drafts/{revision}

Deletes the last draft created for an Agent, enabling users to undo their latest changes incrementally.

Request

  • Method: DELETE
  • Path: $BASE_URL/v4/agents/{idOrName}/drafts/{revision}
  • Body: Empty

Response

On success, the service typically responds with no content.

  • Success:
  • Status: 204 No Content

  • Body: None

  • Error (sample):

{
  "error": {
    "code": "string",            // Machine-readable error code
    "message": "string",         // Human-readable error description
    "details": "string"          // Optional additional information
  },
  "requestId": "string"          // Correlation ID for troubleshooting
}

Sample cURL

curl --request DELETE \
  --url "$BASE_URL/v4/{idOrName}/drafts/{revision}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $GEAI_APITOKEN"

GET /v4/agents/{idOrName}/versions

Retrieves the paginated list of versions for a given Agent. Each item represents a distinct version with metadata such as author, creation timestamp, deprecation flag, sequential number, and revision identifier.

Request

-Method GET - Path: $BASE_URL/v4/agents/{idOrName}/versions - Body: Empty.

Response

{
  "information": {
    "duration": integer,      // Server-side processing duration (units as provided by the server)
    "page": integer,          // Current page number (1-based)
    "pageSize": integer,      // Number of items returned per page
    "total": integer          // Total number of versions available
  },
  "items": [
    {
      "author": "string",     // Display name of the user who created the version
      "createdAt": "string",  // ISO 8601 date-time when the version was created
      "isDeprecated": boolean,// True if the version is marked as deprecated
      "number": integer,      // Sequential version number
      "revisionId": integer   // Internal revision identifier for this version
    }
  ]
}

Sample cURL

curl --request GET \
  --url "$BASE_URL/v4/agents/{idOrName}/versions" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $GEAI_APITOKEN"

POST /v4/agents/{idOrName}/revert

Reverts an Agent to a specified target revisionwhen managing agent version and it restore a previous revision or version. The response returns the Agent’s current definition after the revert operation.

Request

  • Method: POST
  • URL: $BASE_URL/v4/agents/{idOrName}/revert

Request Body

{
  "targetType": "string", // Revert target kind. Supported: "revision", "version"
  "targetId": integer     // The target revision identifier to revert to (e.g., a value from items[].revisionId)
}

Response

{
  "accessScope": "string",                 // "private" | "public"
  "agentData": {
    "llmConfig": {
      "maxRuns": integer,                 // Maximum tool/step runs allowed per execution
      "maxTokens": integer,               // Maximum tokens per model response
      "sampling": {
        "temperature": number             // Sampling temperature for the model
      }
    },
    "models": [
      {
        "name": "string"                  // Model identifier (e.g., "openai/gpt-4.1")
      }
    ],
    "prompt": {
      "context": "string",                // System/role context for the Agent
      "examples": [
        {
          "inputData": "string",          // Example input demonstrating expected usage
          "output": "string"              // Expected output corresponding to the example input
        }
      ],
      "instructions": "string"            // Operational instructions and behavior guidelines
    },
    "properties": [
      {
        "dataType": "string",             // Data type of the property value (e.g., "String")
        "key": "string",                  // Property key (arbitrary metadata key)
        "value": "string"                 // Property value (arbitrary metadata value)
      }
    ],
    "resourcePools": [
      {
        "name": "string"                  // Resource pool name
      }
    ],
    "strategyName": "string"              // Reasoning strategy identifier or UUID
  },
  "description": "string",                // Human-readable Agent description
  "effectivePermissions": {
    "chatSharing": "string",              // Effective chat sharing scope (e.g., "none")
    "externalExecution": "string"         // Effective external execution scope (e.g., "organization")
  },
  "id": "string",                         // Agent GUID
  "isDraft": boolean,                     // True if reverted Agent is in draft state
  "jobDescription": "string",             // Short role description
  "name": "string",                       // Agent name (unique within the project)
  "permissions": {
    "chatSharing": "string",              // Configured chat sharing scope
    "externalExecution": "string"         // Configured external execution scope
  },
  "revision": integer,                    // Current revision number after revert
  "status": "string",                     // Agent lifecycle status (e.g., "active" | "inactive")
  "version": integer                      // Current semantic version number after revert
}

cURL Sample

curl --request POST \
  --url "$BASE_URL/v4/agents/{idOrName}/revert" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $GEAI_APITOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "targetType": "revision",
    "targetId": 2
  }'

POST /v4/agents/{idOrName}/versions/{versionNumber}/deprecate

Deprecates the specified version of an Agent. After deprecation, the version remains in the history but is flagged as deprecated.

Request

  • Method: POST
  • Path: $BASE_URL/v4/agents/{idOrName}/versions/{versionNumber}/deprecate
  • Body: Empty

Response

A successful response returns the version resource marked as deprecated. Some environments may return 204 No Content.

Sample cURL

curl --request POST \
  --url "$BASE_URL/v4/agents/{idOrName/versions/{versionId}/deprecate" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $GEAI_APITOKEN"

PUT /agents/{idOrName}/versions/{versionNumber}

Updates the specified Agent version’s metadata.

Request

  • Method: PUT
  • Path: $BASE_URL/v4/agents/{idOrName}/versions/{versionNumber}

Request Body

{
  "versionInfo": {
    "name": "string"  // Human-readable display name for this version (e.g., "version 4")
  }
}

Response

{
  "agentId": "string",      // Agent GUID the version belongs to
  "author": "string",       // Identifier of the user who performed or owns the version (e.g., user GUID)
  "createdAt": "string",    // ISO 8601 timestamp when the version was created
  "revision": integer,      // Internal revision number associated with this version state
  "version": integer,       // Version number
  "versionName": "string"   // Display name for the version (as updated)
}

cURL Sample

curl --request PUT \
  --url "$BASE_URL/v4/agents/{idOrName}/versions/{versionNumber}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $GEAI_APITOKEN" \
  --data '{
    "versionInfo": {
      "name": "version 4"
    }
  }'

GET /v4/agents/{idOrName}/drafts

Retrieves the paginated list of draft revisions for a given Agent. The endpoint supports offset-based pagination using start and count. The response provides computed pagination metadata as page/pageSize/total for convenience.

Parameters

Name Type Description
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.

Request

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

Response

{
  "information": {
    "duration": integer,     // Server-side processing duration (units as provided by the server)
    "page": integer,         // Current page number derived from start/count
    "pageSize": integer,     // Number of items per page (reflects 'count')
    "total": integer         // Total number of draft revisions available
  },
  "items": [
    {
      "createdAt": "string", // ISO 8601 date-time when the draft revision was created
      "isDeprecated": boolean, // True if this draft revision is flagged as deprecated
      "number": integer,     // Version number associated with this draft revision
      "revisionId": integer  // Internal revision identifier of the draft
    }
  ]
}

Sample cURL

curl --request GET \
  --url "$BASE_URL/v4/agents/{idOrName}/drafts?count=10&start=1" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $GEAI_APITOKEN"

GET /v4/agents/{idOrName}/export

Exports the specified Agent as a Lab Package (JSON) that contains the Agent definition and export metadata.

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.

Request

  • Method: GET
  • Path: $BASE_URL/v4/agents/{idOrName}/export
  • Body: empty

Response

{
  "labPackage": {                                   // Root container for the exported package
    "agents": [                                    // List of exported Agents (typically one)
      {
        "accessScope": "string",                    // "private" | "public"
        "agentData": {                              // Core Agent configuration
          "LLMConfig": {                            // LLM execution settings
            "maxRuns": integer,                     // Maximum tool/step runs per execution
            "maxTokens": integer,                   // Maximum tokens per response
            "sampling": {
              "temperature": number                 // Sampling temperature (0.0–2.0)
            }
          },
          "models": [                               // Preferred models for the Agent
            {
              "id": "string",                       // Model unique identifier
              "name": "string"                      // Provider/model name (e.g., "openai/gpt-4.1")
            }
          ],
          "prompt": {                               // Prompt design and examples
            "context": "string",                    // High-level role/context for the Agent
            "examples": [                           // Few-shot examples
              {
                "inputData": "string",              // Example input content
                "output": "string"                  // Expected output for the example
              }
            ],
            "instructions": "string"                // Detailed instructions/operating procedure
          },
          "strategy": {                             // Reasoning strategy configuration
            "id": "string",                         // Strategy unique identifier
            "name": "string",                       // Strategy name (e.g., "Chain of Thought")
            "systemPrompt": "string"                // System-level guidance for reasoning steps
          }
        },
        "chatSharingPermissions": "string",         // "none" | "organization" | "everybody"
        "description": "string",                    // Human-readable Agent description
        "externalExecutionPermissions": "string",   // Who can execute externally: "none" | "organization" | "everybody"
        "id": "string",                             // Agent GUID
        "importIndex": integer,                     // Import ordering index within the package
        "jobDescription": "string",                 // Short role/job description
        "name": "string",                           // Agent name
        "resources": [                              // Resource pools linked to the Agent
          {
            "isExternal": boolean,                  // When true, tools/resources are external and not validated
            "name": "string"                        // Resource pool name
          }
        ],
        "version": integer                          // Agent major version
      }
    ],
    "info": {                                       // Export metadata
      "majorVersion": integer,                      // Lab package major version
      "minorVersion": integer,                      // Lab package minor version
      "moduleRevision": integer,                    // Internal revision of the export module
      "organizationId": "string",                   // Organization GUID
      "projectId": "string",                        // Project GUID
      "timestamp": "string"                         // ISO 8601 export timestamp (e.g., "2026-05-20T18:59:59.304Z")
    }
  }
}

Sample cURL

curl --request GET \
  --url "$BASE_URL/v4/agents/$AGENT_ID_OR_NAME/export?version=1&revision=2" \
  --header "accept: application/json" \
  --header "authorization: Bearer $GEAI_APITOKEN"
—
Last update: 8 June 2026 by lmigone
Last update: 2026 | © Globant S.A. All rights reserved.