Laravel AI SDK 1.1 aggiunge Agent Skills e Cohere Chat

Laravel AI SDK v1.1.0 è la prima minor release dopo la 1.0 e aggiunge il supporto allo standard Agent Skills. Introduce anche Cohere come provider di testo e permette di richiedere l'approvazione sui tool integrati dell'SDK. Inoltre, il failover tra provider non si interrompe più quando il provider successivo non supporta uno dei provider tool dell'agente.

Novità

Agent Skills

L'SDK ora supporta Agent Skills, il formato a cartelle che i coding agent usano per caricare le istruzioni solo quando un'attività le richiede. Pushpak Chhajed osserva nella PR che il team aveva rifiutato il supporto agli skills già due volte, ma il formato è ormai uno standard usato da molti strumenti.

Ogni skill è una cartella sotto resources/skills con un file SKILL.md. Il frontmatter richiede una description. Il name è opzionale e assume per default il nome della cartella:

resources/skills/
└── refund-policy/
├── SKILL.md
└── references/EDGE-CASES.md

---
name: refund-policy
description: Use when a customer asks for a refund or a partial credit.
---

Check the order date first. Orders older than 30 days...

Per assegnare degli skills a un agente, implementa il nuovo contratto HasSkills. L'agente ottiene un unico tool LoadSkill che elenca il nome e la descrizione di ogni skill. Il modello chiama il tool per leggere le istruzioni complete di uno skill e lo richiama con un percorso per leggere uno dei file inclusi in quello skill:

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasSkills;
use Laravel\Ai\Promptable;
use Laravel\Ai\Skills\Skill;

class SupportAgent implements Agent, HasSkills
{
use Promptable;

public function instructions(): string
{
return 'You are a support agent.';
}

public function skills(): iterable
{
return [
resource_path('skills'),
base_path('.agents/skills'),
new Skill(
name: 'house-style',
description: 'Use when you write copy for a customer.',
instructions: view('skills.house-style', ['brand' => $this->brand]),
),
fn () => $this->user->team->skills->map->toSkill(),
];
}
}

Una sorgente può essere una directory, un oggetto Skill costruito in PHP oppure una closure. L'SDK esegue la closure la prima volta che il tool legge i suoi skill, così puoi caricare gli skill dal database per ogni utente. Puntare a .agents/skills permette agli agenti della tua app di usare gli stessi skill del tuo coding agent.

Puoi anche aggiungere new LoadSkill([...]) direttamente ai tools() di un agente. Se un agente ha entrambi, l'SDK unisce gli skills nell'unico tool e registra un warning nel log, perché i provider rifiutano nomi di tool duplicati. Il tool legge i file inclusi solo dall'interno della cartella dello skill e rifiuta i file più grandi di 256 KB e i file binari.

PR: #1054, #1102

Generazione di testo con Cohere

Cohere era già disponibile per gli embeddings e il reranking. Mojtaba Sayari ha aggiunto la generazione di testo tramite la v2 Chat API di Cohere, con supporto per streaming, tool call, output strutturato e reasoning:

$response = (new SupportAgent)->prompt('Hello', provider: 'cohere');

Il modello predefinito è command-a-03-2025. Cohere non può forzare uno strumento specifico, quindi ToolChoice::tool('X') invia solo il tool X e contrassegna una tool call come obbligatoria. Gli allegati di documenti e le citazioni non sono ancora supportati, ma puoi passare opzioni di Cohere come documents e safety_mode tramite le provider options.

PR: #1078

Approvazione per i tool integrati

I tool MCP, agent, similarity search e filesystem ora implementano il contratto Approvable, quindi puoi chiamare requireApproval() su di essi. Prima di questa release dovevi estendere un tool per applicare un controllo. Questo esempio richiede l'approvazione per ogni tool MCP di GitHub non contrassegnato come read-only:

use Laravel\Ai\Tools\McpTool;

$github->tools()
->mapInto(McpTool::class)
->map(fn (McpTool $tool) => ($tool->annotations()['readOnlyHint'] ?? false)
? $tool
: $tool->requireApproval());

L'approvazione è disattivata per default, quindi gli agenti esistenti si comportano allo stesso modo. Consulta il nostro precedente articolo su human-in-the-loop tool approval per capire come funzionano le approvazioni.

PR: #1097

Il failover salta i provider tool non supportati

Prima di questa release, un provider tool non supportato dal provider successivo poteva interrompere un'esecuzione di failover. Per esempio, un agente con WebFetch e WebSearch su ['anthropic', 'openai'] falliva quando una richiesta ad Anthropic bloccata dal rate limit passava a OpenAI, perché OpenAI generava un'eccezione su WebFetch:

RuntimeException: Provider [openai] does not support the [WebFetch] tool.

Il ciclo di generazione di testo ora rimuove i provider tool che il provider corrente non supporta prima di ogni tentativo, così l'esecuzione prosegue solo con WebSearch. Su un provider privo di ricerca dei tool ospitata, l'SDK elimina il wrapper ToolSearch e invia i suoi tool come tool normali. Più di un wrapper ToolSearch genera comunque un'eccezione su ogni provider.

PR: #1080

Classificazione con Laya self-hosted

Ora puoi eseguire la classificazione su un server Laya self-hosted con il driver typesafe esistente. Aggiungi una connessione con un url locale:

'laya' => [
'driver' => 'typesafe',
'key' => env('LAYA_API_KEY', ''),
'url' => env('LAYA_URL', 'http://localhost:8000/v1'),
'models' => ['classification' => ['default' => 'auto']],
],

Classification::of($ticket)->questions($questions)->classify(provider: 'laya');

I metadati della risposta indicano il checkpoint Laya che ha risposto alla richiesta. Abbiamo parlato di Laya e di un client PHP standalone nel nostro post su LayaPHP.

PR: #1081

Altri provider tool

ToolSearch ora funziona su Azure OpenAI. Su Groq, WebSearch viene mappato su browser_search di Groq e CodeExecution su code_interpreter. Groq offre entrambi solo sui suoi modelli GPT-OSS e ignora le opzioni max(), allow() e location() di WebSearch. Ora WebSearch invia la sua location anche a OpenRouter.

PR: #1098, #1099

Altre modifiche

• Tool MoveFile: Gli agenti possono rinominare o spostare un file con una sola tool call invece di copiarlo e poi eliminare l'originale (#1092).
• Modelli predefiniti: I modelli di fallback sono stati aggiornati per la maggior parte dei provider. Per esempio, Anthropic ora usa come default claude-sonnet-5-5 e Gemini gemini-3.8-flash. Se ti affidi ai default invece di impostare i modelli in config/ai.php, dopo l'aggiornamento la tua app userà i modelli più recenti (#1095).
• Correzioni: il replay della ricerca file stateless di OpenAI (#1089), un messaggio utente di useChat modificato che veniva sostituito dalla risposta dell'assistente (#1076) e i parametri di query di ElevenLabs inviati nel posto sbagliato (#1103).
• Guida all'aggiornamento: La guida all'upgrade alla 1.0 ora specifica che il comando di upgrade di Boost richiede laravel/boost 2.10.0 o successivo e che l'SDK è in conflitto con laravel/mcp precedente alla 1.0 (#1087).

Aggiornamento

Per aggiornare un'app esistente, richiedi la nuova versione con Composer:

composer require laravel/ai:^1.1

Riferimenti

• Note di rilascio della v1.1.0
• Changelog completo
• Documentazione dell'AI SDK