capture_plan()

Design Philosophy: It captures the agent's intent by accepting an explicit plan structure. You define which MCPs and actions the agent will execute. The SDK validates the plan structure, then CSRG-IAP creates the cryptographic proof. This is the foundation of ArmorIQ's intent-based security model.

Captures and validates an execution plan structure. The plan must explicitly define the steps the agent intends to execute based on your onboarded MCPs.

client.capture_plan(
    llm: str,
    prompt: str,
    plan: dict,              # REQUIRED
    metadata: dict = None
) -> PlanCapture

client.capturePlan(
  llm: string,
  prompt: string,
  plan: Record<string, any>,  // REQUIRED
  metadata?: Record<string, any>
): PlanCapture

Required Plan Structure

You must provide an explicit plan with your onboarded MCPs and their tools:

# Define your execution plan
plan = {
    "goal": "Search for Coldplay concerts",  # Required: what you want to accomplish
    "steps": [                                # Required: array of actions
        {
            "action": "search_events",        # Tool name from your MCP
            "mcp": "ticketmaster-mcp",       # Your onboarded MCP identifier
            "params": {"artist": "Coldplay"}  # Tool parameters
        }
    ]
}

# Capture the plan (SDK validates structure)
captured = client.capture_plan(
    llm="gpt-4",
    prompt="Find Coldplay concerts",
    plan=plan  # REQUIRED
)

// Define your execution plan
const plan = {
  goal: 'Search for Coldplay concerts',   // Required: what you want to accomplish
  steps: [                                 // Required: array of actions
    {
      action: 'search_events',            // Tool name from your MCP
      mcp: 'ticketmaster-mcp',           // Your onboarded MCP identifier
      params: { artist: 'Coldplay' }      // Tool parameters
    }
  ]
};

// Capture the plan (SDK validates structure)
const captured = client.capturePlan(
  'gpt-4',
  'Find Coldplay concerts',
  plan  // REQUIRED
);

Parameters

Parameter	Type	Required	Description
llm	str	Yes	LLM identifier for context (e.g., "gpt-4", "claude-3", "gpt-3.5-turbo")
prompt	str	Yes	Natural language description of the task
plan	dict	Yes	Required plan structure with `goal` and `steps` - see below
metadata	dict	No	Optional metadata to attach to plan

Plan Structure

The plan object must include:

{
    "goal": str,              // Required: High-level description
    "steps": [                // Required: Array of execution steps
        {
            "action": str,        // Required: Tool/action name from your MCP
            "mcp": str,           // Required: Your onboarded MCP identifier  
            "params": dict,       // Optional: Tool parameters
            "description": str,   // Optional: Human-readable description
            "metadata": dict      // Optional: Additional metadata
        }
    ],
    "metadata": dict          // Optional: Plan-level metadata
}

Important: You must use the exact MCP identifiers and tool names from your onboarded MCPs on the ArmorIQ platform.

Returns

PlanCapture object containing:

{
    "plan": dict,                  # Your provided plan structure
    "llm": str,                    # LLM identifier used
    "prompt": str,                 # Original prompt
    "metadata": dict               # Attached metadata
}

interface PlanCapture {
  plan: Record<string, any>;    // Your provided plan structure
  llm?: string;                 // LLM identifier used
  prompt?: string;              // Original prompt
  metadata: Record<string, any> // Attached metadata
}

Raises

ValueError/Error: If plan parameter is missing or invalid
ValueError/Error: If required fields (goal, steps) are missing
InvalidPlanError: If plan structure is malformed

Examples

Example 1: Single-Step Plan

# Define a simple single-step plan
plan = {
    "goal": "Fetch user data from database",
    "steps": [
        {
            "action": "fetch_user",
            "mcp": "database-mcp",
            "params": {"user_id": "12345"}
        }
    ]
}

captured = client.capture_plan(
    llm="gpt-4",
    prompt="Get user data for user 12345",
    plan=plan
)

print(f"Captured plan with {len(captured.plan['steps'])} step(s)")
print(f"Plan: {captured.plan}")

