Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Integrazione di prodotti di agenti AI basati su API ## Linee guida sui prodotti per agenti AI basati su API Marketplace AWS fornisce linee guida per tutti i prodotti agenti AI basati su API Software as a Service (SaaS). Queste linee guida garantiscono un'esperienza sicura e affidabile per i clienti. **Topics** + [Processo di revisione del prodotto](#product-review-process) + [Mantenimento della conformità](#maintaining-compliance) ### Processo di revisione del prodotto Quando invii un prodotto, Marketplace AWS esamina il prodotto e i relativi metadati per verificare che soddisfi le linee guida attuali. Aggiorniamo regolarmente queste linee guida per rispondere all'evoluzione dei requisiti di sicurezza. ### Mantenimento della conformità Marketplace AWS monitora continuamente i prodotti per verificarne la conformità. Se il prodotto non soddisfa le linee guida attuali: + Il prodotto potrebbe non essere disponibile per i nuovi abbonati finché non risolverai i problemi + È necessario aggiornare il prodotto per soddisfare i nuovi requisiti | Categoria | Linee guida | | --- | --- | | Funzionalità dell'API e dell'agente | Tutti APIs dovrebbero essere funzionali e rispondere in modo appropriato. Se stai elencando un agente, la soluzione deve dimostrare capacità autonome operando senza comandi esterni espliciti o input umani costanti. | | Accesso e autenticazione alle API | Il cliente dovrebbe essere in grado di iscriversi alla tua inserzione e recuperare le chiavi API o seguire i passaggi per generare il OAuth token. | | Linee guida sull'architettura | [Segui le linee guida sull'architettura per maggiori dettagli.](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-architecture) | | Requisiti in materia di informazioni | [Segui i requisiti in materia di informazioni per i clienti per maggiori dettagli.](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-customer-information) | | Gestione delle chiavi | I fornitori devono fornire ai clienti la possibilità di utilizzare invalidate/rotate le chiavi. I fornitori dovrebbero inoltre disporre di un meccanismo per invalidare le chiavi una volta che il cliente annulla l'iscrizione all'inserzione. | | Requisiti del server MCP (se applicabile) | Per MCP Server, i fornitori devono fornire i dettagli della configurazione MCP remota insieme a qualsiasi prerequisito o variabile di ambiente per la configurazione. | | Configurazione del prodotto | [Segui le linee guida per la configurazione del prodotto per maggiori dettagli.](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-guidelines-setup) | | Utilizzo del prodotto | [Segui le linee guida sull'utilizzo del prodotto per maggiori dettagli.](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-product-usage) | | Istruzioni per l'uso | Le istruzioni per l'uso devono indicare chiaramente i prerequisiti, la configurazione dell'autenticazione, gli endpoint supportati, request/response lo schema, la descrizione dello strumento, i codici di errore e le risorse aggiuntive. | ## Integrazione di prodotti di agenti AI basati su API ### Integrazione in base al prezzo del prodotto L'integrazione del prodotto con Marketplace AWS è un passaggio per elencare un prodotto agente AI basato su API. Per integrare il tuo prodotto agente AI basato su API con Marketplace AWS, devi scrivere codice e dimostrare che è in grado di rispondere con successo a diversi scenari di clienti. Per informazioni sull'integrazione del prodotto in base a diversi modelli di prezzo, consulta i seguenti argomenti: + Per informazioni sui prodotti in abbonamento, consulta. [Integrazione dell'abbonamento Pay-As-You-Go o del prodotto SaaS con Marketplace AWS](saas-integrate-subscription.md) + Per informazioni sui prodotti basati su contratto, consulta. [Integrazione del prodotto contrattuale SaaS con Marketplace AWS](saas-integrate-contract.md) + Per informazioni sul contratto con pay-as-you-go i prodotti, vedere. [Integrazione del prodotto SaaS basato su contratti con Marketplace AWS](saas-integrate-contract-with-pay.md) ### Onboarding dei clienti #### Reindirizzamento alla pagina di gestione del sito Web Quando i clienti si abbonano al tuo prodotto tramite Marketplace AWS, accedono al prodotto nel tuo ambiente AWS. Dopo l'iscrizione, indirizziamo i clienti al sito Web del prodotto per registrare il proprio account e configurare il prodotto. + Scopri come effettuare l'onboarding dei clienti utilizzando il servizio Reindirizza al sito Web in. [Attivazione dei clienti verso il tuo prodotto SaaS tramite Marketplace AWS](saas-product-customer-setup.md) #### QuickLaunch adempimento Quando i clienti si abbonano al tuo prodotto tramite Marketplace AWS, ricevono una chiave API o OAuth credenziali per effettuare chiamate all'endpoint API o al server MCP. Di seguito è riportato il procedimento: + Il cliente si abbona al prodotto. + Il cliente si iscrive o accede a un account sul tuo sito web. + L'**PutDeploymentParameter**API viene utilizzata per archiviare la chiave API o OAuth le credenziali nel AWS Secrets Manager del cliente. + Se memorizzi un parametro nel caso delle chiavi API, chiama l'`PutDeploymentParameter`API con il `secretString` parametro come stringa. Se memorizzi più di un parametro nel caso delle OAuth credenziali, fornisci una stringa JSON con coppie chiave-valore nel `secretString` parametro come mostrato di seguito: ``` { "Client Id": "{{12345}}", "Client Secret": "{{12345}}", "Discovery URL" : "{{https://auth.example.com/.well-known/openid-configuration}}" } ``` Scopri di più sull' QuickLaunch adempimento in queste risorse: + [Scopri di più sull'**PutDeploymentParameter**API in Deployment Marketplace AWS API](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_Operations_AWS_Marketplace_Deployment_Service.html) + Trova le istruzioni per l'onboarding dei clienti in [Attivazione dei clienti verso il tuo prodotto SaaS tramite Marketplace AWS](saas-product-customer-setup.md) ### Accedendo Marketplace AWS APIs La sezione seguente descrive il processo di integrazione con il Marketplace AWS Metering Service o Marketplace AWS Entitlement Service, utilizzato per garantire che la fatturazione e la rendicontazione relative all'utilizzo dei prodotti da parte dei clienti siano accurate. + Per ulteriori informazioni sull'accesso, consulta. Marketplace AWS APIs [Accesso al servizio Marketplace AWS Metering and Entitlement APIs](saas-integration-metering-and-entitlement-apis.md) ### Notifiche SNS Iscriviti agli argomenti di Amazon Simple Notification Service (Amazon SNS) per ricevere notifiche sulle modifiche all'abbonamento dei clienti e sui diritti contrattuali per i tuoi prodotti. Marketplace AWS fornisce questi argomenti durante la creazione del prodotto per aiutarti a gestire l'accesso dei clienti. I seguenti argomenti di Amazon SNS sono disponibili per i prodotti basati su API SaaS: + [Argomento di Amazon SNS: `aws-mp-entitlement-notification`](saas-notification.md#saas-sns-message-body)— Ti avvisa quando i clienti creano, aggiornano o rinnovano i contratti o quando i contratti scadono. È disponibile solo per i prodotti con modelli di prezzo che includono un contratto. + [Argomento di Amazon SNS: `aws-mp-subscription-notification`](saas-notification.md#saas-sns-subscription-message-body)— Ti avvisa quando i clienti si abbonano o annullano l'iscrizione al tuo prodotto e include il contrassegno `offer-identifier` per le offerte private e un contrassegno per le prove gratuite SaaS. È disponibile per tutti i modelli di prezzo, inclusi contratti e abbonamenti. ## Modelli di istruzioni per l'uso ### Modello di istruzioni per l'utilizzo del server MCP L'esempio seguente illustra le istruzioni d'uso per un server MCP, tra cui descrizioni degli strumenti, prerequisiti, configurazione dell'autenticazione, configurazione per i client più diffusi, limiti di velocità e risorse aggiuntive: ``` To get started using the remove MCP server, follow the instructions below: **Availble Tools** This MCP server support the following tools: - Search - Performs a web search - Summarize Website - Summarizes a webpage **Prerequisites** - Install **Node.js** and **npm** **Authentication** Replace `YOUR_API_KEY` with your actual key below. **Claude Desktop** Edit the configuration file at: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json Add the below code: ``` { "mcpServers": { "demo-example": { "command": "npx", "args": [ "mcp-remote", "https://remote.mcp.server/sse", "--header", "Authorization: Bearer " ] }, } } ``` **Cline** Cline stores MCP server configurations in a JSON file that can be modified. In the "Installed" tab, click "Configure MCP Servers" to access the settings file. Add the following: ``` { "mcpServers": { "demoServer": { "url": "https://remote.mcp.server/sse", "disabled": false, "autoApprove": ["searchWeb", "summarizeWebsite"], "timeout": 30 } } } ``` **Rate Limits** - 60 requests per minute per API key. - Exceeding returns HTTP 429 Too Many Requests. - Use retry and exponential backoff to handle limits. **Learn More** MCP Docs: https://mcp.search.demoproduct.com ``` ### Modello di istruzioni per l'utilizzo di AI Agent e Agent & Tools L'esempio seguente illustra le istruzioni di utilizzo per uno o più strumenti dell'agente, inclusi prerequisiti, configurazione dell'autenticazione, endpoint supportati, request/response schema, codici di errore e risorse aggiuntive: ``` To get started follow the instructions below: **Authentication** All API requests require this HTTP header: Authorization: Bearer `YOUR_API_KEY` Replace `YOUR_API_KEY` with your actual key. **Search Endpoint** **Endpoint:** `GET /web/search` Performs a web search. **Query Parameters:** | Param | Type | Description | |------------|--------|-------------------------------------| | `q` | string | Your search query (required) | | `count` | int | Number of results (default: 10) | | `offset` | int | Offset for pagination | | `country` | string | Country code (e.g. `us`, `de`) | | `safesearch` | string | `off`, `moderate`, or `strict` | **Example Request:** ```bash curl -X GET "https://api.search.demo.com/res/v1/web/search?q=searchtool" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response Schema:** ``` { "results": [{ "title": "string", "url": "string", "description": "string" }], "query" :"string", "total" :"number" } ``` **Example Response:** ``` { "results": [ { "title": "DemoProductAPI", "url": "https://demo.com", "description": "Demo Product API is a search tool for..." } ], "query": "searchtool", "total": 1 } ``` **Additional Search Types** DemoProduct also supports: - `GET /news/search – News articles` - `GET /images/search – Image results` - `GET /videos/search – Video results` These endpoints follow the same format as /web/search. **Summarize Endpoint** **Endpoint:** `POST /summarize` Summarizes a webpage **Request Headers:** Content Type: application/json **Request Body:** ``` { "input": "string" // URL or plain text } ``` **Example Request:** ``` { "input": "https://example.com/article" } ``` **Response Schema** ``` { "summary": "string" } ``` **Example Response** ``` { "summary": "This article explains our commitment to user privacy." } ``` **Error Codes** | Status | Meaning | | ------ | ------------------------------ | | `401` | Unauthorized (check your key) | | `429` | Too many requests (rate limit) | | `500` | Server error | All error responses follow this structure: ``` { "error": { "code": 401, "message": "Unauthorized" } } ``` **Rate Limits** - 60 requests per minute per API key. - Exceeding returns HTTP 429 Too Many Requests. - Use retry and exponential backoff to handle limits. **Learn More** API Docs: https://api.search.demoproduct.com ```