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

The Agents 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 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).

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

json
{
  "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.

json
{
  "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

json
{
  "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.

json
{
  "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 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

json
{
  "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

json
{
  "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

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

Response

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

json
{
  "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

curl -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

json
{
  "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": [
          {
            "id": "string",                   // Tool unique identifier
            "name": "string"                  // Tool name
          }
        ]
      }
    ],
    "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 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

json
{
  "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

curl -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

json
{
  "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 --request GET \
  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":  "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":  "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":  "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"
    }
  }
}'
—
Last update: 20 February 2026 by rp
Last update: December 2025 | © GeneXus. All rights reserved. GeneXus Powered by Globant