Skills e Tools

// skills/weather.ts
export const weatherSkill = {
  name: "get_weather",
  description: "Consulta previsao do tempo para uma cidade. " +
    "Use quando o usuario perguntar sobre clima, " +
    "temperatura ou previsao meteorologica.",
  parameters: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "Nome da cidade (ex: 'Sao Paulo')"
      },
      days: {
        type: "number",
        description: "Dias de previsao (1-7)",
        default: 1
      }
    },
    required: ["city"]
  },
  execute: async ({ city, days = 1 }) => {
    const res = await fetch(
      `https://api.weather.com/forecast?city=${city}&days=${days}`
    );
    const data = await res.json();
    return {
      city: data.city,
      temperature: data.temp,
      condition: data.condition,
      forecast: data.daily.slice(0, days)
    };
  }
};

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Termo de busca para filtrar clientes"
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "trial"],
      "description": "Filtrar por status da conta"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 10,
      "description": "Numero maximo de resultados"
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Incluir clientes deletados"
    }
  },
  "required": ["query"]
}

// 1. Definir tools no request
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Qual o clima em SP hoje?" }
  ],
  tools: [{
    type: "function",
    function: {
      name: "get_weather",
      description: "Consulta clima atual de uma cidade",
      parameters: {
        type: "object",
        properties: {
          city: { type: "string" }
        },
        required: ["city"]
      }
    }
  }]
});

// 2. LLM retorna tool_call (nao texto!)
// response.choices[0].message.tool_calls = [{
//   id: "call_abc123",
//   function: { name: "get_weather", arguments: '{"city":"Sao Paulo"}' }
// }]

// 3. Executar funcao e retornar resultado
const weatherData = await getWeather("Sao Paulo");

// 4. Enviar resultado de volta ao LLM
const finalResponse = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Qual o clima em SP hoje?" },
    response.choices[0].message, // inclui tool_calls
    { role: "tool", tool_call_id: "call_abc123",
      content: JSON.stringify(weatherData) }
  ]
});
// 5. LLM gera: "Em Sao Paulo esta 24°C com ceu parcialmente nublado."

// Usuario: "Qual o clima em SP e no Rio?"
// LLM retorna 2 tool_calls em paralelo:
tool_calls: [
  { id: "call_1", function: { name: "get_weather",
    arguments: '{"city":"Sao Paulo"}' }},
  { id: "call_2", function: { name: "get_weather",
    arguments: '{"city":"Rio de Janeiro"}' }}
]
// Ambas executam ao mesmo tempo, resultados voltam juntos

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  response_format: { type: "json_object" },
  messages: [{
    role: "system",
    content: "Retorne sempre um JSON com campos: name, price, available"
  }, {
    role: "user",
    content: "Quero info sobre o Plano Pro"
  }]
});

const data = JSON.parse(response.choices[0].message.content);
// Garante JSON valido, mas nao garante o schema exato

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "product_info",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          price: { type: "number" },
          available: { type: "boolean" },
          trial_days: { type: "integer" }
        },
        required: ["name", "price", "available", "trial_days"],
        additionalProperties: false
      }
    }
  },
  messages: [{ role: "user", content: "Info do Plano Pro" }]
});
// Garante que o JSON segue EXATAMENTE o schema definido

import { z } from "zod";

// Definir schema com Zod
const ProductSchema = z.object({
  name: z.string(),
  price: z.number().positive(),
  available: z.boolean(),
  trial_days: z.number().int().min(0).max(90)
});

type Product = z.infer<typeof ProductSchema>;

// Validar resposta do LLM
const raw = JSON.parse(llmResponse);
const product = ProductSchema.parse(raw);
// Se invalido, Zod lanca erro com detalhes do que falhou
// Se valido, 'product' tem type safety completa

skills/
  weather/
    index.ts          # Exporta a skill registrada
    schema.ts         # JSON Schema dos parametros
    handler.ts        # Logica de execucao
    handler.test.ts   # Testes unitarios do handler
    types.ts          # TypeScript types (input/output)
    README.md         # Documentacao da skill
  database/
    index.ts
    schema.ts
    handler.ts
    handler.test.ts
    types.ts
  index.ts            # Registry: exporta todas as skills
  register.ts         # Funcao de registro de skills no agente

