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

# Run Agent

> Execute an AI agent by name with a user message.


This endpoint runs inference using a specific agent identified by its name. The agent's custom instructions, demonstrations, and model configuration are applied to generate a personalized response.


**Path Parameters:**

- `agent_name`: URL-friendly name of the agent to execute (lowercase with underscores)


**Request Body:**

- `message`: User message or prompt to send to the agent


**Optional Headers:**

- `X-Session-ID`: Session identifier to store conversations


**Returns:**

- `agent_id`: Unique identifier of the agent that processed the request
- `model`: Model ID that was used for inference
- `response`: Generated text response from the agent
- `usage`: Token usage statistics containing:
  - `input_tokens`: Number of tokens in the input
  - `output_tokens`: Number of tokens in the output
  - `total_tokens`: Total tokens used


**Raises:**

- `404`: If the agent name is not found or not active
- `402`: If user has insufficient quota/balance
- `500`: If inference execution fails


**Example Request:**

```json
POST /api/v3/agents/run-agents/customer_support_bot/run
Headers: {
  "Authorization": "Bearer <api_key>"
}

{
  "message": "How do I reset my password?"
}
```


**Example Response:**

```json
{
  "agent_id": "alignment-abc123-deployed",
  "model": "nugen-flash-instruct",
  "response": "I'd be happy to help you reset your password. Here are the steps:

1. Go to the login page
2. Click on 'Forgot Password'
3. Enter your email address
4. Check your email for a reset link
5. Follow the link and create a new password

If you don't receive the email within a few minutes, please check your spam folder. Let me know if you need any further assistance!",
  "usage": {
    "input_tokens": 245,
    "output_tokens": 98,
    "total_tokens": 343
  }
}
```


**Notes:**

- The `agent_name` in the URL must match the normalized agent name (lowercase with underscores)
- Include `X-Session-ID` header to maintain conversation context across multiple requests
- The response includes token usage for monitoring purposes
- Conversations are automatically saved if enabled in user settings



## OpenAPI

````yaml https://api.nugen.in/openapi-public.json post /api/v3/agents/run-agents/{agent_name}/run
openapi: 3.1.0
info:
  title: Nugen Intelligence API
  description: 'Nugen Intelligence : Powering Specialized Intelligence At Scale'
  version: 25.4.20
servers: []
security: []
paths:
  /api/v3/agents/run-agents/{agent_name}/run:
    post:
      tags:
        - Agents
      summary: Run Agent
      description: >-
        Execute an AI agent by name with a user message.



        This endpoint runs inference using a specific agent identified by its
        name. The agent's custom instructions, demonstrations, and model
        configuration are applied to generate a personalized response.



        **Path Parameters:**


        - `agent_name`: URL-friendly name of the agent to execute (lowercase
        with underscores)



        **Request Body:**


        - `message`: User message or prompt to send to the agent



        **Optional Headers:**


        - `X-Session-ID`: Session identifier to store conversations



        **Returns:**


        - `agent_id`: Unique identifier of the agent that processed the request

        - `model`: Model ID that was used for inference

        - `response`: Generated text response from the agent

        - `usage`: Token usage statistics containing:
          - `input_tokens`: Number of tokens in the input
          - `output_tokens`: Number of tokens in the output
          - `total_tokens`: Total tokens used


        **Raises:**


        - `404`: If the agent name is not found or not active

        - `402`: If user has insufficient quota/balance

        - `500`: If inference execution fails



        **Example Request:**


        ```json

        POST /api/v3/agents/run-agents/customer_support_bot/run

        Headers: {
          "Authorization": "Bearer <api_key>"
        }


        {
          "message": "How do I reset my password?"
        }

        ```



        **Example Response:**


        ```json

        {
          "agent_id": "alignment-abc123-deployed",
          "model": "nugen-flash-instruct",
          "response": "I'd be happy to help you reset your password. Here are the steps:

        1. Go to the login page

        2. Click on 'Forgot Password'

        3. Enter your email address

        4. Check your email for a reset link

        5. Follow the link and create a new password


        If you don't receive the email within a few minutes, please check your
        spam folder. Let me know if you need any further assistance!",
          "usage": {
            "input_tokens": 245,
            "output_tokens": 98,
            "total_tokens": 343
          }
        }

        ```



        **Notes:**


        - The `agent_name` in the URL must match the normalized agent name
        (lowercase with underscores)

        - Include `X-Session-ID` header to maintain conversation context across
        multiple requests

        - The response includes token usage for monitoring purposes

        - Conversations are automatically saved if enabled in user settings
      operationId: run_agent_by_name
      parameters:
        - name: agent_name
          in: path
          required: true
          schema:
            type: string
            description: Name of the agent to execute
            title: Agent Name
          description: Name of the agent to execute
        - name: X-Session-ID
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Session-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_run_agent_by_name'
      responses:
        '200':
          description: >-
            Returns the generated response from the agent along with usage
            statistics and model information after executing the specified agent
            by name
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    Body_run_agent_by_name:
      properties:
        message:
          type: string
          title: Message
          description: User message or prompt to send to the agent
      type: object
      required:
        - message
      title: Body_run_agent_by_name
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````