// Define a simple single-step plan
const plan = {
  goal: 'Fetch user data from database',
  steps: [
    {
      action: 'fetch_user',
      mcp: 'database-mcp',
      params: { user_id: '12345' }
    }
  ]
};

const captured = client.capturePlan(
  'gpt-4',
  'Get user data for user 12345',
  plan
);

console.log(`Captured plan with ${captured.plan.steps?.length || 0} step(s)`);
console.log('Plan:', captured.plan);

Example 2: Multi-Step Plan

# Define a multi-step plan
multi_step_plan = {
    "goal": "Analyze user data and calculate risk score",
    "steps": [
        {
            "action": "fetch_data",
            "mcp": "data-mcp",
            "params": {"user_id": "12345"}
        },
        {
            "action": "analyze",
            "mcp": "analytics-mcp",
            "params": {"metrics": ["risk_score", "engagement"]}
        }
    ]
}

captured = client.capture_plan(
    llm="gpt-4",
    prompt="Fetch and analyze user data",
    plan=multi_step_plan
)

print(f"Captured {len(captured.plan['steps'])} steps")

// Define a multi-step plan
const multiStepPlan = {
  goal: 'Analyze user data and calculate risk score',
  steps: [
    {
      action: 'fetch_data',
      mcp: 'data-mcp',
      params: { user_id: '12345' }
    },
    {
      action: 'analyze',
      mcp: 'analytics-mcp',
      params: { metrics: ['risk_score', 'engagement'] }
    }
  ]
};

const captured = client.capturePlan(
  'gpt-4',
  'Fetch and analyze user data',
  multiStepPlan
);

console.log(`Captured ${captured.plan.steps?.length || 0} steps`);

Example 3: Plan with metadata

# Include metadata for tracking
plan_with_metadata = {
    "goal": "Calculate credit risk for loan application",
    "steps": [
        {
            "action": "calculate_risk",
            "mcp": "analytics-mcp",
            "description": "Calculate credit risk score",
            "params": {"application_id": "APP-12345"},
            "metadata": {"priority": "high"}
        }
    ]
}

captured = client.capture_plan(
    llm="gpt-4",
    prompt="Calculate credit risk for loan application",
    plan=plan_with_metadata,
    metadata={
        "purpose": "credit_assessment",
        "version": "1.2.0",
        "tags": ["finance", "risk"]
    }
)
print(f"Metadata: {captured.metadata}")

// Include metadata for tracking
const planWithMetadata = {
  goal: 'Calculate credit risk for loan application',
  steps: [
    {
      action: 'calculate_risk',
      mcp: 'analytics-mcp',
      description: 'Calculate credit risk score',
      params: { application_id: 'APP-12345' },
      metadata: { priority: 'high' }
    }
  ]
};

const captured = client.capturePlan(
  'gpt-4',
  'Calculate credit risk for loan application',
  planWithMetadata,
  {
    purpose: 'credit_assessment',
    version: '1.2.0',
    tags: ['finance', 'risk']
  }
);
console.log('Metadata:', captured.metadata);

What happens during capture_plan()?

SDK validates the plan structure you provide
Checks required fields (goal, steps array with action and mcp in each step)
Returns PlanCapture object with validated plan - ready for get_intent_token()

Note: The SDK does NOT generate plans or call LLMs. You must provide the explicit plan structure based on your onboarded MCPs.

What happens AFTER capture_plan()?

When you call get_intent_token(plan_capture):

Backend forwards plan to CSRG-IAP
CSRG-IAP canonicalizes the plan into CSRG format
Cryptographic hash computed (plan_hash)
Merkle tree generated with merkle_root
step_proofs array created - one Merkle proof for EACH step
Token signed with Ed25519
Token returned with plan_hash, merkle_root, and step_proofs[]

The step_proofs array is used later during invoke() - the SDK extracts the appropriate proof and sends it in the X-CSRG-Proof header for verification.

capture_plan()

On this page