// skills/register.ts
import { Tool } from "./types";

class SkillRegistry {
  private skills: Map<string, Tool> = new Map();

  register(skill: Tool) {
    if (this.skills.has(skill.name)) {
      throw new Error(`Skill "${skill.name}" ja registrada`);
    }
    this.skills.set(skill.name, skill);
  }

  get(name: string): Tool | undefined {
    return this.skills.get(name);
  }

  // Retorna schemas para enviar ao LLM
  getSchemas() {
    return Array.from(this.skills.values()).map(s => ({
      type: "function",
      function: {
        name: s.name,
        description: s.description,
        parameters: s.parameters
      }
    }));
  }

  // Executa uma skill por nome
  async execute(name: string, args: unknown) {
    const skill = this.skills.get(name);
    if (!skill) throw new Error(`Skill "${name}" nao encontrada`);
    try {
      return await skill.execute(args);
    } catch (error) {
      return { error: true, message: error.message };
    }
  }
}

export const registry = new SkillRegistry();

// skills/database/handler.ts
export async function queryDatabase(args: QueryInput) {
  try {
    const results = await db.query(args.sql, args.params);
    return {
      success: true,
      rows: results.rows,
      count: results.rowCount
    };
  } catch (error) {
    // Retornar erro estruturado, nao lancar excecao
    return {
      success: false,
      error: error.message,
      code: error.code,
      hint: error.code === "42P01"
        ? "Tabela nao existe. Verifique o nome."
        : "Erro na query SQL. Verifique a sintaxe."
    };
  }
}

// skills/weather/handler.test.ts
import { describe, it, expect } from "vitest";
import { getWeather } from "./handler";

describe("Weather Skill", () => {
  it("retorna dados para cidade valida", async () => {
    const result = await getWeather({ city: "Sao Paulo" });
    expect(result.success).toBe(true);
    expect(result.temperature).toBeDefined();
    expect(typeof result.temperature).toBe("number");
  });

  it("retorna erro para cidade invalida", async () => {
    const result = await getWeather({ city: "XYZ123" });
    expect(result.success).toBe(false);
    expect(result.error).toBeDefined();
  });

  it("respeita limite de dias", async () => {
    const result = await getWeather({ city: "SP", days: 3 });
    expect(result.forecast.length).toBeLessThanOrEqual(3);
  });
});

// skills/search-customers/index.ts
import { z } from "zod";

// 1. Schema de Input
const InputSchema = z.object({
  query: z.string().describe("Termo de busca por nome ou email"),
  status: z.enum(["active", "inactive", "trial"])
    .optional()
    .describe("Filtrar por status"),
  limit: z.number().min(1).max(100).default(10)
    .describe("Maximo de resultados")
});

// 2. Schema de Output
const OutputSchema = z.object({
  success: z.boolean(),
  customers: z.array(z.object({
    id: z.string(),
    name: z.string(),
    email: z.string(),
    plan: z.string(),
    status: z.string()
  })),
  total: z.number()
});

// 3. Tool Definition (para enviar ao LLM)
export const searchCustomersTool = {
  type: "function" as const,
  function: {
    name: "search_customers",
    description: "Busca clientes no banco de dados por nome, " +
      "email ou ID. Use quando o usuario perguntar sobre " +
      "um cliente especifico ou pedir uma lista filtrada.",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string",
          description: "Termo de busca" },
        status: { type: "string",
          enum: ["active", "inactive", "trial"] },
        limit: { type: "integer", default: 10,
          minimum: 1, maximum: 100 }
      },
      required: ["query"]
    }
  }
};

// 4. Handler
export async function searchCustomers(raw: unknown) {
  const args = InputSchema.parse(raw);
  try {
    const results = await db.customers.findMany({
      where: {
        OR: [
          { name: { contains: args.query } },
          { email: { contains: args.query } }
        ],
        ...(args.status && { status: args.status })
      },
      take: args.limit
    });
    return OutputSchema.parse({
      success: true,
      customers: results,
      total: results.length
    });
  } catch (error) {
    return { success: false, error: error.message,
      customers: [], total: 0 };
  }
}