76 lines
3.9 KiB
Plaintext
76 lines
3.9 KiB
Plaintext
Sviluppa **ApiPilot**, una libreria Python riutilizzabile che trasforma operazioni di un’applicazione FastAPI in tool eseguibili da agenti AI. La libreria non deve contenere riferimenti a progetti, API o domini applicativi specifici.
|
||
|
||
## Obiettivo
|
||
|
||
Lo sviluppatore abilita un endpoint esistente tramite `x-apipilot` nel decorator FastAPI. ApiPilot genera le definizioni dei tool, valida ed esegue le chiamate e restituisce risultati strutturati. L’agente decide quando usare un tool; ApiPilot ne gestisce l’esecuzione.
|
||
|
||
## Prima di implementare
|
||
|
||
Esamina struttura del repository, versioni Python e FastAPI, convenzioni di autenticazione e test. Definisci un piano breve e segui le convenzioni del progetto.
|
||
|
||
## Interfaccia desiderata
|
||
|
||
```python
|
||
from apipilot.fastapi import install_apipilot
|
||
|
||
pilot = install_apipilot(
|
||
app,
|
||
get_current_user=get_current_user,
|
||
)
|
||
|
||
tools = pilot.tools_for(user)
|
||
result = await pilot.execute(
|
||
user=user,
|
||
name="list_items",
|
||
arguments={"category": "active"},
|
||
)
|
||
```
|
||
|
||
Un endpoint deve poter essere abilitato così:
|
||
|
||
```python
|
||
@router.get(
|
||
"/items",
|
||
summary="Elenca gli elementi",
|
||
openapi_extra={
|
||
"x-apipilot": {
|
||
"enabled": True,
|
||
"name": "list_items",
|
||
"description": (
|
||
"Cerca gli elementi disponibili. Usalo quando "
|
||
"l'utente chiede un elenco o cerca elementi "
|
||
"di una categoria."
|
||
),
|
||
}
|
||
},
|
||
)
|
||
async def list_items(category: str | None = None):
|
||
...
|
||
```
|
||
|
||
Puoi migliorare l’interfaccia proposta se trovi una soluzione più semplice, mantenendo documentate le scelte.
|
||
|
||
## Requisiti
|
||
|
||
1. Leggi l’OpenAPI generato dall’app FastAPI e registra solo le operazioni con `x-apipilot.enabled: true`.
|
||
2. Genera nome, descrizione e schema JSON dei parametri nel formato function calling compatibile OpenAI. Supporta parametri di path, query e body. Non esporre al modello credenziali o header tecnici.
|
||
3. Rileva nomi duplicati, configurazioni incomplete e schemi non supportati con errori chiari.
|
||
4. Implementa `tools_for(user)` e `execute(user, name, arguments)`.
|
||
5. Esegui solo tool registrati. Valida gli argomenti e applica l’autenticazione e i permessi dell’app ospite. Il modello non deve poter scegliere liberamente URL, metodo HTTP o credenziali.
|
||
6. Gestisci timeout, errori degli endpoint, risultati vuoti e risposte troppo grandi. Restituisci errori strutturati.
|
||
7. Permetti di registrare tool Python composti che eseguono più passaggi e non corrispondono a un singolo endpoint OpenAPI.
|
||
8. Mantieni separati il nucleo di ApiPilot e gli adapter per specifici provider LLM. Implementa un adapter iniziale per il formato tool calling compatibile OpenAI, incluso il collegamento tra risultato e `tool_call_id`.
|
||
9. Se esponi catalogo ed esecuzione via HTTP, rendili opzionali e documenta autenticazione e contratto delle richieste.
|
||
|
||
## Documentazione per gli agenti di sviluppo
|
||
|
||
Genera nella radice del repository **`AGENT.md` e `CLAUDE.md`**. Devono contenere istruzioni pratiche e coerenti per chi sviluppa ApiPilot con agenti di coding: architettura e confini dei moduli, comandi di installazione e test, convenzioni del codice, requisiti di sicurezza, criteri per aggiungere adapter e regole per aggiornare documentazione e test. Evita duplicazioni divergenti: `CLAUDE.md` può rimandare ad `AGENT.md` e aggiungere solo istruzioni specifiche, se necessarie.
|
||
|
||
## Verifica e consegna
|
||
|
||
Aggiungi test per selezione delle operazioni, conversione dei parametri, autorizzazione, rifiuto di tool sconosciuti, argomenti invalidi, gestione degli errori e tool composti. Usa una piccola app FastAPI di esempio, senza dipendenze da sistemi esterni.
|
||
|
||
Consegna codice installabile, README con esempi di integrazione, formato documentato di `x-apipilot`, `AGENT.md`, `CLAUDE.md` e comandi per eseguire i test. Evita comportamenti o nomi legati a una singola applicazione.
|
||
|
||
Includi anche un esempio demo di un FastAPI backend che usa apipilot
|