katanakit-js / AgentService

Class: AgentService

Defined in: src/core/services/agent.service.ts:258

AgentService - Singleton facade con Strategy Pattern.

Centraliza el registro del proveedor AI y el bucle de completions, delegando la llamada HTTP en una IAiProviderStrategy intercambiable. Por defecto usa OpenAiCompatibleStrategy.

Example

// Configurar el proveedor
AgentService.getInstance().useInitAgent({ apiKey: process.env.DASHSCOPE_API_KEY });

// Cambiar de estrategia en runtime (p. ej. un mock en tests)
AgentService.getInstance().useSetStrategy(new OpenAiCompatibleStrategy());

Methods

useChat()

useChat(messages, options?): Promise<AiResult<string>>;

Defined in: src/core/services/agent.service.ts:373

Sends a single chat completion and returns the assistant text as a Safe Result.

Use this for review / questioning (single-shot). For autonomous multi-step work with tools, use useRunAgent.

Parameters

Parameter	Type	Description
messages	{ content: string | null; name?: string; role: "system" | "user" | "assistant" | "tool"; tool_call_id?: string; tool_calls?: { function: { arguments: string; name: string; }; id: string; type: "function"; }[]; }[]	Conversation messages (a system prompt is prepended if absent).
options	AiChatOptions	Optional completion options.

Returns

Promise<AiResult<string>>

A AiResult with the assistant text.

Example

import { useChat } from "katanakit-js";

const result = await useChat([
  { role: "user", content: "Summarize the benefits of solar energy in three bullet points." },
]);
if (result.ok) console.log(result.data);

---

useGetStrategy()

useGetStrategy(): IAiProviderStrategy;

Defined in: src/core/services/agent.service.ts:304

Returns the currently active provider strategy.

Returns

IAiProviderStrategy

---

useInitAgent()

useInitAgent(config?): void;

Defined in: src/core/services/agent.service.ts:334

Registers the AI provider for the Kitt assistant.

apiKey falls back to process.env.DASHSCOPE_API_KEY; baseUrl, model and systemPrompt fall back to the kittPreset defaults.

Parameters

Parameter	Type	Description
config	Partial<AiProviderConfig>	Partial provider configuration.

Returns

void

Example

import { useInitAgent } from "katanakit-js";

useInitAgent({
  apiKey: process.env.DASHSCOPE_API_KEY,
  model: "qwen3.8-max",
});

---

useRunAgent()

useRunAgent(goal, options?): Promise<AgentResult>;

Defined in: src/core/services/agent.service.ts:423

Runs the tool-calling agent loop against a goal until it emits a final answer or exhausts maxSteps.

Parameters

Parameter	Type	Description
goal	string	The natural-language objective.
options	AgentRunOptions	Tools, step budget and completion options.

Returns

Promise<AgentResult>

An AgentResult with the final message and executed steps.

Example

import { useRunAgent } from "katanakit-js";

const result = await useRunAgent("Fix the type errors reported by tsc", {
  tools: [
    {
      name: "runCommand",
      description: "Runs a shell command and returns its output",
      parameters: { type: "object", properties: { command: { type: "string" } } },
      execute: (input) => shell.run(input.command),
    },
  ],
  maxSteps: 12,
});

---

useSetStrategy()

useSetStrategy(strategy): void;

Defined in: src/core/services/agent.service.ts:299

Intercambia la estrategia de proveedor en runtime (Strategy Pattern).

Parameters

Parameter	Type	Description
strategy	IAiProviderStrategy	La nueva estrategia a utilizar.

Returns

void

---

create()

static create(strategy?): AgentService;

Defined in: src/core/services/agent.service.ts:290

Crea una instancia NO-singleton con una estrategia específica. Útil para tests o para aislar varios proveedores.

Parameters

Parameter	Type	Description
strategy?	IAiProviderStrategy	Estrategia a inyectar.

Returns

AgentService

Una nueva instancia de AgentService.

---

getInstance()

static getInstance(): AgentService;

Defined in: src/core/services/agent.service.ts:276

Obtiene la instancia única del AgentService (Singleton).

Returns

AgentService

La instancia única de AgentService.