Agent Execution API

Overview

The Agent Execution API allows clients to send requests to a specific agent and receive responses. It interacts with agents using contextual and user-specific data.

Endpoint

POST /api/agents/{agent_id}

Description

Executes an agent interaction using the provided input and user context.

Request Parameters

Parameter	Type	Description
agent_id	string	The unique identifier of the agent.

Request Body

{
  "org_id": "string",
  "user_id": "string",
  "agent_version_id": "string",
  "input": "string",
  "session_id": "string (optional)",
  "agent_call_id": "string (optional)",
  "user": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "avatar_url": "string (optional)"
  }
}

Request Body Fields

Field	Type	Description
org_id	string	The organization ID associated with the request.
user_id	string	The ID of the user making the request.
agent_version_id	string	The version of the agent to be used.
input	string	The user input message.
session_id	string (optional)	A session identifier to track conversations.
agent_call_id	string (optional)	A unique call identifier for the request.
user	object (optional)	User information, including ID, name, and email.

Response

{
  "answer": "string",
  "artifacts": "any",
  "success": "boolean"
}

Response Fields

Field	Type	Description
answer	string	The response message from the agent.
artifacts	any	Additional response data, such as screenshots or related artifacts.
success	boolean	Indicates whether the request was successfully processed.

Authentication

• TBD, needs valid user_id and org_id for now.

Example Request

curl -X POST "https://agents.higent.ai/api/agents/agt_xxx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "org_id": "org_001",
       "user_id": "user_123",
       "agent_version_id": "agtv_xxx",
       "input": "Send an email to John Doe",
     }'

Example Response

{
  "answer": "I have successfully retrieved a screenshot of the higent.ai website along with its title. The information is now ready to be presented to the user.",
  "artifacts": [
    {
      "artifact_id": "website.screenshot-4340c785",
      "description": "Screenshot of the website",
      "num_records": 1
    }
  ],
  "success": true
}