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

# Execute an agent

> Start an execution for the given agent.



## OpenAPI

````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agents/{agentId}/execute
openapi: 3.1.0
info:
  title: Agent Service
  version: v1
servers:
  - description: V2 API
    url: https://odyssey.asteroid.ai/agents/v2
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
  - name: Execution
  - name: Files
  - name: Agent Profiles
  - name: Agent Profile Pools
  - name: Workflows
  - name: Schema
  - name: Documentation
  - name: Context
paths:
  /agents/{agentId}/execute:
    post:
      tags:
        - Agents
      summary: Execute an agent
      description: Start an execution for the given agent.
      operationId: AgentExecutePost
      parameters:
        - description: The ID of the agent to execute
          in: path
          name: agentId
          required: true
          schema:
            $ref: '#/components/schemas/Common.uuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Agents.Agent.ExecuteAgentRequest'
        description: Execution request parameters
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agents.Agent.ExecuteAgentResponse'
          description: >-
            The request has been accepted for processing, but processing has not
            yet completed.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Error'
          description: An unexpected error response.
components:
  schemas:
    Common.uuid:
      format: uuid
      type: string
    Agents.Agent.ExecuteAgentRequest:
      properties:
        agentProfileId:
          allOf:
            - $ref: '#/components/schemas/Common.uuid'
          description: >-
            The ID of the agent profile to use for this execution. Mutually
            exclusive with agentProfilePoolId.
        agentProfilePoolId:
          allOf:
            - $ref: '#/components/schemas/Common.uuid'
          description: >-
            The ID of the agent profile pool to select a profile from. Mutually
            exclusive with agentProfileId.
        dynamicData:
          deprecated: true
          description: >-
            Deprecated: Use 'inputs' instead. Inputs to be merged into the
            placeholders defined in prompts
          type: object
          unevaluatedProperties: {}
        executionOptions:
          allOf:
            - $ref: '#/components/schemas/Agents.Agent.ExecutionOptions'
          description: >-
            Per-execution runtime options that override or extend the agent's
            default settings.
        inputs:
          description: Inputs to be merged into the placeholders defined in prompts
          type: object
          unevaluatedProperties: {}
        metadata:
          description: >-
            Optional metadata key-value pairs (string keys and string values)
            for organizing and filtering executions
          type: object
          unevaluatedProperties:
            type: string
        tempFiles:
          description: >-
            Array of temporary files to attach to the execution. Must have been
            pre-uploaded using the stage file endpoint
          items:
            $ref: '#/components/schemas/Agents.Files.TempFile'
          type: array
        version:
          description: >-
            The version of the agent to execute. If not provided, the latest
            version will be used.
          type: integer
      type: object
    Agents.Agent.ExecuteAgentResponse:
      properties:
        executionId:
          allOf:
            - $ref: '#/components/schemas/Common.uuid'
          description: The ID of the newly created execution
      required:
        - executionId
      type: object
    Common.Error:
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
      required:
        - code
        - message
      type: object
    Agents.Agent.ExecutionOptions:
      description: Per-execution runtime options.
      properties:
        sharedStorageKey:
          description: >-
            Scopes shared-file storage to a per-entity subdirectory under each
            node's shared folder. The value is normalised to a filesystem-safe
            slug by the server.
          type: string
        softTimeoutMins:
          description: >-
            Soft timeout in minutes. When the execution has been running longer
            than this value, a message is injected on every subsequent step
            urging the agent to wrap up and produce output. Must be greater than
            0 and less than the agent's hard timeout (max_timeout_mins).
          minimum: 1
          type: integer
      type: object
    Agents.Files.TempFile:
      properties:
        id:
          $ref: '#/components/schemas/Common.uuid'
        name:
          type: string
      required:
        - id
        - name
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-Asteroid-Agents-Api-Key
      type: apiKey

````