InvocationContext

┌─────────────────────── invocation ──────────────────────────┐
┌──────────── llm_agent_call_1 ────────────┐ ┌─ agent_call_2 ─┐
┌──── step_1 ────────┐ ┌───── step_2 ──────┐
[llm_generate] [execute_tool] [llm_generate] [transfer]

import { InvocationContext, PluginManager } from "@iqai/adk";

const context = new InvocationContext({
  sessionService: mySessionService,
  agent: myAgent,
  session: mySession,
  pluginManager: new PluginManager(plugins),
  invocationId: "e-123abc",
  branch: "coordinator.researcher"
});

// In a tool or callback
context.endInvocation = true; // Stops the invocation

const appName = context.appName;

const userId = context.userId;

context.incrementLlmCallCount();
// Increments counter and checks against runConfig.maxLlmCalls

const spanIndex = context.nextLlmSpanIndex();
// Returns: 1, 2, 3, ...

const spanIndex = context.nextToolSpanIndex();

const spanIndex = context.nextAgentSpanIndex();

const counters = context.getSpanCounters();
// { llm: 3, tool: 5, agent: 2 }

const childContext = parentContext.createChildContext(subAgent);
// childContext.branch = "parent.subAgent"
// childContext.invocationId = same as parent
// childContext.agent = subAgent

interface TransferContext {
  /** Array of agent names in transfer order */
  transferChain: string[];
  
  /** Current depth in transfer chain (0 = root) */
  transferDepth: number;
  
  /** Name of the root agent that started the chain */
  rootAgentName: string;
  
  /** Span context of the root agent for linking */
  rootSpanContext?: SpanContext;
  
  /** Span context of the previous agent in the chain */
  previousSpanContext?: SpanContext;
}

// Root agent starts invocation
context.transferContext = {
  transferChain: ["coordinator"],
  transferDepth: 0,
  rootAgentName: "coordinator"
};

// After transfer to researcher
childContext.transferContext = {
  transferChain: ["coordinator", "researcher"],
  transferDepth: 1,
  rootAgentName: "coordinator"
};

// After researcher transfers to analyst
grandchildContext.transferContext = {
  transferChain: ["coordinator", "researcher", "analyst"],
  transferDepth: 2,
  rootAgentName: "coordinator"
};

class InvocationCostManager {
  private _numberOfLlmCalls = 0;
  
  incrementAndEnforceLlmCallsLimit(runConfig?: RunConfig): void {
    this._numberOfLlmCalls += 1;
    
    if (runConfig?.maxLlmCalls > 0 && 
        this._numberOfLlmCalls > runConfig.maxLlmCalls) {
      throw new LlmCallsLimitExceededError(
        `Max number of llm calls limit of ${runConfig.maxLlmCalls} exceeded`
      );
    }
  }
}

import { newInvocationContextId } from "@iqai/adk";

const id = newInvocationContextId();
// Returns: "e-550e8400-e29b-41d4-a716-446655440000"

class LlmCallsLimitExceededError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "LlmCallsLimitExceededError";
  }
}

type SpanCounters = { 
  llm: number; 
  tool: number; 
  agent: number; 
};

interface TransferContext {
  transferChain: string[];
  transferDepth: number;
  rootAgentName: string;
  rootSpanContext?: SpanContext;
  previousSpanContext?: SpanContext;
}