Outils

Les outils intégrés du Copilot CLI sont activés par défaut. Ce que vous configurez ici, ce sont des outils personnalisés.

Utilisation de base

Spécifiez la définition des outils dans tools de SessionConfig. Tool::define() est un helper équivalent à defineTool dans d’autres versions linguistiques. Le paramètre parameters accepte le JsonSchema utilisé par Laravel MCP. Vous pouvez aussi passer directement un tableau sans JsonSchema.

use Illuminate\Support\Facades\Artisan;
use Illuminate\JsonSchema\JsonSchema;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\Tool;
use Revolution\Copilot\Types\ToolResultObject;

use function Laravel\Prompts\{info, note, spin, warning};

Artisan::command('copilot:tools', function () {
    $facts = [
        'PHP' => 'A popular general-purpose scripting language that is especially suited to web development.',
        'Laravel' => 'A web application framework with expressive, elegant syntax.',
    ];

    $parameters = JsonSchema::object(
        properties: [
            'topic' => JsonSchema::string()
                ->description('Topic to look up (e.g., "PHP", "Laravel")')
                ->required(),
        ],
    )->toArray();

    $config = new SessionConfig(
        tools: [
            Tool::define(
                name: 'lookup_fact',
                description: 'Returns a fun fact about a given topic.',
                parameters: $parameters,
                handler: function (array $params, array $invocation) use ($facts): array {
                    $topic = $params['topic'] ?? '';

                    $fact = $facts[$topic] ?? null;

                    if (! $fact) {
                        return new ToolResultObject(
                            textResultForLlm: "No fact stored for {$topic}.",
                            resultType: 'failure',
                            sessionLog: "lookup_fact: missing topic {$topic}",
                            toolTelemetry: [],
                        );
                    }

                    return new ToolResultObject(
                        textResultForLlm: $fact,
                        resultType: 'success',
                        sessionLog: "lookup_fact: served {$topic}",
                        toolTelemetry: [],
                    );
                },
                overridesBuiltInTool: false,
                skipPermission: false, // À true, exécute sans prompt de permission
                defer: 'auto', // Contrôle si l'outil est préchargé en permanence ou chargé paresseusement (via la découverte d'outils). `"auto"` : chargé paresseusement, révélé par la découverte d'outils. `"never"` : toujours préchargé. Optionnel, défaut `"auto"`.
            ),
        ],
    );

    Copilot::start(function (CopilotSession $session) {
        info('Starting Copilot with tools: '.$session->id());

        $prompt = 'You can call the lookup_fact tool. Use lookup_fact to tell me something about Laravel.';

        warning($prompt);

        $response = spin(
            callback: fn () => $session->sendAndWait($prompt),
            message: 'Copilot thinking...',
        );

        note($response->content());
    }, config: $config);
});

skipPermission

Avec skipPermission: true, l’outil s’exécute sans prompt de permission.

Tool::define(
    name: 'read_only_lookup',
    description: 'Read-only data lookup.',
    parameters: $parameters,
    handler: fn ($params) => ['result' => 'data'],
    skipPermission: true,
),

$invocation

Le second argument du gestionnaire d’outil, $invocation, reçoit les champs suivants.

[
    'sessionId'  => '...',
    'toolCallId' => '...',
    'toolName'   => 'lookup_fact',
    'arguments'  => [...], // Arguments de l'outil (identiques à $params)
    // Uniquement si OpenTelemetry est activé
    'traceparent' => '...', // W3C Trace Context traceparent
    'tracestate'  => '...', // W3C Trace Context tracestate
]

Détails du protocole

En Protocol v3 (défaut actuel), les appels d’outils sont diffusés comme des événements de session (external_tool.requested) plutôt que comme des requêtes JSON-RPC. Le SDK traite ces événements en interne et répond via le RPC session.tools.handlePendingToolCall. L’usage de SessionConfig est inchangé. Il suffit de passer les définitions à tools, le SDK absorbe les différences de protocole.

Convertir un CallToolResult MCP

Pour convertir un résultat d’outil d’un serveur MCP (CallToolResult) en ToolResultObject du Copilot SDK, utilisez McpCallToolResult::convert(). Les résultats d’outils MCP sont un tableau de blocs content (text, image, resource, etc.), mais le Copilot SDK attend un ToolResultObject, d’où la conversion.

use Revolution\Copilot\Support\McpCallToolResult;

// Format CallToolResult de MCP
$mcpResult = [
    'content' => [
        ['type' => 'text', 'text' => 'File contents here'],
        ['type' => 'image', 'data' => 'base64...', 'mimeType' => 'image/png'],
    ],
    'isError' => false,
];

// Conversion au format ToolResultObject du Copilot SDK
$toolResult = McpCallToolResult::convert($mcpResult);
// $toolResult->textResultForLlm => 'File contents here'
// $toolResult->resultType => 'success'
// $toolResult->binaryResultsForLlm => [['data' => 'base64...', 'mimeType' => 'image/png', 'type' => 'image']]

Pour les dernières informations, consultez le dépôt GitHub.

​Outils

​Utilisation de base

​skipPermission

​$invocation

​Détails du protocole

​Convertir un CallToolResult MCP

Outils

Utilisation de base

skipPermission

$invocation

Détails du protocole

Convertir un CallToolResult MCP