Zum Hauptinhalt springen

​
Tools

Die integrierten Tools der Copilot CLI sind standardmäßig aktiviert. An dieser Stelle geben Sie ausschließlich benutzerdefinierte Tools an.

​
Grundlegende Verwendung

Definieren Sie die Tools in tools von SessionConfig. Tool::define() ist ein Helper analog zu defineTool anderer Sprachversionen. Für parameters können Sie das von Laravel selbst in Laravel MCP verwendete JsonSchema nutzen. Alternativ ist auch die direkte Angabe eines Arrays möglich. 
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, // Bei true wird ohne Berechtigungsprompt ausgeführt
                defer: 'auto', // Steuert, ob das Tool nicht immer vorgeladen, sondern lazy geladen wird (Lazy-Load per Tool-Suche). Bei `"auto"` wird das Tool lazy geladen und über die Tool-Suche sichtbar. Bei `"never"` wird das Tool immer vorgeladen. Optional. Standard ist `"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

Mit skipPermission: true können Sie das entsprechende Tool ohne Berechtigungsprompt ausführen. 
Tool::define(
    name: 'read_only_lookup',
    description: 'Read-only data lookup.',
    parameters: $parameters,
    handler: fn ($params) => ['result' => 'data'],
    skipPermission: true,
),

​
$invocation

Dem zweiten Argument $invocation des Tool-Handlers werden die folgenden Felder übergeben. 
[
    'sessionId'  => '...',
    'toolCallId' => '...',
    'toolName'   => 'lookup_fact',
    'arguments'  => [...], // Tool-Argumente (identisch mit $params)
    // Nur enthalten, wenn OpenTelemetry aktiv ist
    'traceparent' => '...', // W3C Trace Context traceparent
    'tracestate'  => '...', // W3C Trace Context tracestate
]

​
Protokoll-Details

Ab Protocol v3 (aktueller Standard) werden Tool-Aufrufe nicht als JSON-RPC-Requests, sondern als Session-Events (external_tool.requested) gesendet. Das SDK verarbeitet dieses Event intern und antwortet mit dem RPC session.tools.handlePendingToolCall. Die Verwendung von SessionConfig ändert sich dadurch nicht. Sie übergeben lediglich die Definitionen an tools, und die Protokollunterschiede fängt das SDK ab.

​
Umwandlung eines MCP-CallToolResult

Um ein Tool-Ergebnis eines MCP-Servers (CallToolResult) in ein ToolResultObject des Copilot SDK zu konvertieren, verwenden Sie McpCallToolResult::convert(). Die Ergebnisse von MCP-Tools sind ein Array von content-Blöcken (text/image/resource), das Copilot SDK erwartet jedoch das ToolResultObject-Format, daher ist die Umwandlung erforderlich. 
use Revolution\Copilot\Support\McpCallToolResult;

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

// In das ToolResultObject-Format des Copilot SDK umwandeln
$toolResult = McpCallToolResult::convert($mcpResult);
// $toolResult->textResultForLlm => 'File contents here'
// $toolResult->resultType => 'success'
// $toolResult->binaryResultsForLlm => [['data' => 'base64...', 'mimeType' => 'image/png', 'type' => 'image']]
Aktuelle Informationen finden Sie im GitHub-Repository.
Zuletzt geändert am 13. Juli 2026

Verwandte Themen

Laravel AI SDKSession-HooksStreaming-EreignisseLaravel MCPBenutzerdefinierte Agenten