Package ai.acolite.agentsdk.core

Class RunContext<TContext>

java.lang.Object
ai.acolite.agentsdk.core.RunContext<TContext>
Type Parameters:
TContext - The type of user-provided context object
public class RunContext<TContext> extends Object
RunContext manages execution state for agent runs.

This class serves three primary purposes:

  1. User Context Storage - Holds application-specific data (TContext) that tools need to access, such as user IDs, database connections, auth tokens, etc.
  2. Usage Tracking - Accumulates token usage statistics across all API calls in a conversation for cost monitoring and billing.
  3. Tool Approval Management - Provides a safety mechanism to approve or reject tool calls before execution, supporting both per-call and permanent approval modes.

Example Usage: 


 // Create context with app-specific data
 MyAppContext appContext = new MyAppContext();
 appContext.userId = "user_123";
 appContext.database = myDatabase;

 RunContext<MyAppContext> context = new RunContext<>(appContext);

 // Check tool approval
 Boolean approved = context.isToolApproved("send_email", "call_123");
 if (approved == null) {
     // Pending approval - pause execution
 } else if (approved) {
     // Execute tool
     tool.invoke(context, parameters);
 }

 // Track usage
 context.addUsage(modelResponse.getUsage());
 System.out.println("Total tokens: " + context.getUsage().getTotalTokens());

Ported from TypeScript OpenAI Agents SDK Source: runContext.ts

  • Constructor Details

    • RunContext

      public RunContext()
      Creates a RunContext with default (unknown) context.

    • RunContext

      public RunContext(TContext context)
      Creates a RunContext with the specified user context.
      Parameters:
      context - Application-specific context object, or null for default

  • Method Details

    • isToolApproved

      public Boolean isToolApproved(String toolName, String callId)
      Checks if a tool call has been approved for execution.

      This method supports three approval states:

      • true - Tool call is approved and can execute
      • false - Tool call is rejected and should be blocked
      • null - No decision yet, execution should pause for user approval

      Approval can be either:

      • Permanent - All calls to this tool are approved/rejected
      • Per-call - Only specific call IDs are approved/rejected
      Parameters:
      toolName - The name of the tool being checked
      callId - The unique identifier for this specific tool call
      Returns:
      true if approved, false if rejected, null if pending decision

    • approveTool

      public void approveTool(RunToolApprovalItem approvalItem, boolean alwaysApprove)
      Approves a tool call for execution.

      This method provides two modes:

      • Per-call approval (alwaysApprove = false) - Only approves this specific call ID
      • Permanent approval (alwaysApprove = true) - Approves all future calls to this tool
      Parameters:
      approvalItem - The tool approval request containing tool name and call ID
      alwaysApprove - If true, permanently approves all calls to this tool

    • approveTool

      public void approveTool(RunToolApprovalItem approvalItem)
      Approves a tool call for execution (per-call mode).

      This is a convenience method that approves only the specific call ID. Use approveTool(RunToolApprovalItem, boolean) for permanent approval.

      Parameters:
      approvalItem - The tool approval request

    • rejectTool

      public void rejectTool(RunToolApprovalItem approvalItem, boolean alwaysReject)
      Rejects a tool call, preventing its execution.

      This method provides two modes:

      • Per-call rejection (alwaysReject = false) - Only rejects this specific call ID
      • Permanent rejection (alwaysReject = true) - Rejects all future calls to this tool
      Parameters:
      approvalItem - The tool approval request containing tool name and call ID
      alwaysReject - If true, permanently rejects all calls to this tool

    • rejectTool

      public void rejectTool(RunToolApprovalItem approvalItem)
      Rejects a tool call (per-call mode).

      This is a convenience method that rejects only the specific call ID. Use rejectTool(RunToolApprovalItem, boolean) for permanent rejection.

      Parameters:
      approvalItem - The tool approval request

    • addUsage

      public void addUsage(Usage newUsage)
      Adds usage statistics from a model response to the accumulated total.

      This method is called after each API call to track token consumption across the entire conversation. The usage is immutable - each call creates a new Usage instance with summed values.

      Parameters:
      newUsage - The usage statistics to add

    • toJSON

      public Map<String,Object> toJSON()
      Serializes the context state to a map for persistence or debugging.

      The returned map contains:

      • context - The user-provided context object
      • usage - Accumulated token usage statistics
      • approvals - Tool approval/rejection records
      Returns:
      Map representation of the context state

    • rebuildApprovals

      public void rebuildApprovals(Map<String,ApprovalRecord> approvalsMap)
      Rebuilds approval records from deserialized state.

      This method is used when resuming a run from saved state. It clears existing approvals and replaces them with the provided map.

      Parameters:
      approvalsMap - The approval records to restore