Skip to main content

Interface: ResourceControls

Defined in: packages/agentos/src/api/types.ts:714

Resource limits applied to the entire agency run. The onLimitReached policy determines whether a breach is fatal.

Properties​

maxAgentCalls?​

optional maxAgentCalls: number

Defined in: packages/agentos/src/api/types.ts:730

Maximum number of agent invocations (across all agents).


maxCostUSD?​

optional maxCostUSD: number

Defined in: packages/agentos/src/api/types.ts:722

Maximum USD cost cap across the entire run.


maxDurationMs?​

optional maxDurationMs: number

Defined in: packages/agentos/src/api/types.ts:728

Wall-clock time budget for the run in milliseconds. The lightweight agent() helper maps this to a per-call request timeout (requestTimeout) instead of the whole-run budget.


maxEmergentAgents?​

optional maxEmergentAgents: number

Defined in: packages/agentos/src/api/types.ts:734

Maximum number of emergent agents the orchestrator may synthesise.


maxStepsPerAgent?​

optional maxStepsPerAgent: number

Defined in: packages/agentos/src/api/types.ts:732

Maximum steps per individual agent invocation.


maxTotalTokens?​

optional maxTotalTokens: number

Defined in: packages/agentos/src/api/types.ts:720

Maximum total tokens (prompt + completion) across all agents and steps. The lightweight agent() helper maps this to a per-call completion-token cap (maxTokens) instead of the run total.


maxValidationRetries?​

optional maxValidationRetries: number

Defined in: packages/agentos/src/api/types.ts:756

Maximum number of retries when structured output validation fails.

When agency({ output: someZodSchema }) is set and the LLM returns text that does not parse or validate against the schema, the agency will retry the generation up to this many times, each time appending an error feedback hint to the prompt so the model can self-correct. agent({ responseSchema }) reads the same setting for generate() (agent() does not apply output; it warns at construction). The retry runs under generate() and a session's send(); stream() and a session's stream() finalize the one run they streamed. A final text that a beforeReturn approval replaced with a different one is not retried: the replacement is returned, with parsed undefined when it does not match. A replacement equal to the strategy's text counts as an approval without modifications, and is retried as that is.

Defaults to 1 (one extra attempt = two total calls). Set to 0 to disable retries entirely. Also used by default-runtime agent().generate() with responseSchema. Session sends take their own maxValidationRetries, defaulting to 0.


onLimitReached?​

optional onLimitReached: "error" | "stop" | "warn"

Defined in: packages/agentos/src/api/types.ts:763

Action taken when any resource limit is breached.

  • "stop" — gracefully stop and return partial results.
  • "warn" — emit a limitReached event and continue.
  • "error" — throw an error and halt immediately.