claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
134 lines • 5.27 kB
TypeScript
/**
* GAIA Agent — ADR-133-PR3 / ADR-135 (planning interval)
*
* Multi-turn Anthropic Messages API loop that drives Claude through the
* GAIA benchmark questions using a tool-use agent pattern.
*
* Loop algorithm:
* 1. Build initial message with the question and a system prompt that
* instructs Claude to output `FINAL_ANSWER: <value>` when done.
* 2. Call Anthropic Messages API with the registered tool definitions.
* 3. On `stop_reason === 'tool_use'`: execute all tool_use blocks in
* parallel, append results as a `user` turn, and repeat.
* Every PLANNING_INTERVAL turns, inject a planning-checkpoint text
* alongside the tool results to force strategy re-evaluation.
* 4. On `stop_reason === 'end_turn'`: scan content for the final answer
* pattern and return the result.
* 5. On timeout (maxTurns exceeded): return `{ timedOut: true }`.
*
* API key resolution order (mirrors resolveHfToken from gaia-loader.ts):
* 1. `options.apiKey` (caller-supplied)
* 2. `ANTHROPIC_API_KEY` env var
* 3. `gcloud secrets versions access latest --secret=ANTHROPIC_API_KEY`
*
* Cost discipline: smoke runs use `claude-haiku-4-5` only. The smoke
* runner at the bottom of this file enforces that model.
*
* Planning interval (iter 30 finding #3):
* smolagents CodeAgent uses planning_interval=4 — replans every 4 steps
* to prevent tunnel-vision on bad strategies. Adds ~80 tokens per
* replan event (~$0.0001 each), negligible cost.
*
* Refs: ADR-133, ADR-135, iter 30, #2156
*/
import { GaiaQuestion } from './gaia-loader.js';
import { GaiaToolCatalogue } from './gaia-tools/index.js';
/**
* Every PLANNING_INTERVAL tool_use turns, inject a planning-checkpoint
* message to force the agent to reassess its strategy.
*
* Based on iter 30 research: smolagents CodeAgent uses planning_interval=4.
* HAL reliability analysis showed agents fail when they exhaust step
* budgets without recalibrating.
*/
export declare const PLANNING_INTERVAL = 4;
/**
* Build the planning-checkpoint text injected every PLANNING_INTERVAL turns.
* Exported so tests can snapshot the exact wording.
*/
export declare function buildPlanningCheckpoint(turn: number, maxTurns: number): string;
export interface GaiaAgentResult {
questionId: string;
finalAnswer: string | null;
turns: number;
toolCallsByName: Record<string, number>;
totalInputTokens: number;
totalOutputTokens: number;
wallMs: number;
/** Number of planning-checkpoint injections during this run (0 when planning is disabled). */
replanCount?: number;
timedOut?: boolean;
error?: string;
}
export interface GaiaAgentOptions {
/** Model to use (default: 'claude-haiku-4-5'). */
model?: string;
/** Maximum number of agent turns before giving up (default: 8). */
maxTurns?: number;
/** Maximum tokens per Anthropic API call (default: 2048). */
maxTokensPerTurn?: number;
/** Per-turn HTTP timeout in milliseconds (default: 60 000). */
perTurnTimeoutMs?: number;
/**
* Inject a planning-checkpoint every N tool_use turns (default: PLANNING_INTERVAL = 4).
* Set to 0 to disable planning checkpoints.
*/
planningInterval?: number;
/**
* Anthropic API key. Resolved automatically via env var + gcloud fallback
* if omitted.
*/
apiKey?: string;
/**
* Pre-built tool catalogue. Defaults to `createDefaultToolCatalogue()`.
* Exposed so callers can inject mocks for testing.
*/
catalogue?: GaiaToolCatalogue;
}
/**
* Resolve the Anthropic API key.
*
* Resolution order:
* 1. Caller-supplied `apiKey`
* 2. `ANTHROPIC_API_KEY` env var
* 3. `gcloud secrets versions access latest --secret=ANTHROPIC_API_KEY`
*
* Throws with a clear message if none of the above is available.
*/
export declare function resolveAnthropicApiKey(apiKey?: string): string;
/**
* Run a GAIA question through Claude with tool use.
*
* @returns GaiaAgentResult with the final answer (or null if timed out),
* turn count, token totals, and per-tool call counts.
*/
export declare function runGaiaAgent(question: GaiaQuestion, options?: GaiaAgentOptions): Promise<GaiaAgentResult>;
/**
* Check whether a model answer matches the expected ground-truth answer.
*
* Matching rules (mirrors GAIA evaluation):
* - Normalise: trim whitespace, lowercase.
* - Substring match: expected is contained in model answer (handles "Paris" vs "Paris, France").
* - Direct equality after normalisation.
* - Numeric: parse as floats and compare with ±1% tolerance.
*/
export declare function isAnswerCorrect(modelAnswer: string, expected: string): boolean;
/**
* Run all 5 SMOKE_FIXTURE questions and report results to stdout.
*
* Pass criteria: ≥3/5 correct (60% pass rate).
*
* Cost estimate is printed at the end using Haiku pricing.
*
* This function is exported so tests can call it directly and capture output;
* it also runs when this file is executed directly via `node gaia-agent.js --smoke`.
*/
export declare function runSmokeTest(opts?: {
verbose?: boolean;
apiKey?: string;
}): Promise<{
passRate: number;
passed: number;
total: number;
}>;
//# sourceMappingURL=gaia-agent.d.ts.map