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

# Execute Agent

> Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be active and belong to the specified location, with locationId required in the request body. For initial messages, exclude executionId. The API returns an executionId that identifies the conversation session. Include this ID in follow-up requests to maintain context across interactions.



## OpenAPI

````yaml /api-reference/agent-studio/openapi.json post /agent-studio/public-api/agents/{agentId}/execute
openapi: 3.0.0
info:
  title: Agent Studio API
  description: >-
    Documentation for Agent Studio API — list, retrieve, and execute AI agents
    built in Agent Studio.
  version: '1.0'
  contact: {}
servers:
  - url: https://services.leadconnectorhq.com
security: []
tags:
  - name: Agents
    description: Manage and execute Agent Studio agents
paths:
  /agent-studio/public-api/agents/{agentId}/execute:
    post:
      tags:
        - Agents
      summary: Execute Agent
      description: >-
        Executes the specified agent and returns a non-streaming JSON response
        with the complete agent output. The agent must be active and belong to
        the specified location, with locationId required in the request body.
        For initial messages, exclude executionId. The API returns an
        executionId that identifies the conversation session. Include this ID in
        follow-up requests to maintain context across interactions.
      operationId: execute-agent
      parameters:
        - name: Version
          in: header
          description: API Version
          required: true
          schema:
            type: string
            enum:
              - '2021-04-15'
        - name: agentId
          in: path
          description: The agent identifier to execute
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteAgentDTO'
      responses:
        '200':
          description: Agent executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteAgentResponseDTO'
        '400':
          description: Agent inactive or invalid request (missing locationId)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDTO'
        '403':
          description: User lacks required scopes to execute agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenDTO'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundDTO'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableDTO'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorDTO'
      security:
        - bearer: []
components:
  schemas:
    ExecuteAgentDTO:
      type: object
      properties:
        locationId:
          type: string
          description: The location where the agent belongs (required)
          example: loc_abc123
        message:
          type: string
          description: The user message to send to the agent
          example: What services do you offer?
        executionId:
          type: string
          description: >-
            Include for continuing existing conversation sessions. Omit for new
            sessions.
          example: exec_abc123
        contactId:
          type: string
          description: Contact ID to associate with the conversation
          example: contact_abc123
      required:
        - locationId
        - message
    ExecuteAgentResponseDTO:
      type: object
      properties:
        executionId:
          type: string
          description: >-
            Execution session ID. Include this in follow-up requests to continue
            the conversation.
          example: exec_abc123
        agentId:
          type: string
          description: ID of the executed agent
        response:
          type: string
          description: The agent's complete response text
        actions:
          type: array
          description: Actions triggered during execution
          items:
            type: object
            properties:
              type:
                type: string
                description: Type of action triggered
              status:
                type: string
                description: Status of the action execution
              result:
                type: object
                description: Result data from the action
        metadata:
          type: object
          description: Additional execution metadata
          properties:
            tokensUsed:
              type: integer
              description: Number of tokens consumed
            executionTimeMs:
              type: integer
              description: Execution time in milliseconds
    BadRequestDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        message:
          type: string
          example: Bad Request
    UnauthorizedDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          type: string
          example: 'Invalid token: access token is invalid'
        error:
          type: string
          example: Unauthorized
    ForbiddenDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 403
        message:
          type: string
          example: User lacks required scopes
        error:
          type: string
          example: Forbidden
    NotFoundDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 404
        message:
          type: string
          example: Agent not found
        error:
          type: string
          example: Not Found
    UnprocessableDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 422
        message:
          type: array
          items:
            type: string
          example:
            - Unprocessable Entity
        error:
          type: string
          example: Unprocessable Entity
    InternalServerErrorDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 500
        message:
          type: string
          example: Internal server error
        error:
          type: string
          example: Internal Server Error
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use the Access Token generated with user type as Sub-Account (OR)
        Private Integration Token of Sub-Account.
      type: http

````