How to use an Agent with Corpus Semantic Similarity

This is a step-by-step guide to creating an Agent via API that retrieves information from a Corpus using the com.globant.geai.semanticsimilarity.retrieve Tool, which belongs to Semantic Similarity tools.

Once bound to a Corpus, the Agent calls the Corpus by semantic similarity automatically as part of its reasoning (the underlying tool call includes retrieve_post).

Using this Tool is the agentic equivalent of calling POST /v1/corpus/{CorpusId}/retrieve directly: instead of your application sending each retrieval request, you define the Corpus and the default retrieval settings once on the Agent, and the Agent decides when to retrieve information during the conversation.

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

Endpoints

Authentication

All endpoints require authentication using one of the following:

Authorization: Bearer $GEAI_APITOKEN
Authorization: Bearer $OAuth_accesstoken

For OAuth, include ProjectId: $GEAI_PROJECT_ID.

Requests with a JSON body also require Content-Type: application/json.

Step 1: Create an Agent with the Tool Bound to a Corpus

You pass the corpus binding and retrieval defaults as a JSON arguments string on the tool, inside a resource pool.

curl -X POST "$BASE_URL/v2/agents" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentDefinition": {
      "name": "corpus-test01",
      "accessScope": "private",
      "publicName": "com.genexus.geai.test01",
      "description": "Searches information stored in a corpus (vector database) via semantic similarity tools.",
      "jobDescription": "Get corpus related data",
      "agentData": {
        "models": [
          { "name": "openai/gpt-4.1", "llmConfig": { "maxTokens": 10000, "sampling": { "temperature": 0.1 } } }
        ],
        "prompt": {
          "context": "You are a helpful Agent with knowledge from a corpus of data.",
          "instructions": "You can search any information stored in the selected corpus."
        },
        "strategyName": "",
        "resourcePools": [
          {
            "name": "Main",
            "tools": [
              {
                "name": "com.globant.geai.semanticsimilarity.retrieve",
                "arguments": "{\"corpusId\":\"$CORPUS_ID\",\"scoreThreshold\":0.03,\"topK\":3}"
              }
            ]
          }
        ]
      }
    }
  }

The arguments JSON binds the corpus and the retrieval defaults for this Agent. Common shapes:

// minimal (corpus id + name from the corpus dropdown)
{ "corpusId": "{guid}", "name": "{name}" }

// with topK / scoreThreshold
{ "corpusId": "{guid}", "name": "{name}", "scoreThreshold": 0.03, "topK": 3 }

// with filters
{ "corpusId": "{guid}", "name": "{name}", "filters": [ { "key": "extension", "operator": "$eq", "value": "pdf" } ] }

// with rerank + filters + topK + scoreThreshold
{ "corpusId": "{guid}", "name": "{name}",
  "rerank": { "provider": "cohere", "modelName": "rerank-v3.5", "relevanceScore": 0.015, "k": 4 },
  "filters": [ { "key": "extension", "operator": "$eq", "value": "pdf" } ],
  "scoreThreshold": 0.03, "topK": 3
}

POST $BASE_URL/v2/agents is served by the Agent API and returns the Agent's name, version, and revision. Save these values for the chat call in the next step.

To update an existing Agent's tool binding, send a PUT request with the same agentDefinition to $BASE_URL/v2/agents/{idOrName}.

Step 2: Chat with the Agent

Send a request to the /chat endpoint, using the OpenAI-compatible format, with the Agent model id saia:agent:{name}:{version}:{revision}:

curl -X POST "$BASE_URL/chat" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "saia:agent:corpus-test01:$VERSION:$REVISION",
    "messages": [
      { "role": "user", "content": "anything about subject? detail the link sources where you found the information" }
    ]
  }'

The response is an OpenAI-style chat completion. You can find the answer in choices[0].message.content, and the corpus tool invocation appears under tool_calls (the function name includes retrieve_post).

Step 3: Delete the Agent

curl -X DELETE "$BASE_URL/v2/agents/{idOrName}" \
  -H "Authorization: Bearer $GEAI_APITOKEN"

Considerations

• Publishing / export. Publishing an Agent with a bound corpus is restricted. On export, the tool travels with the Agent, but corpus-specific references do not; you must recreate them in the destination Project.

Availability

Since version 2026-06.