DeepSeek Harness desarrollo de la primera herramienta: defineTool
Una herramienta es una función que el Agente usa para trabajar; el modelo decide llamarla después de ver la definición de la herramienta.
En este capítulo usaremos defineTool para escribir la primera herramienta greet y haremos que el modelo realmente la llame.
¿Qué es una herramienta?
Una herramienta (tool) es una función claramente descrita que incluye nombre, descripción, parámetros y formato de salida.
Al generar una respuesta, el modelo puede realizar una llamada basándose en esta información.
En dsh, las herramientas se registran en el registro de herramientas mediante ctx.tools.register.
La estructura completa de defineTool
defineTool es un DSL para definir herramientas; recibe un objeto que describe toda la información de la herramienta.
| Campo | Función | Descripción |
|---|---|---|
| name | Nombre de la herramienta | El modelo lo usa para realizar llamadas |
| description | Descripción de la herramienta | Le dice al modelo qué hace esta herramienta |
| parameters | Schema de parámetros de entrada | Definición tipada; defineTool deduce y valida args a partir de ella |
| output.schema | Schema del valor de retorno | Declara el tipo del valor canónico devuelto por execute |
| output.render | Formateo de resultados | Convierte el valor canónico en contenido orientado al modelo |
| execute | Implementación de la herramienta | Ejecuta la lógica real y devuelve el valor canónico |
Crear la herramienta greet
Reemplaza scratch-plugin/src/my-plugin.ts con el siguiente contenido.
Ejemplo
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-tool'
// Se necesita el servicio tools: requisito previo para registrar herramientas
export const inject = ['tools']
export function apply(ctx: Context) {
// Registra una herramienta llamada greet
ctx.tools.register(defineTool({
// Nombre de la herramienta: el modelo llamará con este nombre
name: 'greet',
// Descripción de la herramienta: le dice al modelo cuándo usarla
description: 'Greet someone by name.',
// Schema de entrada: defineTool deduce y valida args
parameters: {
name: { type: 'string', required: true, description: 'The name to greet' },
},
// Definición de salida
output: {
// Tipo de valor canónico: valor de retorno de execute
schema: { type: 'string' },
// render: convierte el valor canónico en contenido orientado al modelo
render: (_args, value) => [{ type: 'text', text: value }],
},
// Implementación de la herramienta: ejecuta la lógica real
async execute(args) {
// Devuelve el valor canónico; aquí es una cadena
return `Hello, ${args.name}!`
},
}))
}
inject hace que Cordis espere hasta que el registro de herramientas esté listo.
defineTool deduce y valida args según parameters.
execute devuelve el valor canónico declarado por output.schema.
output.render convierte el valor canónico en contenido orientado al modelo.
Ejecutar y llamar
Si el comando de desarrollo no se está ejecutando, reinícialo:
pnpm dsh web --patch ./scratch-plugin/cordis.yml
Abre http://127.0.0.1:3080 e ingresa:
Use the greet tool to greet EJEMPLO.
El modelo puede llamar a greet y recibe como resultado de la herramienta: Hello, EJEMPLO!
Punto clave: el schema fluye automáticamente al prompt
El name, description, parameters y output de la herramienta se ensamblan automáticamente en el prompt del modelo.
Cuando el modelo «sabe» que existe esta herramienta, la llamará en el momento adecuado.
No necesitas escribir manualmente la firma de la función para el modelo; el schema es la interfaz que ve el modelo.
Valor canónico(canonical value) es el valor devuelto por execute y declarado por output.schema.
Está desacoplado del «contenido orientado al modelo»: el mismo valor canónico puede convertirse en diferentes formatos mediante distintos render.
Consejo: para ver ejemplos más complejos de escritura de herramientas (schemas anidados, trabajos en segundo plano, hooks de políticas), consulta la referencia oficial de escritura de herramientas.
Resumen y autoevaluación
defineTool describe la herramienta con un schema, ctx.tools.register la registra, y el modelo la llama directamente al ver el schema.
Otras extensiones1. ¿Qué devuelve execute de defineTool?
2. ¿Cuál es la función de output.render?
3. ¿Cómo sabe el modelo que debe llamar a greet?