Agents Service API

API reference for managing AI agents and agent deployments

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

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Request Body:

Field	Type	Required	Description
name	string	Yes	Name of the agent
description	string	Yes	Description of the agent’s purpose
agent_type	string	Yes	Type of agent (e.g., “chat”, “function”)
model_id	string	Yes	ID of the LLM model to use
tools	array	No	List of tools to provide to the agent
params	object	Yes	Configuration parameters for the agent
is_public	boolean	No	Whether the agent is publicly available (default: false)

Agent Parameters:

Field	Type	Description
system_prompt	string	The system instructions for the agent
temperature	number	Sampling temperature (0-1)
max_tokens	number	Maximum tokens in the response

List Agents

Retrieve all agents for an organization.

Request

curl -X GET {{baseUrl}}/api/agents/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/agents/list

Query Parameters:

Parameter	Required	Description
org_id	Yes	Organization ID

Get Agent Details

Retrieve detailed information about a specific agent.

Request

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:

Parameter	Required	Description
agent_id	Yes	ID of the agent to retrieve

Update Agent

Update an existing agent’s configuration.

Request

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:

Parameter	Required	Description
agent_id	Yes	ID of the agent to update

Request Body:

Field	Type	Required	Description
name	string	No	New name for the agent
description	string	No	New description
model_id	string	No	New model ID
tools	array	No	Updated list of tools
params	object	No	Updated configuration parameters
is_public	boolean	No	Update public availability

Delete Agent

Delete an agent from the organization.

Request

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:

Parameter	Required	Description
agent_id	Yes	ID of the agent to delete

Agent Deployment Endpoints

Create Deployment

Create a new deployment for an existing agent.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Request Body:

Field	Type	Required	Description
agent_id	string	Yes	ID of the agent to deploy
name	string	Yes	Name of the deployment
description	string	Yes	Description of the deployment
deployment_type	string	Yes	Type of deployment (e.g., “widget”, “api”, “iframe”)
config	object	Yes	Configuration parameters for the deployment

List Deployments

Retrieve all deployments for an organization.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Get Deployment Details

Retrieve detailed information about a specific deployment.

Request

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:

Parameter	Required	Description
deployment_id	Yes	ID of the deployment to retrieve

Update Deployment

Update an existing deployment configuration.

Request

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:

Parameter	Required	Description
deployment_id	Yes	ID of the deployment to update

Request Body:

Field	Type	Required	Description
name	string	No	New name for the deployment
description	string	No	New description
config	object	No	Updated configuration parameters

Delete Deployment

Delete a deployment.

Request

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:

Parameter	Required	Description
deployment_id	Yes	ID of the deployment to delete

Regenerate API Key

Regenerate the API key for a deployment.

Request

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:

Parameter	Required	Description
deployment_id	Yes	ID of the deployment for which to regenerate the API key

Error Responses

Status Code	Description
400	Bad Request - Invalid input or validation error
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists or conflict with existing resource
500	Internal 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