> ## 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.

# Get Agent

> Returns a single agent configuration by ID, with `knowledgeBaseIds`
populated as full knowledge base objects.
Requires `agent_config:view` permission.




## OpenAPI

````yaml GET /api/agent-config/{id}
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/{id}:
    get:
      tags:
        - Agent Config
      summary: Get agent
      description: |
        Returns a single agent configuration by ID, with `knowledgeBaseIds`
        populated as full knowledge base objects.
        Requires `agent_config:view` permission.
      operationId: getAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfig'
        '404':
          $ref: '#/components/responses/AgentNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    AgentId:
      name: id
      in: path
      required: true
      description: Agent configuration ObjectId
      schema:
        type: string
  schemas:
    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:
    AgentNotFound:
      description: Agent not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Agent not found
            required:
              - error
    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_*)

````