> ## Documentation Index > Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent Run > Execute an agent with a message and optional media files. Supports both streaming and non-streaming responses. **Features:** - Text message input with optional session management - Multi-media support: images (PNG, JPEG, WebP), audio (WAV, MP3), video (MP4, WebM, etc.) - Document processing: PDF, CSV, DOCX, TXT, JSON - Real-time streaming responses with Server-Sent Events (SSE) - User and session context preservation **Streaming Response:** When `stream=true`, returns SSE events with `event` and `data` fields. ## OpenAPI ````yaml post /agents/{agent_id}/runs openapi: 3.1.0 info: title: Agno API Reference description: The all-in-one, private, secure agent platform that runs in your cloud. version: 3.0.4 servers: [] security: [] paths: /agents/{agent_id}/runs: post: tags: - Agents summary: Create Agent Run description: >- Execute an agent with a message and optional media files. Supports both streaming and non-streaming responses. **Features:** - Text message input with optional session management - Multi-media support: images (PNG, JPEG, WebP), audio (WAV, MP3), video (MP4, WebM, etc.) - Document processing: PDF, CSV, DOCX, TXT, JSON - Real-time streaming responses with Server-Sent Events (SSE) - User and session context preservation **Streaming Response:** When `stream=true`, returns SSE events with `event` and `data` fields. operationId: create_agent_run parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_create_agent_run' responses: '200': description: Agent run executed successfully content: application/json: schema: {} text/event-stream: examples: event_stream: summary: Example event stream response value: |+ event: RunStarted data: {"content": "Hello!", "run_id": "123..."} '400': description: Invalid request or unsupported file type content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '403': description: 'Insufficient permissions. Required scope(s): agents:run' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - {} - HTTPBearer: [] components: schemas: Body_create_agent_run: properties: message: type: string title: Message description: The input message or prompt to send to the agent stream: type: boolean title: Stream description: Enable streaming responses via Server-Sent Events (SSE) default: true session_id: anyOf: - type: string - type: 'null' title: Session Id description: >- Session ID for conversation continuity. If not provided, a new session is created user_id: anyOf: - type: string - type: 'null' title: User Id description: User identifier for tracking and personalization files: anyOf: - items: type: string contentMediaType: application/octet-stream type: array - type: 'null' title: Files description: Files to upload (images, audio, video, or documents) files_metadata: anyOf: - type: string - type: 'null' title: Files Metadata description: >- JSON array of per-file metadata objects, matched to files[] by position version: anyOf: - type: integer - type: 'null' title: Version description: Agent version to use for this run background: type: boolean title: Background description: >- Run in background and return immediately with run metadata (requires database) default: false factory_input: anyOf: - type: string - type: 'null' title: Factory Input description: >- JSON object with factory-specific parameters for dynamic agent construction type: object required: - message title: Body_create_agent_run BadRequestResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: BadRequestResponse example: detail: Bad request UnauthenticatedResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: UnauthenticatedResponse example: detail: Unauthenticated access NotFoundResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: NotFoundResponse example: detail: Not found ValidationErrorResponse: properties: detail: anyOf: - type: string - items: $ref: '#/components/schemas/ValidationErrorDetail' type: array title: Detail description: >- A single message for an explicitly raised 422, or a list of field-level errors for a request-validation failure type: object required: - detail title: ValidationErrorResponse description: >- 422 body. Two runtime shapes share this status code, and the same endpoint can return either, so ``detail`` is typed as their union: - FastAPI's request-validation handler emits a **list** of field-level errors (built-in coercion errors and custom-validator ``ValueError``s alike). - A route that raises ``HTTPException(status_code=422, detail="...")`` for a semantic check (e.g. an invalid cron expression) emits a **string** through the HTTPException handler. example: detail: - loc: - body - endpoint msg: Value error, Endpoint must be a path, not a full URL type: value_error InternalServerErrorResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: InternalServerErrorResponse example: detail: Internal server error ValidationErrorDetail: properties: loc: items: anyOf: - type: string - type: integer type: array title: Loc description: Path to the offending field, e.g. ['body', 'endpoint'] msg: type: string title: Msg description: Human-readable error message type: type: string title: Type description: Error type identifier, e.g. 'value_error' or 'missing' type: object required: - loc - msg - type title: ValidationErrorDetail description: >- One field-level error inside a 422 body, matching FastAPI's default shape. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.