InvokeEsAgent

1. session/new - Create a session

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {}
}

Pass an empty object for params. The data.result.sessionId in the response is used for all subsequent requests.

2. session/list - Session list

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "session/list",
  "params": {},
  "pageNum": 1,
  "pageSize": 10
}

Parameter	Location	Required	Description
pageNum	Top level	No	The page number. The default value is processed by the server.
pageSize	Top level	No	The number of entries per page. The default value is processed by the server.

3. session/prompt - Send a message (SSE streaming)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "863d643f-dadd-40ea-9399-1aef3aea11fe",
    "prompt": [
      {
        "type": "text",
        "role": "user",
        "text": "Hello, what are you good at?"
      }
    ],
    "_meta": {
      "agentMode": "AGENTSWARM",
      "enableThinking": false
    }
  }
}

Parameter description of params._meta:

Parameter	Type	Required	Description
enableThinking	boolean	No	Specifies whether to enable deep thinking mode.
agentMode	string	No	The agent pattern. Valid values: CHAT (default) and AGENTSWARM.

Parameter description of params.prompt:

Parameter	Type	Required	Description
type	String	Yes	The content type. Valid values: text, file, and image.
text	String	Required for the text type	The text content.
url	String	Required for the file or image type	The URL of the file or image.

4. session/load - Resume a session from a breakpoint

Request example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/load",
  "params": {
    "sessionId": "b32ee663-b231-4676-a628-f2d9dd7c951e",
    "_meta": {
      "requestCode": "e4bcb48f-0abd-428c-980c-ab7619e36c10",
      "isReload": true,
      "beginLogOffset": 0
    }
  }
}

Parameter description of params._meta:

Parameter	Type	Required	Description
isReload	boolean	No	Specifies whether to use the breakpoint resumption pattern. Fixed to true.
requestCode	string	No	The conversation ID, which is the _meta.chatId of the SSE event. If this parameter is not passed, the server attempts to find the active node under the current session.
beginLogOffset	integer	No	The log offset from which to continue reading. Default value: 0.

5. session/cancel - Cancel a node

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "session/cancel",
  "params": {
    "sessionId": "3c7c879c-bfdf-4011-b5c8-72f58466af7e"
  }
}

Parameter description of params:

Parameter	Type	Required	Description
sessionId	String	Yes	The session ID.

6. session/delete - Delete a session

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "session/delete",
  "params": {
    "sessionId": "3c7c879c-bfdf-4011-b5c8-72f58466af7e"
  }
}

Parameter description of params:

Parameter	Type	Required	Description
sessionId	String	Yes	The session ID.

7. session/hitlRespond - HITL user response

When the SSE stream of session/prompt receives sessionUpdate=hitl_question, the invoker must display the question and commit the user's response through this operation.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/hitlRespond",
  "params": {
    "sessionId": "sess_hitl_verify_1778467117",
    "requestId": "",
    "responseText": "I choose artificial intelligence and machine learning",
    "selectedOption": "Artificial intelligence and machine learning"
  }
}

Parameter description of params:

Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
requestId	string	No	The HITL request ID. This parameter can be empty. The system automatically finds the currently active HITL request.
responseText	string	No	The text content of the user's response.
selectedOption	string	No	The option selected by the user. Pass the label value of the option.

You must provide at least one of responseText and selectedOption.

Response modes

The response format depends on the called ACP method:

Method	Content-Type	Response format
session/prompt and session/load	text/event-stream; charset=utf-8	SSE event stream
Other methods	application/json	Standard JSON response

Standard JSON response examples.

session/new

{
  "code": 200,
  "data": {
    "result": {
      "models": null,
      "modes": null,
      "sessionId": "8246b4d9-88f3-4a93-80b7-0c242f0ddbb8"
    },
    "requestId": "1df6d614-96db-41bd-b8b6-ab061a1724ca",
    "id": "1",
    "jsonrpc": "2.0",
    "timestamp": 1782723585411
  },
  "requestId": "1df6d614-96db-41bd-b8b6-ab061a1724ca",
  "message": null
}

The data.result.sessionId is used for all subsequent requests.

session/list

{
  "requestId": "598b5734-6dbe-4b04-9c17-4cdf99d58b85",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "598b5734-6dbe-4b04-9c17-4cdf99d58b85",
    "timestamp": 1774494136385,
    "jsonrpc": "2.0",
    "id": "1774339902987004",
    "result": {
      "sessions": [
        {
          "userId": "test_user_doc",
          "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
          "title": "Hello",
          "description": null,
          "createdAt": 1774493075150,
          "updatedAt": 1774493094825,
          "_meta": {
            "sessionSource": "CHAT_BI",
            "agentName": "chat_cli_chatbi",
            "type": "ACP_AGENT",
            "status": "RELEASED",
            "chatCount": 1
          }
        }
      ],
      "nextCursor": null,
      "total": 1
    }
  }
}

