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

# Execute agent

> Executes an agent with optional content.



## OpenAPI

````yaml post /agents/execute
openapi: 3.1.0
info:
  title: Kaizen API
  version: 1.0.0
  description: API for the Kaizen Automation Platform
servers:
  - url: https://api.kaizenautomation.com
    description: Production server
security: []
paths:
  /agents/execute:
    post:
      tags:
        - Agents
      summary: Execute agent
      description: Executes an agent with optional content.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                  description: >-
                    Optional - the backend will automatically get or create an
                    agent.
                content:
                  type: array
                  items:
                    oneOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            const: text
                          text:
                            type: string
                            description: Text content
                        required:
                          - type
                          - text
                      - type: object
                        properties:
                          type:
                            type: string
                            const: file
                          id:
                            type: string
                            description: >-
                              External file ID referencing a previously uploaded
                              file.
                        required:
                          - type
                          - id
                      - type: object
                        properties:
                          type:
                            type: string
                            const: skill
                          id:
                            type: string
                            description: >-
                              ID of the skill to use (the agent_fs_node external
                              ID). The skill content will be read and injected
                              into the initial user prompt.
                        required:
                          - type
                          - id
                      - type: object
                        properties:
                          type:
                            type: string
                            const: login
                          id:
                            type: string
                            description: >-
                              ID of a login to pin to this execution. The login
                              is validated against the organization and injected
                              into the initial prompt so the agent uses it
                              without having to search for credentials.
                        required:
                          - type
                          - id
                      - type: object
                        properties:
                          type:
                            type: string
                            const: json
                          data:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Structured JSON data as key-value pairs. Rendered
                              as a table in the UI and persisted as input.json
                              in the session folder.
                        required:
                          - type
                          - data
                  description: >-
                    Optional content array. If provided, this will be used as
                    the initial message. Each item must have a `type` field with
                    one of the following values:


                    - `text` — Plain text content. Requires a `text` string
                    field.

                    - `file` — A previously uploaded file. Requires an `id`
                    string field with the file external ID.

                    - `skill` — A skill to inject into the prompt. Requires an
                    `id` string field with the agent_fs_node external ID.

                    - `login` — A login to pin to this execution. Requires an
                    `id` string field with the login ID. The login is validated
                    against the organization and injected into the initial
                    prompt so the agent uses it without searching for
                    credentials.

                    - `json` — Structured key-value data. Requires a `data`
                    object field. Rendered as a table in the UI and persisted as
                    input.json.
                archiveSessionFiles:
                  type: boolean
                  description: >-
                    When true, request a background archive of the thread
                    session files after the execution reaches a terminal state.
                  default: false
                summarySchema:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Optional JSON Schema for per-execution summary extraction.
                    Overrides the agent-level result schema for this execution
                    only.
                kaizenVersion:
                  type: string
                  enum:
                    - Full
                    - Lite
                  description: >-
                    Kaizen version tier to use for this execution. Determines
                    the default model based on your organization’s model alias
                    configuration for the selected tier.


                    - `Full` — Uses the model configured for Kaizen Full
                    (typically a frontier model).

                    - `Lite` — Uses the model configured for Kaizen Lite
                    (typically a smaller, faster model).


                    When not provided, the organization’s default Kaizen version
                    is used.
                enableComputerUse:
                  type: boolean
                  description: >-
                    Whether the computer-use tool is available for this
                    execution. When false, computer use is disabled even if the
                    org-level flag is on. When omitted, the org-level flag
                    applies.
              description: Request parameters for executing an agent
      responses:
        '200':
          description: Agent execution started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    description: ID of the session started for this execution
                  executionId:
                    type: string
                    description: ID of the execution
                  status:
                    type: string
                    description: Current status of the execution
                required:
                  - sessionId
                  - executionId
                  - status
                description: Response after starting agent execution
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error

````