AI Agent API

This endpoint group provides methods for interacting with AI agents, including sending messages, managing chat history, retrieving agent configurations, and handling file attachments for agent interactions.

Endpoints

POST /api/rpc (Method: AiRpc.sendMessage)

• Description: Sends a message to an AI agent, optionally with file attachments.

• Request Body:

  {
    "method": "AiRpc.sendMessage",
    "params": {
      "agentName": "myAgent",
      "message": "Hello, agent!",
      "attachments": [
        {
          "fileId": "some-uuid-1",
          "fileName": "document.pdf",
          "mimeType": "application/pdf"
        }
      ]
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	Name of the agent to send the message to.
  message	String	Yes	Message content.
  attachments	Array<Object>	No	An array of file references uploaded by the client. Each object contains fileId (String), fileName (String), and mimeType (String).

• Response:

  {
    "success": true,
    "data": {
      "success": true,
      "message": "Message queued for processing."
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.sendMessage",
      "params": {
        "agentName": "myAgent",
        "message": "Hello, AI agent!"
      }
    }'

POST /api/rpc (Method: AiRpc.cancelProcessing)

• Description: Cancels any ongoing processing for an AI agent.

• Request Body:

  {
    "method": "AiRpc.cancelProcessing",
    "params": {
      "agentName": "myAgent"
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	Name of the agent whose task should be cancelled.

• Response:

  {
    "success": true,
    "data": {
      "success": true,
      "message": "Cancellation signal sent to myAgent."
    }
  }

  Or, if the agent is not found or does not support cancellation:

  {
    "success": true,
    "data": {
      "success": false,
      "message": "Agent not found or does not support cancellation."
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.cancelProcessing",
      "params": {
        "agentName": "myAgent"
      }
    }'

POST /api/rpc (Method: AiRpc.getAgentConfig)

• Description: Retrieves the public configuration for a specific AI agent, including model capabilities.

• Request Body:

  {
    "method": "AiRpc.getAgentConfig",
    "params": {
      "agentName": "myAgent"
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	Name of the agent to get the configuration for.

• Response:

  {
    "success": true,
    "data": {
      "name": "myAgent",
      "description": "A helpful AI assistant.",
      "avatarUrl": "https://example.com/avatar.png",
      "model": "gpt-4",
      "modelSettings": {
        "temperature": 0.7
      },
      "messagingContactId": "contact-id-123",
      "identityId": "agent-identity-456"
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.getAgentConfig",
      "params": {
        "agentName": "myAgent"
      }
    }'

POST /api/rpc (Method: AiRpc.getChatHistory)

• Description: Retrieves the chat history for an AI agent.

• Request Body:

  {
    "method": "AiRpc.getChatHistory",
    "params": {
      "agentName": "myAgent"
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	Name of the agent to get chat history from.

• Response:

  {
    "success": true,
    "data": [
      {
        "role": "user",
        "content": "Hello!"
      },
      {
        "role": "agent",
        "content": "How can I help you?"
      }
    ]
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.getChatHistory",
      "params": {
        "agentName": "myAgent"
      }
    }'

POST /api/rpc (Method: AiRpc.clearChatHistory)

• Description: Clears the chat history for an AI agent.

• Request Body:

  {
    "method": "AiRpc.clearChatHistory",
    "params": {
      "agentName": "myAgent"
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	Name of the agent to clear chat history for.

• Response:

  {
    "success": true,
    "data": {
      "success": true
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.clearChatHistory",
      "params": {
        "agentName": "myAgent"
      }
    }'

POST /api/rpc (Method: AiRpc.getAttachmentUploadKey)

• Description: Gets a secure upload key for attaching files to a message for a specific agent. This key is used with the UploadDownloadService to initiate file uploads.

• Request Body:

  {
    "method": "AiRpc.getAttachmentUploadKey",
    "params": {
      "agentName": "myAgent"
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	The agent the files are intended for.

• Response:

  {
    "success": true,
    "data": {
      "key": "some-uuid-upload-key",
      "server": "https://api.example.com",
      "url": "/upload/some-uuid-upload-key"
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.getAttachmentUploadKey",
      "params": {
        "agentName": "myAgent"
      }
    }'

POST /api/rpc (Method: AiRpc.getAttachmentDownloadKey)

• Description: Gets a persistent, session-scoped download key for viewing chat attachments. This key is used with the UploadDownloadService to download files.

• Request Body:

  {
    "method": "AiRpc.getAttachmentDownloadKey",
    "params": {}
  }

• Parameters:

  Name	Type	Required	Description
  (None)

• Response:

  {
    "success": true,
    "data": {
      "key": "some-uuid-download-key",
      "server": "https://api.example.com",
      "url": "/download/some-uuid-download-key"
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.getAttachmentDownloadKey",
      "params": {}
    }'

POST /api/rpc (Method: AiRpc.finalizeAttachments)

• Description: Finalizes uploaded files associated with an upload key, moving them to their persistent location for an agent. This method should be called after files have been successfully uploaded using the key obtained from getAttachmentUploadKey and the UploadDownloadService.

• Request Body:

  {
    "method": "AiRpc.finalizeAttachments",
    "params": {
      "agentName": "myAgent",
      "uploadKey": "some-uuid-upload-key"
    }
  }

• Parameters:

  Name	Type	Required	Description
  agentName	String	Yes	The agent these files are being prepared for.
  uploadKey	String	Yes	The upload key returned by getAttachmentUploadKey.

• Response:

  {
    "success": true,
    "data": {
      "success": true,
      "files": [
        {
          "filePath": "chat/agent-history-123/document.pdf",
          "fileId": "some-file-uuid-1",
          "fileName": "document.pdf",
          "fileType": "application/pdf",
          "size": 102400
        }
      ]
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "AiRpc.finalizeAttachments",
      "params": {
        "agentName": "myAgent",
        "uploadKey": "some-uuid-upload-key"
      }
    }'