This guide documents the API standards required for custom Agents to integrate with the DuploCloud AI HelpDesk. By following these standards, your Agent can leverage HelpDesk features like Terminal command execution, browser interactions, and file operations.
Agent API Requirements
All custom Agents must expose a chat endpoint:
POST /api/sendMessage
This endpoint handles message exchanges between your Agent and Service Desk, supporting contextual information and specialized response types.
Request Format
Request from HelpDesk to Agent
The HelpDesk sends a flat array of messages where the last message is the current user request. All previous messages provide conversation context.
{"messages":[{"role":"user"|"assistant","content":"Message text content","platform_context":{// only for user messages},"data":{// Structured data exchanges},"timestamp":"2025-05-20T18:00:46.123456Z"}// ... more messages]}
Field Descriptions
messages (array, required)
Flat array of all conversation messages
Last element is the current message
Follows OpenAI/Anthropic conversation format
role (string, required)
"user": Message from user to Agent
"assistant": Message from Agent to user
content (string, required)
Human-readable message text
Empty string for pure approval/rejection messages
platform_context (object, only for user messages)
Environment-specific configuration and credentials
Set by HelpDesk
Example:
data (object, required)
Structured data for commands, URLs, and other actions
Contains cmds, executed_cmds, and url_configs arrays
timestamp (string, optional)
formatted timestamp
Response Format
Response from Agent to HelpDesk
Capability-Specific Formats
Terminal Commands
Agents can provide Terminal commands for user approval and execution through a human-in-the-loop workflow.
Command Proposal (Agent → User)
Command Fields
command (string, required)
The shell command to execute
execute (boolean, required)
false: Command proposed by Agent, awaiting approval
true: Command approved by user
files (array, optional)
Files to create before command execution
Each file object contains:
file_path: Relative path where file should be created
file_content: Content of the file
rejection_reason (string, optional in user response)
User's reason for rejecting a command (when execute=false)
Terminal Command Workflow
1. Agent Proposes Commands
Agent suggests commands with execute: false:
2. User Approves/Rejects Commands
When the user responds, they send back commands with updated execute status:
3. User can send Executed Commands to the agent
In the next request, the user can also share commands and outputs executed by him on his own in a shared user terminal to the agent:
4. Agent Analyzes and Responds
The agent can share the commands it executed to the user via the executed_cmds array.
User-Initiated Commands
Users can run their own terminal commands between agent messages. These appear in the next user message:
File Operations with Commands
For commands requiring file creation (e.g., Helm charts, configurations):
Browser Actions
Agents can direct users to web resources:
Complete Workflow Example
Here's a full conversation flow showing all capabilities:
Best Practices
Use Platform Context: Always use provided platform context values instead of hardcoded values
Clear Explanations: Provide clear explanations with suggested actions
Human-in-the-Loop: Set execute: false for commands requiring approval
Maintain State: Include your executed commands in responses to maintain context
Progressive Disclosure: Start with diagnostic commands before suggesting changes
Analyze Outputs: Always analyze command outputs and provide insights
Thread Consistency: Return the same thread_id received in the request
Handle Rejections: Respect command rejections and adjust your approach
Symmetric Patterns: Use executed_cmds consistently for sharing command results
{
"k8s_namespace": "duploservices-andy",
"tenant_name": "andy",
"tenant_id": "7859b3f9-6d74-44fd-b20f-2b9c1e056761",
"duplo_base_url": "duplo.cloud.exmple.com",
"aws_credentials": { /* ... */ },
"kubeconfig": "base64...",
"duplo_token": "DuploCloud Token for the user sending the message to the Agent",
"grafana_base_url": "https://grafana.example.com",
"aws_security_group_name": "duploservices-andy",
"aws_iam_role_name": "duploservices-andy"
}
{
"role": "assistant",
"content": "Agent's text response to the user",
"data": {
"cmds": [],
"executed_cmds": [],
"url_configs": []
}
}
{
"role": "assistant",
"content": "I'll check the pod status in your namespace.",
"data": {
"cmds": [
{
"command": "kubectl get pods -n duploservices-andy",
"execute": false,
"files": [
{
"file_path": "config/app.yaml",
"file_content": "apiVersion: v1\nkind: ConfigMap..."
}
]
}
]
}
}
{
"role": "assistant",
"content": "Let me check your pod status and recent events.",
"data": {
"cmds": [
{
"command": "kubectl get pods -n duploservices-andy",
"execute": false
},
{
"command": "kubectl get events -n duploservices-andy --sort-by=.metadata.creationTimestamp",
"execute": false
}
]
}
}
{
"role": "user",
"content": "", // Empty for pure approval
"data": {
"cmds": [
{
"command": "kubectl get pods -n duploservices-andy",
"execute": true // Approved
},
{
"command": "kubectl get events -n duploservices-andy --sort-by=.metadata.creationTimestamp",
"execute": false, // Rejected
"rejection_reason": "Too much output, let's focus on pods first" //Optional Field may or may not be provided by the user
}
]
}
}
{
"role": "user",
"content": "I ran my own commands, analyze them",
"data": {
"executed_cmds": [
{
"command": "kubectl get pods -n duploservices-andy",
"output": "NAME READY STATUS RESTARTS AGE\napp-69fb74d9d4-j2l6x 1/1 Running 0 22h"
}
]
}
}
{
"content": "All pods are running successfully. The app pod has been stable for 22 hours.",
"data": {
"executed_cmds": [
{
"command": "kubectl get pods -n duploservices-andy",
"output": "NAME READY STATUS RESTARTS AGE\napp-69fb74d9d4-j2l6x 1/1 Running 0 22h"
}
],
"cmds": [
{
"command": "kubectl logs app-69fb74d9d4-j2l6x --tail=50",
"execute": false
}
]
}
}
{
"role": "user",
"content": "I checked the logs myself and found errors",
"data": {
"executed_cmds": [
{
"command": "kubectl logs app-69fb74d9d4-j2l6x | grep ERROR",
"output": "ERROR: Database connection timeout\nERROR: Failed to fetch user data"
}
]
}
}
