The Agents Service provides endpoints for creating, configuring, and deploying AI agents within your organization. It enables you to define agent behaviors, tools, and deployment configurations.

​
Agent Lifecycle Overview

​
Agent-Tool Integration Flow

​
Authentication

All endpoints require a valid Bearer token in the Authorization header.

​
Base URL

/api/agents

​
Agent Endpoints

​
Create Agent

Create a new AI agent for your organization. 
curl -X POST {{baseUrl}}/api/agents?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "AI agent for handling customer support inquiries",
    "agent_type": "chat",
    "model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tools": [
      {
        "tool_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "config": [
          {
            "name": "api_key",
            "value": "sk-123456789"
          }
        ]
      }
    ],
    "params": {
      "system_prompt": "You are a helpful customer support agent for our e-commerce platform. Your goal is to assist customers with their inquiries, help them track orders, and resolve issues with their purchases. If you don't know the answer, you can use available tools to look up information.",
      "temperature": 0.7,
      "max_tokens": 1000
    },
    "is_public": false
  }'
Endpoint: POST /api/agents Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
namestringYesName of the agent
descriptionstringYesDescription of the agent’s purpose
agent_typestringYesType of agent (e.g., “chat”, “function”)
model_idstringYesID of the LLM model to use
toolsarrayNoList of tools to provide to the agent
paramsobjectYesConfiguration parameters for the agent
is_publicbooleanNoWhether the agent is publicly available (default: false)
Agent Parameters:
FieldTypeDescription
system_promptstringThe system instructions for the agent
temperaturenumberSampling temperature (0-1)
max_tokensnumberMaximum tokens in the response

​
List Agents

Retrieve all agents for an organization. 
curl -X GET {{baseUrl}}/api/agents/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/agents/list Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID

​
Get Agent Details

Retrieve detailed information about a specific agent. 
curl -X GET {{baseUrl}}/api/agents/get?agent_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/agents/get Query Parameters:
ParameterRequiredDescription
agent_idYesID of the agent to retrieve

​
Update Agent

Update an existing agent’s configuration. 
curl -X PUT {{baseUrl}}/api/agents/update?agent_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Customer Support Agent",
    "description": "Enhanced AI agent for handling premium customer support inquiries",
    "params": {
      "system_prompt": "You are a helpful premium customer support agent...",
      "temperature": 0.5
    }
  }'
Endpoint: PUT /api/agents/update Query Parameters:
ParameterRequiredDescription
agent_idYesID of the agent to update
Request Body:
FieldTypeRequiredDescription
namestringNoNew name for the agent
descriptionstringNoNew description
model_idstringNoNew model ID
toolsarrayNoUpdated list of tools
paramsobjectNoUpdated configuration parameters
is_publicbooleanNoUpdate public availability

​
Delete Agent

Delete an agent from the organization. 
curl -X DELETE {{baseUrl}}/api/agents/delete?agent_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/agents/delete Query Parameters:
ParameterRequiredDescription
agent_idYesID of the agent to delete

​
Agent Deployment Endpoints

​
Create Deployment

Create a new deployment for an existing agent. 
curl -X POST {{baseUrl}}/api/agent_deploy/create?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s",
    "name": "Web Widget Deployment",
    "description": "Customer support agent for the web widget",
    "deployment_type": "widget",
    "config": {
      "theme": {
        "primary_color": "#4f46e5",
        "font_family": "Inter, sans-serif"
      },
      "branding": {
        "logo_url": "https://example.com/logo.png",
        "company_name": "Example Corp"
      },
      "widget_placement": "bottom-right",
      "welcome_message": "👋 Hi there! How can I help you today?"
    }
  }'
Endpoint: POST /api/agent_deploy/create Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
agent_idstringYesID of the agent to deploy
namestringYesName of the deployment
descriptionstringYesDescription of the deployment
deployment_typestringYesType of deployment (e.g., “widget”, “api”, “iframe”)
configobjectYesConfiguration parameters for the deployment

​
List Deployments

Retrieve all deployments for an organization. 
curl -X GET {{baseUrl}}/api/agent_deploy/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/agent_deploy/list Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID

​
Get Deployment Details

Retrieve detailed information about a specific deployment. 
curl -X GET {{baseUrl}}/api/agent_deploy/get?deployment_id=5a4b3c2d-1e0f-9g8h-7i6j-5k4l3m2n1o0p \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/agent_deploy/get Query Parameters:
ParameterRequiredDescription
deployment_idYesID of the deployment to retrieve

​
Update Deployment

Update an existing deployment configuration. 
curl -X PUT {{baseUrl}}/api/agent_deploy/update?deployment_id=5a4b3c2d-1e0f-9g8h-7i6j-5k4l3m2n1o0p \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web Widget Deployment v2",
    "config": {
      "theme": {
        "primary_color": "#3b82f6"
      },
      "welcome_message": "👋 Hello! How may I assist you today?"
    }
  }'
Endpoint: PUT /api/agent_deploy/update Query Parameters:
ParameterRequiredDescription
deployment_idYesID of the deployment to update
Request Body:
FieldTypeRequiredDescription
namestringNoNew name for the deployment
descriptionstringNoNew description
configobjectNoUpdated configuration parameters

​
Delete Deployment

Delete a deployment. 
curl -X DELETE {{baseUrl}}/api/agent_deploy/delete?deployment_id=5a4b3c2d-1e0f-9g8h-7i6j-5k4l3m2n1o0p \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/agent_deploy/delete Query Parameters:
ParameterRequiredDescription
deployment_idYesID of the deployment to delete

​
Regenerate API Key

Regenerate the API key for a deployment. 
curl -X POST {{baseUrl}}/api/agent_deploy/regenerate_key?deployment_id=5a4b3c2d-1e0f-9g8h-7i6j-5k4l3m2n1o0p \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: POST /api/agent_deploy/regenerate_key Query Parameters:
ParameterRequiredDescription
deployment_idYesID of the deployment for which to regenerate the API key

​
Error Responses

Status CodeDescription
400Bad Request - Invalid input or validation error
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists or conflict with existing resource
500Internal Server Error - Server-side error

​
Implementation Notes

  • Agents are configured with specific LLM models, tools, and parameters
  • Agents can be deployed in multiple ways (widget, API, SDK)
  • Each deployment has its own API key for authentication
  • Deployments can be customized with different themes and configurations
  • Usage statistics are available for each deployment
  • Organization-based access control ensures separation between tenants