# Consume an Agent via API

Consuming an Agent refers to the process of calling or using the Agent to perform a desired action or provide a particular functionality. In this context, it means utilizing an API to access a trained Document AI model to classify documents, extract information from them or consume as a use case.
Once the agent is created and published, you will be able to invoke the agent using API.

This guide will walk you through the below steps on how to invoke your agents using an API.

1. Activate the Agent
2. Download the API documentation
3. Execute an APIthrough API

• Once an agent is published, it can be activated in the Governance module. If the agent is in the deactivated state and when trying to use the agent via API, you will get an error stating that the agent is not activated
• Agents can be activated / deactivated anytime. When it is deactivated, the transactions initiated already will not be suspended until it is completed
• You can view the detailed steps to activate an agent here

API documentation has the necessary information and structure of how an agent can be invoked. Every agent will have a different API definition. Details on the API endpoints and parameters are dynamically generated and will be available in the API documentation.
You can download the API documentation by following the below steps:

1. In the Agent Expert Studio page, click on the three dots against the agent which you would like to use and select the Download API option. The agent API gets downloaded

   Note:
   You can download the API documentation for the published agents only.

2. The Open API specification JSON file will be downloaded to your system

API documentation

• The generated API documentation (REST API) is OpenAPI 3.0 specification compliant
• Each agent and its version will have a different API endpoint
• Each API’s definition and endpoints are versioned

Authentication

• Only valid users with proper access can use (Invoke) an agent via API
• API keys need to be passed as part of each and every API call. Only requests with valid API keys will be allowed to process
• We use JSON Web Token (JWT) for authorization of API requests

End points
There are 3 API endpoints in the API documentation:

• End Point 1: Get Authenticated
• End Point 2: Invoke the agent
• End Point 3: Get the status and result

End point 1: Get authenticated

1. The first endpoint is for Authentication.
2. Once the request is successful, the response will be a valid JWT token.
3. This access token comes with default expiry time which can be configured at the tenant level.
4. You need to send this access token first to get the access from the agent API to do the GET and POST operations.
5. To agent Token access you need to setup the following:
   • Request: GET
   • Service URL : accesstoken/idx
6. Go to Headers and update the following:

7. Enter the API key (replace this with the actual value of the api key); for each and every tenant, a unique API key is provided
8. In username & password, enter your login credentials

End point 2: Invoke the agent

1. The second endpoint is for executing (invoke) the agent
   Once the request is successful, the response will have a trace_id
2. To execute the Invoke Agent API, go to Authorization tab
   1. In Type select Bearer Token
   2. In Token enter
3. Go to Headers and update the following:

• Enter the API key; for each and every tenant, a unique API key is provided

4. Go to Body tab,
   1. There are different types of input for some cases, and for some cases, no input is required; it all depends on the agent the user creates
      1. Input_file – upload the file from your local storage
      2. S3_file_path – provide the file/folder path from the AWS S3 bucket
      3. No Input – in some cases no input required to execute the agent
5. After the successful execution the response is as follows
   {
   "trace_id": "<GENERATED_TRACE_ID>",
   "message": "agent Invoked Successfully"
   }

End point 3: Get the status and results

1. The third endpoint is for getting the status and output of the invoked agent
2. Once the request is successful, the final output
3. To execute the Invoke agent API, go to the Authorization tab
   1. In Type select Bearer Token
   2. In Token enter
4. Go to Headers and update the following

• Enter the API key (replace this with the actual value of the api key); for each and every tenant, a unique API key is provided.

5. Go to the Params tab
   1. Provide the value for path variable trace_id, the value of the trace_id is the response of the invoke agent api
   2. After the successful execution of this API, the response is the result of the executed agent

• The API returns exceptions in the HTTP response body when something * The API returns exceptions in the HTTP response body when something

Invoking an agent API through curl
cuRL Request to generate the Access token

curl –location –request GET ‘https://api.intellectai.com/accesstoken/<YOUR_TENANT_ID>‘ \

    — header ‘apikey: <YOUR_API_KEY>‘ \

    — header ‘username: <YOUR_USER_NAME>‘ \       –header ‘password: <YOUR_PASSWORD>‘

