Understanding Copilot SDK Factory Limits: maxConcurrentSubagents, timeoutSeconds, and maxAiCredits

The Copilot SDK enforces resource constraints on Agent Factories through the FactoryLimits interface, validating maxConcurrentSubagents, timeoutSeconds, and maxAiCredits at registration time in nodejs/src/factory.ts to prevent runtime overconsumption.

The github/copilot-sdk repository provides extension authors with a framework for building AI agents that spawn sub-agents and consume computational resources. Understanding Copilot SDK Factory limits is essential for preventing resource exhaustion and ensuring predictable behavior in production environments. These constraints are declared in the factory metadata and strictly validated when you register your factory using defineFactory.

What Are Copilot SDK Factory Limits?

Agent Factories can spawn sub-agents, execute code for bounded durations, and consume AI credits during operation. To prevent runaway processes, the SDK requires authors to declare resource caps inside the Factory Meta → limits object. When you call defineFactory in nodejs/src/factory.ts, the SDK deep-freezes the metadata and executes validateLimits to enforce compliance before registration succeeds.

The limits are TypeScript-defined in the FactoryLimits interface located at nodejs/src/types.ts:L38-L49. All numeric constraints must be positive when present, with specific upper bounds enforced by the validation logic.

The Four Core Limit Parameters

The FactoryLimits interface exposes four distinct constraints that govern factory behavior throughout its lifecycle.

maxConcurrentSubagents

The maxConcurrentSubagents parameter defines the maximum number of sub-agents permitted to run simultaneously at any given moment. According to the validation logic in nodejs/src/factory.ts:L383-L387, this value must be a positive integer when supplied. Attempting to register a factory with zero, negative numbers, or non-integer values triggers an immediate validation error.

maxTotalSubagents

Distinct from concurrent limits, maxTotalSubagents establishes a lifetime ceiling on the total number of sub-agents that may be spawned over the factory's entire execution. This limit shares the same validation rules as maxConcurrentSubagents—it must be a positive integer if provided, enforced in the same code block at nodejs/src/factory.ts:L383-L387.

timeoutSeconds

The timeoutSeconds parameter sets an upper bound on accumulated active-execution time for the factory and all its descendants. Active execution includes the extension body, subprocess waits, queued-agent waits, and sleep operations. The validation logic at nodejs/src/factory.ts:L90-L104 requires this value to be a finite, positive number that cannot exceed Node.js's timer ceiling of 2,147,483.647 seconds (MAX_FACTORY_TIMEOUT_SECONDS).

maxAiCredits

This soft ceiling constrains AI-credit consumption for the factory and its entire sub-agent tree. When specified, the value must be a positive, finite number that, when multiplied by 1,000,000,000 (nano-AI units), rounds to a safe integer as determined by Number.isSafeInteger. This validation occurs at nodejs/src/factory.ts:L107-L118. The SDK treats this as a post-paid soft limit, meaning enforcement happens after consumption occurs rather than blocking requests prospectively.

Validation and Error Handling

When defineFactory processes your factory definition, it immediately deep-freezes the metadata object to prevent mutation, then runs validateLimits against your declared constraints. Any violation produces a descriptive Error that prevents registration, allowing you to catch configuration issues during development rather than production.

If you attempt to exceed the Node.js timeout ceiling, the SDK throws: Factory limit "timeoutSeconds" must not exceed 2147483.647 seconds.

Practical Implementation Examples

Defining a Factory with Resource Limits

Configure your factory with explicit constraints to prevent resource exhaustion:

import { defineFactory } from '@copilot/sdk';

export const myFactory = defineFactory({
  meta: {
    name: "example-factory",
    description: "Demo factory with limits",
    phases: [{ title: "setup" }, { title: "run" }],
    limits: {
      maxConcurrentSubagents: 3,   // at most 3 sub-agents concurrently
      maxTotalSubagents: 10,      // no more than 10 sub-agents overall
      timeoutSeconds: 60,         // max 1 minute of active execution
      maxAiCredits: 5,            // soft ceiling of 5 AI credits
    },
  },

  async run({ emit }) {
    // factory logic here…
  },
});

The SDK validates these limits at nodejs/src/factory.ts during the registration call. If any value violates the constraints—such as timeoutSeconds exceeding approximately 24.8 days—the factory registration fails immediately with a descriptive error message.

Inspecting Limits at Runtime

You can retrieve factory metadata for UI display or logging purposes:

import { getFactoryDefinition } from '@copilot/sdk';

const def = getFactoryDefinition(myFactory);
console.log(def.meta.limits);
/*
{
  maxConcurrentSubagents: 3,
  maxTotalSubagents: 10,
  timeoutSeconds: 60,
  maxAiCredits: 5,
}
*/

This approach leverages the deep-frozen metadata object returned by the SDK, ensuring you see the exact values validated at registration time.

Summary

• Resource constraints in the Copilot SDK are declared via the FactoryLimits interface in nodejs/src/types.ts and validated in nodejs/src/factory.ts.
• maxConcurrentSubagents and maxTotalSubagents must be positive integers limiting simultaneous and total sub-agent counts respectively.
• timeoutSeconds caps active execution time at a maximum of 2,147,483.647 seconds and must be finite and positive.
• maxAiCredits imposes a soft ceiling on AI consumption, requiring values that convert safely to nano-AI units (multiplying by 1,000,000,000).
• Validation occurs at registration when defineFactory calls validateLimits, throwing errors for invalid configurations before runtime.

Frequently Asked Questions

What happens if I exceed maxConcurrentSubagents at runtime?

The Copilot SDK enforces maxConcurrentSubagents as a hard limit. When your factory attempts to spawn additional sub-agents beyond the declared concurrent maximum, the SDK blocks the creation request. This prevention occurs at the factory level, ensuring you never exceed the simultaneous execution threshold defined in your FactoryLimits.

Is maxAiCredits a hard limit that stops execution immediately?

No, maxAiCredits operates as a soft, post-paid ceiling. The SDK tracks consumption throughout execution and enforces the limit retrospectively rather than blocking AI requests prospectively. You must still specify a positive, finite number that safely converts to nano-AI units (multiplied by 1,000,000,000) as validated in nodejs/src/factory.ts:L107-L118.

What is the absolute maximum value for timeoutSeconds?

The validation logic at nodejs/src/factory.ts:L90-L104 enforces a hard ceiling of 2,147,483.647 seconds (approximately 24.8 days), defined as MAX_FACTORY_TIMEOUT_SECONDS. This corresponds to Node.js's maximum timer duration. Values exceeding this threshold trigger a validation error during factory registration.

Where are FactoryLimits defined in the source code?

The FactoryLimits TypeScript interface is defined in nodejs/src/types.ts at lines 38-49, specifying the optional properties for maxConcurrentSubagents, maxTotalSubagents, timeoutSeconds, and maxAiCredits. The corresponding validation logic resides in nodejs/src/factory.ts, with comprehensive test coverage available in nodejs/test/factory.test.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}