Ferramentas

Use ferramentas quando um agente precisar ler dados da aplicação, chamar um serviço interno ou executar uma ação. O Agent SDK valida os limites das ferramentas e executa o código delas dentro da sua aplicação.

Defina uma ferramenta local

defineTool() aceita uma descrição, parâmetros JSON opcionais, validadores de execução, um tempo limite e uma função execute().

import { defineTool } from "@phaseo/agent-sdk";

const fetchTicket = defineTool({
  id: "fetch-ticket",
  description: "Load one internal support ticket.",
  parameters: {
    type: "object",
    properties: {
      ticketId: { type: "string" },
    },
    required: ["ticketId"],
    additionalProperties: false,
  },
  timeoutMs: 3_000,
  async execute(input: { ticketId: string }, context) {
    const response = await fetch(
      `https://internal.example/tickets/${input.ticketId}`,
      { signal: context.signal },
    );

    return response.json();
  },
});

Se o tempo limite expirar, o runtime cancela context.signal, marca a execução como malsucedida e relança o erro de tempo limite. Os esquemas podem ser funções ou objetos que expõem parse() ou safeParse(). Argumentos inválidos do modelo e resultados inválidos da ferramenta falham antes de cruzar os limites da ferramenta.

Execute o trabalho na sua aplicação

Defina execute: false quando o trabalho for feito pela sua aplicação, e não pelo processo do SDK. Continue a execução pausada com o resultado em toolOutputs. Para uma ferramenta interativa, retorne null em onToolCalled. Após a continuação, onResponseReceived pode validar ou transformar a resposta fornecida.

Publique o progresso

Um gerador assíncrono pode fornecer resultados preliminares antes de retornar um resultado final:

const indexRepository = defineTool({
  id: "index-repository",
  async *execute(input: { path: string }) {
    yield { phase: "scan" };
    yield { phase: "embed" };
    return { indexed: 248 };
  },
});

O progresso fica disponível por meio dos eventos tool.preliminary_result e de preliminaryResults da etapa.

Execute ferramentas independentes em paralelo

Se um turno do modelo puder chamar várias ferramentas independentes com segurança, configure um limite de concorrência:

const agent = createAgent({
  id: "research-agent",
  toolExecution: {
    toolConcurrency: 3,
  },
  tools: [fetchDocs, fetchStatus, fetchIncidents],
});

O runtime preserva a ordem das mensagens de resultado das ferramentas mesmo quando as execuções locais se sobrepõem.

Comece aqui

Criar

Observabilidade

Referência

Defina uma ferramenta local

Execute o trabalho na sua aplicação

Publique o progresso

Execute ferramentas independentes em paralelo

Guias relacionados

​Defina uma ferramenta local

​Execute o trabalho na sua aplicação

​Publique o progresso

​Execute ferramentas independentes em paralelo

​Guias relacionados

Defina uma ferramenta local

Execute o trabalho na sua aplicação

Publique o progresso

Execute ferramentas independentes em paralelo

Guias relacionados