cuRL Request to invoke the Agent with INPUT

    curl --location --request POST 'https://api.intellectai.com/magicplatform/v1/invokeagent/<YOUR_AGENT_VERSION_ID>/extract' \

    --header 'apikey: <YOUR_API_KEY>' \

    --header 'Content-Type: multipart/form-data' \

    --header 'Accept: application/json' \

    --header 'Authorization: Bearer <YOUR_GENERATED_TOKEN>' \

    --form 'input_file=@"<FILE_LOCATION>"'

cuRL Request to invoke the Agent with INPUT

    curl --location --request POST 'https://api.intellectai.com/magicplatform/v1/invokeagent/<YOUR_AGENT_VERSION_ID>/extract' \

    --header 'apikey: <YOUR_API_KEY>' \

    --header 'Content-Type: multipart/form-data' \

    --header 'Accept: application/json' \

    --header 'Authorization: Bearer <YOUR_GENERATED_TOKEN>' \

    --form 'input_file=@"<FILE_LOCATION>"'

cuRL Request to invoke the agent without INPUT

    curl --location --request POST 'https://api.intellectseecstag.com/magicplatform/v1/invokeagent/<YOUR_AGENT_VERSION_ID>/usecase' \

    --header 'apikey: <YOUR_API_KEY>' \

    --header 'Content-Type: application/json' \

    --header 'Accept: application/json' \

    --header 'Authorization: Bearer <YOUR_GENERATED_TOKEN> ' \

    --data-raw '{}'

cuRL Request to get the status of an agent

    curl --location --request 'https://api.intellectai.com//magicplatform/v1/invokeagent/50d6e176-7837-44ef-8564-7847e5170f33/< trace_id >' \

    --header 'apikey: < YOUR_API_KEY >' \

    --header 'Accept: application/json' \--header 'Authorization: Bearer <YOUR_GENERATED_TOKEN>'

Code examples
Java

    static HttpResponse<String> getData(String jsonStr, String endpoint, String accessToken)
    throws Exception {
        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest httpRequest = HttpRequest.newBuilder()
        .method("GET", body)
        .header("apikey", "<< apikey >>")
        .header("username", "<< username >>")
        .header("password", "<< password >>")
    .uri(URI.create("https://api.intellectai.com/accesstoken/<YOUR_TENANT_ID>”))
        .build();
    HttpResponse<String> httpResponse = httpClient.send(httpRequest,                       HttpResponse.BodyHandlers.ofString());
    }

Python

    import http.client
    conn = http.client.HTTPSConnection("api.intellectai.com")
    payload = ''
    headers = {
    'apikey': '<< apikey >>',
    'username': '<<  username  >>',
    'password': '<< password >>'
    }
    conn.request("GET", "//accesstoken/<YOUR_TENANT_ID>", payload, headers)
    res = conn.getresponse()
    data = res.read()
    print(data.decode("utf-8"))

Node Js

    var axios = require('axios');
    var config = {
    method: 'get',
    url: 'https://api.intellectai.com//accesstoken/<YOUR_TENANT_ID>,
    headers: { 
    'apikey': '<< apikey >>', 
    'username': '<<  username  >>', 
    'password': '<< password >>'
    }
    };
    axios(config)
    .then(function (response) {
    console.log(JSON.stringify(response.data));
    })
    .catch(function (error) {
    console.log(error);
    });

Possible errors and exceptions

• The API returns exceptions in the HTTP response body when something goes wrong
• Possible Error Codes
  • OK – 200
  • CREATED – 201
  • ACCEPTED – 202
  • BAD_REQUEST – 400
  • UNAUTHORIZED – 401
  • FORBIDDEN – 403
  • NOT_FOUND – 404
  • NOT_ACCEPTABLE – 406
  • CONFLICT – 409
  • LENGTH_REQUIRED – 411
  • INTERNAL_SERVER_ERROR – 500

Example
Here is a simple 404

    {  
    "statusCode": 404,  
    "message": "Agent not found",  
    "error": "Not Found"  
    }

UnAuthorized Request 401

    {  
    "statusCode": 401,  
    "message": "Not Authorized.",  
    "error": "Unauthorized"  
    }