DeepSeek Harness: Erstes Tool entwickeln: defineTool
Tools sind Funktionen, die ein Agent verwendet, um Aufgaben zu erledigen. Nachdem das Modell die Tool-Definition gesehen hat, entscheidet es, ob es sie aufruft.
In diesem Kapitel verwenden wir defineTool, um unser erstes Tool greet zu schreiben und das Modell es tatsächlich aufrufen zu lassen.
Was ist ein Tool?
Ein Tool ist eine klar beschriebene Funktion, die einen Namen, eine Beschreibung, Parameter und ein Ausgabeformat enthält.
Wenn das Modell eine Antwort generiert, kann es Aufrufe basierend auf diesen Informationen durchführen.
In dsh werden Tools über ctx.tools.register in der Tool-Registry registriert.
Die vollständige Struktur von defineTool
defineTool ist eine DSL zum Definieren von Tools. Sie nimmt ein Objekt entgegen, das alle Informationen über das Tool beschreibt.
| Fields | Funktion | Beschreibung |
|---|---|---|
| name | Tool-Name | Das Modell verwendet sie, um Aufrufe zu initiieren. |
| description | Tool-Beschreibung | Teilt dem Modell mit, was dieses Tool tut. |
| parameters | Eingabeparameter-Schema | Typisierte Definition: defineTool leitet args daraus ab und validiert sie. |
| output.schema | Rückgabewert-Schema | Deklariert den kanonischen Werttyp, der von execute zurückgegeben wird. |
| output.render | Ergebnisformatierung | Wandelt kanonische Werte in modellorientierten Inhalt um. |
| execute | Tool-Implementierung | Führt tatsächlich die Logik aus und gibt kanonische Werte zurück. |
Erstelle ein Greet-Tool.
Ersetze scratch-plugin/src/my-plugin.ts durch den folgenden Inhalt.
Beispiel
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-tool'
// Erfordert Tools-Dienst: Voraussetzung für die Registrierung von Tools.
export const inject = ['tools']
export function apply(ctx: Context) {
// Ein Tool namens greet registrieren
ctx.tools.register(defineTool({
// Tool-Name: Das Modell ruft das Tool unter diesem Namen auf
name: 'greet',
// Tool-Beschreibung: Dem Modell sagen, wann es zu verwenden ist
description: 'Jemanden mit Namen begrüßen.',
// Eingabeparameter-Schema: defineTool leitet args ab und validiert sie
parameters: {
name: { type: 'string', required: true, description: 'Der Name zum Begrüßen' },
},
// Ausgabedefinition
output: {
// Werttyp normalisieren: Rückgabewert von execute
schema: { type: 'string' },
// render: Kanonische Werte in modellorientierten Inhalt umwandeln
render: (_args, value) => [{ type: 'text', text: value }],
},
// Tool-Implementierung: Logik tatsächlich ausführen
async execute(args) {
// Gibt einen kanonischen Wert zurück; hier ist es ein String
return `Hello, ${args.name}!`
},
}))
}
inject sorgt dafür, dass Cordis wartet, bis die Tool-Registry bereit ist.
defineTool leitet args basierend auf parameters ab und validiert sie.
execute gibt den kanonischen Wert zurück, der von output.schema deklariert wird.
output.render wandelt dann den kanonischen Wert in Inhalt für das Modell um.
Ausführen und aufrufen
Wenn der Entwicklungsbefehl nicht läuft, starte ihn neu:
pnpm dsh web --patch ./scratch-plugin/cordis.yml
Öffne http://127.0.0.1:3080, gib ein:
Use the greet tool to greet EXAMPLE.
Das Modell kann greet aufrufen und erhält das Tool-Ergebnis Hello, EXAMPLE!.
Wichtig: Das Schema fließt automatisch in den Prompt ein.
Der Name, die Beschreibung, die Parameter und die Ausgabe des Tools werden automatisch in den Modell-Prompt eingebaut.
Das Modell „weiß“, dass ein solches Tool existiert, und wird es zum richtigen Zeitpunkt aufrufen.
Du musst keine Funktionssignaturen für das Modell von Hand schreiben. Das Schema ist die Schnittstelle, die das Modell sieht.
Kanonischer Wert(kanonischer Wert) ist der Wert, der von execute zurückgegeben und in output.schema deklariert wird.
Er ist vom „modellzugewandten Inhalt“ entkoppelt: Derselbe kanonische Wert kann durch verschiedene Render-Funktionen in unterschiedliche Formate umgewandelt werden.
Tipp: Um komplexere Tool-Beispiele zu sehen (verschachtelte Schemata, Hintergrundarbeit, Policy-Hooks), siehe den offiziellen Leitfaden zum Schreiben von Tools.
Zusammenfassung und Selbsttest
defineTool beschreibt das Tool mit einem Schema, ctx.tools.register registriert es, und das Modell ruft es direkt auf, nachdem es das Schema gesehen hat.
Weitere Erweiterungen1. Was gibt execute von defineTool zurück?
2. Was ist der Zweck von output.render?
3. Woher weiß das Modell, dass es greet aufrufen soll?