Valid values for sessions[]._meta.status:

Value	Description
RUNNING	The session is in progress.
RELEASED	The session has ended.

session/cancel

{
  "code": 200,
  "data": {
    "result": {
      "success": true,
      "cancelledCount": 1,
      "totalActive": 1,
      "message": "The cancellation request has been sent, and 1 task has been canceled."
    },
    "requestId": "9e3c0189-3673-4f3b-8864-1e47915781a2",
    "id": "9",
    "jsonrpc": "2.0",
    "timestamp": 1782720975482
  },
  "requestId": "9e3c0189-3673-4f3b-8864-1e47915781a2",
  "message": null
}

• cancelledCount: The actual number of canceled tasks.

• totalActive: The number of active tasks in the session.

session/delete

{
  "code": 200,
  "data": {
    "result": {
      "success": true,
      "sessionId": "3c7c879c-bfdf-4011-b5c8-72f58466af7e",
      "message": "The session is deleted."
    },
    "requestId": "ac753513-db17-492a-9c4f-7be17f95122c",
    "id": "14",
    "jsonrpc": "2.0",
    "timestamp": 1782721288151
  },
  "requestId": "ac753513-db17-492a-9c4f-7be17f95122c",
  "message": null
}

session/hitlRespond

{
  "requestId": "578ccdae-e0df-490d-b49c-313e94c08c02",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "578ccdae-e0df-490d-b49c-313e94c08c02",
    "timestamp": 1778467232264,
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
      "status": "accepted"
    }
  }
}

SSE streaming responses (session/prompt and session/load)

The response is an SSE event stream. The format of each event is data: {JSON}\n\n.

Event structure

{
  "requestId": "<uuid>",
  "timestamp": 1774493075579,
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "<session-id>",
    "update": {
      "sessionUpdate": "<event-type>",
      "content": { "type": "text", "text": "<content>" }
    },
    "_meta": { }
  }
}

sessionUpdate event types

Type	Description
task_status	The task status changes (created -> in_progress -> completed).
agent_message_start	The message starts.
agent_message_chunk	The message chunk from the agent (incremental).
agent_message	The complete message from the agent.
user_message_chunk	The playback of the user message.
hitl_question	The agent asks the user a question (HITL).
hitl_response	The user has answered the HITL question, and the agent resumes execution.
task_complete	The task is completed.

The caller can ignore unlisted event types as needed.

Description of special fields in params._meta

Field	Description
status	The task status. Valid values: created, in_progress, and completed.
response_id	The response ID.
message_id	The message ID.
delta	A value of true indicates incremental content.
role	The message role (assistant).

Stream end markers

1. Receiving result.stopReason as end_turn indicates that the task ends normally.

2. Receiving data: [DONE] indicates that the SSE stream ends.

Complete event stream example

data: {"requestId":"...","method":"session/update","params":{"update":{"sessionUpdate":"task_status"},"_meta":{"status":"created"}}}

data: {"requestId":"...","method":"session/update","params":{"update":{"sessionUpdate":"task_status"},"_meta":{"status":"in_progress"}}}

data: {"requestId":"...","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_start"},"_meta":{"message_id":"msg_xxx","role":"assistant"}}}

data: {"requestId":"...","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Hello"}},"_meta":{"message_id":"msg_xxx","delta":true}}}

data: {"requestId":"...","method":"session/update","params":{"update":{"sessionUpdate":"agent_message","content":{"type":"text","text":"Hello! Complete response..."}},"_meta":{"message_id":"msg_xxx"}}}

data: {"requestId":"...","method":"session/update","params":{"update":{"sessionUpdate":"task_complete"},"_meta":{"status":"completed"}}}

data: {"requestId":"...","id":"...","result":{"stopReason":"end_turn"}}

data: [DONE]

HITL interactions.

hitl_question event format

{
  "requestId": "...",
  "timestamp": 1778467122742,
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_xxx",
    "update": {
      "sessionUpdate": "hitl_question",
      "questionId": "call_832fe77927734a598b5bbb40",
      "question": "Which IT field development direction are you most interested in?",
      "options": [
        { "label": "Artificial intelligence and machine learning", "description": "Artificial intelligence and machine learning" },
        { "label": "Cloud computing and DevOps", "description": "Cloud computing and DevOps" },
        { "label": "Cybersecurity and data protection", "description": "Cybersecurity and data protection" }
      ],
      "timeoutSeconds": 120
    },
    "_meta": {
      "hitlType": "question",
      "call_id": "call_832fe77927734a598b5bbb40",
      "nextLogOffset": 37
    }
  }
}

SSE events after HITL completion

After you submit a response through session/hitlRespond, the SSE stream of the original session/prompt continues to output the following events:

1. The hitl_response event, which confirms that the user has answered.

2. The agent resumes execution and outputs subsequent events such as agent_message_chunk.

3. task_complete, end_turn, and [DONE].