> This page is for Server SDKs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# list

> List AI agent resources.

List AI agent resources in the project.

### Schema

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /api/fabric/resources/ai_agents:
    get:
      operationId: subpackageAiAgentsCustom_list_ai_agents
      summary: List AI agents
      description: >-
        Lists the custom AI Agents in your SignalWire project. Each agent is a
        reusable Fabric resource that defines a conversational call experience
        and can be reached through resource addresses or assigned as a call
        handler. Use [Dialogflow
        Agents](/docs/apis/rest/ai-agents/ai-agents-dialogflow/list-dialogflow-agents)
        for linked Dialogflow integrations, or [Call
        Flows](/docs/apis/rest/call-flows/list-call-flows) for visual,
        deterministic call logic.


        #### Permissions


        The API token used to authenticate must have the following scope(s)
        enabled to make a successful request: _Voice_, _Messaging_, _Fax_, or
        _Video_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).
      tags:
        - subpackage_aiAgentsCustom
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIAgentListResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
tags:
  - name: subpackage_aiAgentsCustom
servers:
  - url: https://%7BYour_Space_Name%7D.signalwire.com
    description: SignalWire API
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    AiAgentResponseType:
      type: string
      enum:
        - ai_agent
      description: Type of the Fabric Resource
      title: AiAgentResponseType
    AiAgentLanguagesItems:
      type: object
      properties: {}
      title: AiAgentLanguagesItems
    AiAgentParams:
      type: object
      properties: {}
      description: >-
        A JSON object containing parameters as key-value pairs.


        See [`ai.params` in the SWML
        reference](/docs/swml/reference/calling/ai#aiparams).
      title: AiAgentParams
    AiAgentPostPrompt:
      type: object
      properties: {}
      description: >-
        The final set of instructions and configuration settings to send to the
        agent.


        See [`ai.post_prompt` in the SWML
        reference](/docs/swml/reference/calling/ai#aipost_prompt).
      title: AiAgentPostPrompt
    AiAgentPronounceItems:
      type: object
      properties: {}
      title: AiAgentPronounceItems
    AiAgentPrompt:
      type: object
      properties: {}
      description: >-
        Defines the AI agent's personality, goals, behaviors, and instructions
        for handling conversations.

        The prompt establishes how the agent should interact with callers, what
        information it should gather,

        and how it should respond to various scenarios. It is recommended to
        write prompts using markdown formatting.


        See [`ai.prompt` in the SWML
        reference](/docs/swml/reference/calling/ai#aiprompt).
      title: AiAgentPrompt
    AiAgentSwaig:
      type: object
      properties: {}
      description: >-
        An array of JSON objects to create user-defined functions/endpoints that
        can be executed during the dialogue.


        See [`ai.SWAIG` in the SWML
        reference](/docs/swml/reference/calling/ai#aiswaig).
      title: AiAgentSwaig
    AIAgent:
      type: object
      properties:
        hints:
          type: array
          items:
            type: string
          description: >-
            Hints help the AI agent understand certain words or phrases better.
            Words that can commonly be misinterpreted can be added to the hints
            to help the AI speak more accurately.


            See [`ai.hints` in the SWML
            reference](/docs/swml/reference/calling/ai#aihints).
        languages:
          type: array
          items:
            $ref: '#/components/schemas/AiAgentLanguagesItems'
          description: >-
            An array of JSON objects defining supported languages in the
            conversation.

            Mutually exclusive with `multilingual`: if both are set,
            `multilingual` is used and

            this array is ignored.


            See [`ai.languages` in the SWML
            reference](/docs/swml/reference/calling/ai#ailanguages).
        params:
          $ref: '#/components/schemas/AiAgentParams'
          description: >-
            A JSON object containing parameters as key-value pairs.


            See [`ai.params` in the SWML
            reference](/docs/swml/reference/calling/ai#aiparams).
        post_prompt:
          $ref: '#/components/schemas/AiAgentPostPrompt'
          description: >-
            The final set of instructions and configuration settings to send to
            the agent.


            See [`ai.post_prompt` in the SWML
            reference](/docs/swml/reference/calling/ai#aipost_prompt).
        pronounce:
          type: array
          items:
            $ref: '#/components/schemas/AiAgentPronounceItems'
          description: >-
            An array of JSON objects to clarify the AI's pronunciation of words
            or expressions.


            See [`ai.pronounce` in the SWML
            reference](/docs/swml/reference/calling/ai#aipronounce).
        prompt:
          $ref: '#/components/schemas/AiAgentPrompt'
          description: >-
            Defines the AI agent's personality, goals, behaviors, and
            instructions for handling conversations.

            The prompt establishes how the agent should interact with callers,
            what information it should gather,

            and how it should respond to various scenarios. It is recommended to
            write prompts using markdown formatting.


            See [`ai.prompt` in the SWML
            reference](/docs/swml/reference/calling/ai#aiprompt).
        SWAIG:
          $ref: '#/components/schemas/AiAgentSwaig'
          description: >-
            An array of JSON objects to create user-defined functions/endpoints
            that can be executed during the dialogue.


            See [`ai.SWAIG` in the SWML
            reference](/docs/swml/reference/calling/ai#aiswaig).
        agent_id:
          $ref: '#/components/schemas/uuid'
          description: Unique ID of an AI Agent.
        name:
          type: string
          description: Name of the AI Agent.
      required:
        - prompt
        - agent_id
        - name
      description: >-
        Creates an AI agent that conducts voice conversations using automatic
        speech recognition (ASR),

        large language models (LLMs), and text-to-speech (TTS) synthesis.

        The agent processes caller speech in real-time, generates contextually
        appropriate responses,

        and can execute custom functions to interact with external systems
        through SignalWire AI Gateway (SWAIG).


        See the [SWML `ai` method reference](/docs/swml/reference/calling/ai)
        for the complete configuration contract.
      title: AIAgent
    AIAgentResponse:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: Unique ID of the AIAgent.
        project_id:
          $ref: '#/components/schemas/uuid'
          description: Unique ID of the Project.
        display_name:
          type: string
          description: Display name of the AIAgent Fabric Resource
        type:
          $ref: '#/components/schemas/AiAgentResponseType'
          description: Type of the Fabric Resource
        created_at:
          type: string
          format: date-time
          description: Date and time when the resource was created.
        updated_at:
          type: string
          format: date-time
          description: Date and time when the resource was updated.
        ai_agent:
          $ref: '#/components/schemas/AIAgent'
          description: AIAgent data.
      required:
        - id
        - project_id
        - display_name
        - type
        - created_at
        - updated_at
        - ai_agent
      title: AIAgentResponse
    AIAgentPaginationResponse:
      type: object
      properties:
        self:
          type: string
          format: uri
          description: Link of the current page
        first:
          type: string
          format: uri
          description: Link to the first page
        next:
          type: string
          format: uri
          description: Link to the next page
        prev:
          type: string
          format: uri
          description: Link to the previous page
      required:
        - self
        - first
      title: AIAgentPaginationResponse
    AIAgentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AIAgentResponse'
          description: An array of objects containing the list of AI Agent data.
        links:
          $ref: '#/components/schemas/AIAgentPaginationResponse'
          description: Object containing pagination links
      required:
        - data
        - links
      title: AIAgentListResponse
    TypesStatusCodesStatusCode401Error:
      type: string
      enum:
        - Unauthorized
      title: TypesStatusCodesStatusCode401Error
    Types.StatusCodes.StatusCode401:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error'
      required:
        - error
      description: Access is unauthorized.
      title: Types.StatusCodes.StatusCode401
    TypesStatusCodesStatusCode404Error:
      type: string
      enum:
        - Not Found
      title: TypesStatusCodesStatusCode404Error
    Types.StatusCodes.StatusCode404:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode404Error'
      required:
        - error
      description: The server cannot find the requested resource.
      title: Types.StatusCodes.StatusCode404
    TypesStatusCodesStatusCode500Error:
      type: string
      enum:
        - Internal Server Error
      title: TypesStatusCodesStatusCode500Error
    Types.StatusCodes.StatusCode500:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error'
      required:
        - error
      description: An internal server error occurred.
      title: Types.StatusCodes.StatusCode500

```

## **Response Example**

### Response (200)

```json
{
  "data": [
    {
      "id": "993ed018-9e79-4e50-b97b-984bd5534095",
      "project_id": "1313fe58-5e14-4c11-bbe7-6fdfa11fe780",
      "display_name": "Support Assistant",
      "type": "ai_agent",
      "created_at": "2024-05-06T12:20:00Z",
      "updated_at": "2024-05-06T12:25:00Z",
      "ai_agent": {
        "prompt": {
          "text": "You are a helpful customer support assistant."
        },
        "agent_id": "a87db7ed-8ebe-42e4-829f-8ba5a4152f54",
        "name": "Support Assistant"
      }
    }
  ],
  "links": {
    "self": "https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50",
    "first": "https://example.signalwire.com/api/fabric/resources/ai_agents?page_number=0&page_size=50"
  }
}
```

## **Example**

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

response = client.fabric.ai_agents.list()
for agent in response.get("data", []):
    print(f"{agent['display_name']}: {agent['id']}")
```