Pular para o conteúdo
Guida

Ferramentas personalizadas

Ferramentas personalizadas permitem estender o servidor MCP do Guida com funcionalidade específica do espaço de trabalho. Defina ferramentas em tools.json e qualquer agente de IA conectado poderá invocá-las.

Configuração

Seção intitulada “Configuração”

Crie um arquivo tools.json na raiz do espaço de trabalho:

{
  "tools": [
    {
      "name": "search-products",
      "description": "Search the product catalog by keyword",
      "script": "scripts/search-products.js",
      "timeout": 30,
      "parameters": {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "string",
            "description": "Search keyword"
          },
          "maxResults": {
            "type": "number",
            "description": "Maximum results to return (default: 10)"
          }
        },
        "required": ["keyword"]
      }
    }
  ]
}

Campos da ferramenta

Seção intitulada “Campos da ferramenta”
CampoObrigatórioDescrição
nameSimNome da ferramenta exposto via MCP; deve ser único
descriptionSimDescrição legível exibida nas listagens de ferramentas
scriptSimCaminho do script relativo à raiz do espaço de trabalho
timeoutNãoTimeout de execução em segundos
parametersNãoJSON Schema descrevendo parâmetros de entrada
headersNãoCabeçalhos HTTP injetados em chamadas g.http.makeHttpRequest()

Esquemas de parâmetros

Seção intitulada “Esquemas de parâmetros”

O campo parameters usa JSON Schema para descrever as entradas da ferramenta. O agente de IA vê o esquema e fornece argumentos compatíveis.

Dentro do script, parâmetros ficam disponíveis em g.tool.args:

async function main() {
  const keyword = g.tool.args.keyword;
  const maxResults = g.tool.args.maxResults || 10;


  await g.nav.navigateToUrl("https://store.example.com/search?q=" + keyword);
  // ... extrair resultados ...


  return results.slice(0, maxResults);
}

O valor retornado pela função main() vira o resultado da ferramenta, enviado de volta ao agente de IA.

Cabeçalhos apoiados por credenciais

Seção intitulada “Cabeçalhos apoiados por credenciais”

Use templates {{SECRET_NAME}} nos cabeçalhos para injetar credenciais sem expô-las à IA:

{
  "tools": [
    {
      "name": "fetch-api-data",
      "description": "Fetch data from the internal API",
      "script": "scripts/api-fetch.js",
      "headers": {
        "Authorization": "Bearer {{API_TOKEN}}",
        "X-Api-Key": "{{API_KEY}}"
      }
    }
  ]
}

Os cabeçalhos são resolvidos no momento da execução usando credenciais armazenadas no painel Secrets do Guida. O agente de IA nunca vê os valores dos cabeçalhos, apenas o nome da ferramenta e o esquema de parâmetros.

Os cabeçalhos resolvidos são injetados automaticamente em qualquer chamada g.http.makeHttpRequest() dentro do script.

Execução do script

Seção intitulada “Execução do script”

Quando um agente de IA invoca uma ferramenta personalizada:

  1. O Guida carrega o script do espaço de trabalho
  2. O pragma @timeout é processado
  3. Parâmetros ficam disponíveis em g.tool.args
  4. Cabeçalhos são resolvidos, substituindo templates de credenciais por valores descriptografados
  5. O script roda com ScriptTaskOrigin.Mcp, ou seja, g.secrets.getSecret() é bloqueado
  6. O valor retornado por main() é serializado e enviado ao agente

Superfície MCP

Seção intitulada “Superfície MCP”

Três ferramentas MCP integradas gerenciam ferramentas personalizadas:

FerramentaDescrição
GetWorkspaceToolsLista todas as ferramentas personalizadas com seus esquemas de parâmetros
ExecuteWorkspaceToolExecuta uma ferramenta personalizada com parâmetros
ReloadWorkspaceToolsRecarrega tools.json após alterações

Exemplo: integração de API

Seção intitulada “Exemplo: integração de API”
{
  "tools": [
    {
      "name": "create-ticket",
      "description": "Create a support ticket in the ticketing system",
      "script": "scripts/create-ticket.js",
      "timeout": 15,
      "headers": {
        "Authorization": "Bearer {{TICKETING_API_KEY}}"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "title": { "type": "string", "description": "Ticket title" },
          "body": { "type": "string", "description": "Ticket description" },
          "priority": { "type": "string", "enum": ["low", "medium", "high"] }
        },
        "required": ["title", "body"]
      }
    }
  ]
}
scripts/create-ticket.js
async function main() {
  try {
    const response = await g.http.makeHttpRequest({
      url: "https://api.ticketing.example.com/tickets",
      method: "POST",
      body: JSON.stringify({
        title: g.tool.args.title,
        body: g.tool.args.body,
        priority: g.tool.args.priority || "medium"
      }),
      headers: { "Content-Type": "application/json" }
    });


    const ticket = JSON.parse(response.body);
    return { ticketId: ticket.id, url: ticket.url };
  } catch (e) {
    return { error: e.message };
  }
}

Próximos passos

Seção intitulada “Próximos passos”