Agents

Manage AI agents and their configurations.

Agent Management

List Agents

GET /orgs/{organizationId}/agents

Query Parameters:

• limit (optional): Number of results (default: 20)
• cursor (optional): Pagination offset
• orderBy (optional): Field to sort by
• all (optional): Set to "true" to list all agents (requires Admin/Owner role)
• ensureDefaultAgentId (optional): ID of default agent to ensure exists

Response:

{
  "items": [
    {
      "id": "agent-123",
      "organizationId": "org-456",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries",
      "instructions": "You are a helpful...",
      "model": "gpt-4.1",
      "creativityScore": "0.4",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 1,
  "offset": 0
}

Create Agent

POST /orgs/{organizationId}/agents

Required Fields:

• name: Agent name
• description: Agent description
• instructions: System instructions for the agent
• model: AI model to use (e.g., “gpt-4.1”, “gemini”)

Optional Fields:

• creativityScore: String value between “0” and “1” (default: “0.4”)
• emailAddress: Email address for email-based interactions
• emailFilters: Filters for incoming emails
• emailAttachmentsToKnowledgeBaseId: KB ID to store email attachments

Request Body:

{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "instructions": "You are a helpful customer support agent...",
  "model": "gpt-4.1",
  "creativityScore": "0.4"
}

Response: Returns created agent with id field

Get Agent

GET /orgs/{organizationId}/agents/{id}

Returns a single agent’s details. The {id} parameter can be:

• A regular agent ID
• A default agent ID (system will create if not exists)

Update Agent

PUT /orgs/{organizationId}/agents/{id}

Required Fields: All fields from create (name, description, instructions, model)

Request Body:

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "instructions": "Updated instructions...",
  "model": "gpt-4.1",
  "creativityScore": "0.6",
  "emailAddress": "agent@example.com"
}

Delete Agent

DELETE /orgs/{organizationId}/agents/{id}

Permanently deletes the agent and all its knowledge base attachments.

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456"
}

Agent Attachments

Agents can be enhanced with knowledge bases, tools, other agents, and action chains.

Knowledge Base Attachments

List Knowledge Bases

GET /orgs/{organizationId}/agents/{id}/knowledgebases

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456",
  "knowledgebases": [
    {
      "agentId": "agent-456",
      "knowledgeBaseId": "kb-789",
      "kbOrganizationId": "org-123",
      "name": "Product Documentation",
      "description": "Product docs and FAQs",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Attach Knowledge Base

POST /orgs/{organizationId}/agents/{id}/knowledgebases

Request Body:

{
  "knowledgeBaseId": "kb-123",
  "kbOrganizationId": "org-123"
}

Optional: kbOrganizationId - If attaching a knowledge base from a different organization (must be public)

Detach Knowledge Base

DELETE /orgs/{organizationId}/agents/{id}/knowledgebases/{knowledgeBaseId}

Tool Attachments

Tools extend agent capabilities with external integrations.

List Agent’s Tools

GET /orgs/{organizationId}/agents/{id}/tools

Returns array of AgentToolAttachment objects with toolCode and configuration.

Attach Tool

POST /orgs/{organizationId}/agents/{id}/tools

Request Body:

{
  "toolCode": "web_search",
  "configuration": {
    "searchEngine": "google"
  }
}

Update Tool Configuration

PUT /orgs/{organizationId}/agents/{id}/tools/{toolCode}

Request Body:

{
  "configuration": {
    "searchEngine": "bing"
  }
}

Detach Tool

DELETE /orgs/{organizationId}/agents/{id}/tools/{toolCode}

Agent-to-Agent Attachments

Allow agents to collaborate by attaching other agents as sub-agents.

List Agent Attachments

GET /orgs/{organizationId}/agents/{id}/agent-attachments

Returns array of AgentToAgentAttachmentView objects.

Attach Agent

POST /orgs/{organizationId}/agents/{id}/agent-attachments

Request Body:

{
  "targetAgentId": "agent-456",
  "instructions": "Use this agent for technical questions"
}

Update Agent Attachment

PUT /orgs/{organizationId}/agents/{id}/agent-attachments/{targetAgentId}

Detach Agent

DELETE /orgs/{organizationId}/agents/{id}/agent-attachments/{targetAgentId}

Action Chain Attachments

Attach workflow automation chains to agents.

List Action Chains

GET /orgs/{organizationId}/agents/{id}/chains

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456",
  "actionChains": [
    {
      "agentId": "agent-456",
      "chainId": "chain-789",
      "chainName": "Order Processing",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Attach Action Chain

POST /orgs/{organizationId}/agents/{id}/chains

Request Body:

{
  "chainId": "chain-789"
}

Detach Action Chain

DELETE /orgs/{organizationId}/agents/{id}/chains/{chainId}

Available Tools

List Available Tools

GET /orgs/{organizationId}/tools

Returns all tools available for attachment to agents.

Agent Configuration Details

creativityScore

The creativityScore field controls response variability (similar to temperature):

• String value between "0" and "1"
• "0" - Deterministic, focused responses
• "0.4" - Balanced (default)
• "1" - Maximum creativity and variability

Email Integration

Agents can be configured to receive and process emails:

{
  "emailAddress": "support@yourdomain.com",
  "emailFilters": "all",
  "emailAttachmentsToKnowledgeBaseId": "kb-123",
  "emailAttachmentsFileTypeFilter": "pdf,docx,txt",
  "emailCcTo": "team@example.com,manager@example.com",
  "emailBccTo": "archive@example.com",
  "emailReplyTo": "noreply@example.com"
}

Email Configuration Fields:

• emailAddress: Email address where agent receives messages
• emailFilters: String value controlling access
  • "all" - All users in organization can send emails to this agent
  • Other values - Only users with explicit agent access can send emails
• emailAttachmentsToKnowledgeBaseId: Knowledge base ID where email attachments are stored
• emailAttachmentsFileTypeFilter: Comma-separated list of allowed file extensions (e.g., "pdf,docx,txt")
• emailCcTo: Comma-separated list of email addresses to CC on agent replies
• emailBccTo: Comma-separated list of email addresses to BCC on agent replies
• emailReplyTo: Reply-To header for agent email responses

Behavior:

• Incoming emails create new conversations with the agent
• Attachments are automatically uploaded to the specified knowledge base
• Agent can access attachment contents through knowledge base search
• Agent replies are sent from the configured email address
• File type filter restricts which attachment types are processed

Best Practices

1. Clear Instructions - Provide detailed, specific instructions for your agent’s behavior
2. Appropriate Model Selection - Choose models based on task complexity and cost requirements
3. Creativity Score - Use lower values (0-0.3) for factual tasks, higher (0.7-1.0) for creative tasks
4. Incremental Attachments - Test agents with one attachment at a time before adding more
5. Monitor Usage - Track agent performance and token usage through analytics
6. Required Fields - All fields (name, description, instructions, model) are required for both create and update