> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naturalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Agent

> Creates a new agent configuration for the current account.
Requires `agent_config:edit` permission.




## OpenAPI

````yaml POST /api/agent-config
openapi: 3.1.0
info:
  title: Naturalead Agent Config API
  version: 1.0.0
  description: >
    API for managing AI agent configurations in the Naturalead platform.

    Agent configs define how the AI converses with leads, including the system
    prompt,

    conversation stages, guardrails, and attached knowledge bases.


    All endpoints require API key authentication and are scoped to the caller's
    account.
servers:
  - url: '{baseUrl}'
    description: API server
    variables:
      baseUrl:
        default: http://localhost:3001
security:
  - BearerAuth: []
tags:
  - name: Agent Config
    description: AI agent configuration CRUD, templates, and knowledge base assignment
  - name: Templates
    description: Pre-built agent configuration templates
  - name: Knowledge Bases
    description: Attach and detach knowledge bases from agents
paths:
  /api/agent-config:
    post:
      tags:
        - Agent Config
      summary: Create agent
      description: |
        Creates a new agent configuration for the current account.
        Requires `agent_config:edit` permission.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentConfigInput'
      responses:
        '201':
          description: Created agent configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfig'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    AgentConfigInput:
      type: object
      description: >-
        Request body for creating or updating an agent configuration. All fields
        are optional on update.
      properties:
        name:
          type: string
          description: Agent display name
        status:
          type: string
          enum:
            - active
            - inactive
            - draft
        systemPrompt:
          type: string
          description: System prompt sent to the LLM
        language:
          type: string
          description: Conversation language
        goal:
          type: string
          description: High-level goal for the agent
        instructions:
          type: string
          description: Additional instructions
        qualificationCriteria:
          type: string
        handoffMessage:
          type: string
        stages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationStage'
        guardrails:
          $ref: '#/components/schemas/Guardrails'
        knowledgeBaseIds:
          type: array
          items:
            type: string
    AgentConfig:
      type: object
      properties:
        _id:
          type: string
          description: MongoDB ObjectId
        accountId:
          type: string
          description: Account ObjectId this agent belongs to
        name:
          type: string
          description: Agent display name
        status:
          type: string
          enum:
            - active
            - inactive
            - draft
          default: active
        systemPrompt:
          type: string
          description: System prompt sent to the LLM for every conversation
        language:
          type: string
          description: Conversation language
          default: English
        goal:
          type: string
          description: High-level goal for the agent
        instructions:
          type: string
          description: Additional instructions for the agent
        qualificationCriteria:
          type: string
          description: Criteria used to qualify leads
        handoffMessage:
          type: string
          description: Message sent when the conversation is handed off to a human
          default: I'll connect you with a specialist who can help further!
        stages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationStage'
          description: Ordered conversation stages
        guardrails:
          $ref: '#/components/schemas/Guardrails'
        knowledgeBaseIds:
          type: array
          items:
            type: string
          description: ObjectIds of attached knowledge bases
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - accountId
        - name
        - systemPrompt
        - goal
    ConversationStage:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        order:
          type: integer
        prompt:
          type: string
          description: Stage-specific prompt for the LLM
        transitionCriteria:
          type: string
          description: Criteria for transitioning to the next stage
        maxMessages:
          type: integer
          description: Max messages allowed in this stage (0 = unlimited)
          default: 0
        nextStages:
          type: array
          items:
            $ref: '#/components/schemas/StageConnection'
          description: Explicit connections with optional per-branch conditions
        nextStageIds:
          type: array
          items:
            type: string
          description: 'Legacy: derived from nextStages, kept for backward compatibility'
        position:
          type: object
          properties:
            x:
              type: number
            'y':
              type: number
          description: Visual position in the stage flow editor
      required:
        - id
        - name
        - order
    Guardrails:
      type: object
      properties:
        maxTotalMessages:
          type: integer
          description: Maximum number of messages before the conversation ends
          default: 40
        inactivityTimeoutMinutes:
          type: integer
          description: Minutes of inactivity before the conversation times out
          default: 1440
        forbiddenTopics:
          type: string
          description: Comma-separated topics the agent must avoid
          default: ''
        escalationTriggers:
          type: string
          description: Comma-separated triggers that escalate to a human
          default: ''
    StageConnection:
      type: object
      properties:
        id:
          type: string
          description: Target stage ID
        condition:
          type: string
          description: Branch label (e.g. "Yes", "No", "Premium")
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
            required:
              - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token using an API key (format nl_live_* or nl_test_*)

````