# Intake Agent

Convert unstructured customer input into a Cart or Quote Request through the HTTP API.

The Intake Agent accepts a natural-language prompt, file uploads, or both. It extracts line items and resolves the Customer, Business Unit, and Store from the input. It then creates a [Cart](/search.md?urn=ctp:api:type:Cart) or [Quote Request](/search.md?urn=ctp:api:type:QuoteRequest) in commercetools REST representation. The caller chooses which entity to create, then reviews and acts on the result using the standard commercetools APIs.

**AI use:** This feature uses AI to analyze data you provide.

**Your data:** We do not use your data to train models.

**Opt-in:** To enable this feature, submit a [support request](https://support.commercetools.com/) and include the Project key.

## When to use the Intake Agent

Use the Intake Agent to:

- Convert a list of SKUs, ISBNs, or product names from an email into a Cart without entering each line manually.
- Convert a customer request from a CSV, PDF, or free-text email into a Cart or Quote Request with catalog matches, pricing, and customer context.
- Convert inbound emails or support tickets into commerce objects without implementing document parsing, product matching, and customer resolution.

## Required information

Every request must include:

- `outputType`: whether to create a Cart or a Quote Request.
- `locale`: a valid BCP-47 language tag, for example `en-US`.

The request must also include input that contains at least one Product reference (name, key, SKU, or Product Variant key). For `application/json` requests, provide a `prompt`. For `multipart/form-data` requests, provide a `prompt`, one or more files, or both.

The Intake Agent must also resolve the Business Unit and Store for the request, either from the input or from an explicit reference.

If a required value is missing or cannot be resolved, the request fails with a [`400` error](/api/agents/intake-agent.md#error-codes). The response names the missing information, such as `RequiredField`, `BusinessUnitUnresolved`, or `StoreUnresolved`.

## Supported input

| Input type | Notes |
| --- | --- |
| Free text | A natural-language prompt, such as the body of an email, a message, or a note. |
| File upload | PDF, TXT, CSV, DOCX, XLSX, EML, Markdown, and HTML. Up to 3 files, 20 MB each. |

## Handling unmatched input

The Intake Agent creates the requested entity even when it cannot match every part of the input. Non-fatal issues are returned as [`warnings`](/api/agents/intake-agent.md#warnings) alongside the `201` response:

- When every referenced Product is matched to your catalog, `warnings` is omitted.
- When one or more Products cannot be matched, a `ProductsNotFound` warning lists the unmatched identifiers. The caller can then address them, for example by editing the entity or asking the customer for more information.
- When an uploaded file cannot be parsed, a `FileNotProcessed` warning names the file.

If no line items can be extracted from the input at all, the request fails with a `NoLineItemsExtracted` error instead.

## Representations

### AgentResponsesRequest

JSON body for an `application/json` request. `prompt` is required.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesRequest).

### AgentResponsesPayload

JSON `payload` part of a `multipart/form-data` request. `prompt` is optional when files are attached.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesPayload).

### AgentResponsesMultipartRequest

`multipart/form-data` body when files are attached.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesMultipartRequest).

### AgentResponsesOutputType

[type definition](/search.md?urn=ctp:api:type:AgentResponsesOutputType).

### AgentResponsesSuccess

Successful `201` responses use a discriminated type based on `entityType`.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesSuccess).

#### AgentResponsesCartSuccess

Returned when `outputType` is `Cart`.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesCartSuccess).

#### AgentResponsesQuoteRequestSuccess

Returned when `outputType` is `QuoteRequest`.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesQuoteRequestSuccess).

### Warnings

Warnings use a [WarningObject](/search.md?urn=ctp:api:type:WarningObject) with a machine-readable `code`. See [Warnings](/api/types.md#warnings) for the full list, including [ProductsNotFound](/search.md?urn=ctp:api:type:AgentProductsNotFoundWarning) and [FileNotProcessed](/search.md?urn=ctp:api:type:AgentFileNotProcessedWarning), which are specific to the Intake Agent.

### AgentResponsesErrorResponse

Except for `401` and `403` responses, errors use this envelope: a `statusCode`, a human-readable `message`, and one or more `errors`.

[type definition](/search.md?urn=ctp:api:type:AgentResponsesErrorResponse).

### AgentResponsesAuthError

A `401` or `403` response uses the standard [AuthErrorResponse](/search.md?urn=ctp:api:type:AuthErrorResponse) shape (`statusCode`, `message`, `errors`, plus OAuth `error` / `error_description`) rather than the [AgentResponsesErrorResponse](/search.md?urn=ctp:api:type:AgentResponsesErrorResponse) envelope. Typical OAuth codes are `invalid_token` (`401`) and `insufficient_scope` (`403`).

[type definition](/search.md?urn=ctp:api:type:AgentResponsesAuthError).

## Endpoints

The Intake Agent exposes a single, stateless endpoint. Each call starts a fresh workflow run and returns its terminal outcome: either a created entity or an error. Multi-turn conversation is not currently supported by this endpoint.

To call this endpoint, use an API Client with the `manage_intake_agent:{projectKey}` [scope](/api/scopes.md#intake-agent).

### Create a Cart or Quote Request

[endpoint definition](/search.md?urn=ctp:api:endpoint:/{projectKey}/agents/intake/v1/responses:POST).

#### Multipart form data

Send an [AgentResponsesPayload](/search.md?urn=ctp:api:type:AgentResponsesPayload) as a single `payload` part and attach files under `files` parts. Uploading a file under any other field name is rejected with an `InvalidField` error.

You can upload up to 3 files, 20 MB each. The allowed content types are:

- PDF (`application/pdf`)
- Plain text (`text/plain`)
- CSV (`text/csv`)
- DOCX (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`)
- XLSX (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)
- EML (`message/rfc822`)
- Markdown (`text/markdown`)
- HTML (`text/html`)

```bash title="Create a Quote Request with an uploaded file"
curl -X POST https://api.{region}.commercetools.com/{projectKey}/agents/intake/v1/responses 
  -H "Authorization: Bearer {token}" 
  -F 'payload={"outputType":"QuoteRequest","locale":"en-US","prompt":"Quote for the attached purchase order."};type=application/json' 
  -F "files=@purchase-order.pdf"
```

## Error codes

Every workflow run is identified by a `threadId`, which is returned in the [AgentResponsesErrorResponse](/api/agents/intake-agent.md#agentresponseserrorresponse) body on any error raised once the workflow has started. Errors that fail during request parsing, before the workflow starts, don't include it.

For the full list of Intake Agent-specific error codes and their `400` and `500` responses, see [Intake Agent errors](/api/errors.md#intake-agent).

The `ProductsNotFound` code appears as either a `400` error, when none of the requested Products could be matched to the catalog, or as a [warning](/api/agents/intake-agent.md#warnings) on a successful `201` response, when only some Products couldn't be matched.

## Next actions

The created entity is a standard commercetools [Cart](/api/projects/carts.md) or [Quote Request](/api/projects/quote-requests.md), so you can act on it with the regular APIs. For example, you can:

- Review and refine a Cart through the standard [Cart update actions](/api/projects/carts.md#update-actions).
- Create a [Quote Request](/api/projects/quote-requests.md) from a Cart that was created first.
- Delete the entity and start over.

Because each call is stateless, keep the returned `id`, and the `cartId` for a Quote Request, to reference the entity in follow-up API calls.

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Overview](/api/agents/overview.md)
- [Search documentation and API specs](/search.md)