@db-lyon/flowkit 0.10.0 → 0.11.1

package/README.md

@@ -163,6 +163,42 @@ import { ShellTask } from '@db-lyon/flowkit';
 registry.register('shell', ShellTask as any);
 ```
 
+### AI agents
+
+Run LLM calls as steps. Flowkit has **no SDK dependencies** — you wire a
+model-agnostic `LLMProvider` onto the task context as `ctx.llm`, and two tasks
+consume it:
+
+- `agent_prompt` (`AgentPromptTask`) — single-shot prompt, with optional
+  JSON-Schema structured output (validated, with a repair re-prompt).
+- `agent` (`AgentTask`) — a tool-calling loop. Tools reference flowkit tasks,
+  flows, or other agents (or context handlers), gated by an allowlist and
+  per-tool argument validation. Multiple tool calls in a turn (including
+  parallel sub-agents) run concurrently under a cap.
+
+Reusable agents live under an `agents:` root key and run as flow steps or as
+other agents' tools, with mandatory budgets (`maxIterations`, `tokenBudget`,
+`maxAgentDepth`). Iteration and concurrency live in the agent runtime, so a flow
+stays a sequential spine with no `loop:` or parallel-step primitive.
+
+```yaml
+tasks:
+  extract:
+    class_path: agent_prompt
+    options:
+      prompt: "Pull the ticket fields from:\n${steps.1.data.text}"
+      schema:
+        type: object
+        required: [title, priority]
+        properties:
+          title: { type: string }
+          priority: { type: string, enum: [low, medium, high] }
+```
+
+Every call is hardened by a shared core: per-call `timeout` (with provider
+abort), `retries` with exponential backoff, structured-output validation +
+repair, and output-size caps. See [docs/ai-agents.md](docs/ai-agents.md).
+
 ### Nested flows
 
 A step can reference another flow instead of a task:
@@ -330,6 +366,7 @@ import { topologicalSort } from '@db-lyon/flowkit/dag';
 
 - [Getting started](docs/getting-started.md) — step-by-step setup guide
 - [Custom tasks](docs/custom-tasks.md) — writing and registering tasks
+- [AI agents](docs/ai-agents.md) — LLM prompts, structured output, tool-calling agents
 - [Configuration](docs/configuration.md) — YAML schema, layering, deep merge
 - [API reference](docs/api-reference.md) — full type and function reference
 

package/dist/config/index.d.ts

@@ -1,6 +1,6 @@
 export { deepMerge } from './deep-merge.js';
-export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, EngineConfigSchema, } from './schema.js';
-export type { TaskOptions, TaskDefinition, FlowStep, FlowDefinition, EngineConfig, } from './schema.js';
+export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, AgentToolSchema, AgentBudgetSchema, AgentDefinitionSchema, EngineConfigSchema, } from './schema.js';
+export type { TaskOptions, TaskDefinition, FlowStep, FlowDefinition, AgentTool, AgentBudget, AgentDefinition, EngineConfig, } from './schema.js';
 export { loadConfig, loadRawYaml, findConfigFile } from './loader.js';
 export type { LoadConfigOptions, LoadedConfig } from './loader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,cAAc,EACd,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/config/index.js

@@ -1,4 +1,4 @@
 export { deepMerge } from './deep-merge.js';
-export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, EngineConfigSchema, } from './schema.js';
+export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, AgentToolSchema, AgentBudgetSchema, AgentDefinitionSchema, EngineConfigSchema, } from './schema.js';
 export { loadConfig, loadRawYaml, findConfigFile } from './loader.js';
 //# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAarB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/config/schema.d.ts

@@ -485,6 +485,213 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
     }[] | undefined;
     rollback_on_failure?: boolean | undefined;
 }>;
+/**
+ * A tool an agent may call. References an existing flowkit primitive — a `task`,
+ * a `flow`, or another `agent` — so tool dispatch reuses the registry, options,
+ * and `${...}` reference machinery rather than inventing a parallel concept.
+ * `name` (defaulted from the reference) is what the model sees.
+ */
+export declare const AgentToolSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodString>;
+    flow: z.ZodOptional<z.ZodString>;
+    agent: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}>, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Hard bounds on an agent run. A tool-using agent with no caps is unbounded
+ * spend, so a budget is the intended companion to every agent definition.
+ */
+export declare const AgentBudgetSchema: z.ZodObject<{
+    /** Max model turns. */
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+    tokenBudget: z.ZodOptional<z.ZodNumber>;
+    /** Cap on a single tool result's serialized size, in chars. */
+    maxToolResultChars: z.ZodOptional<z.ZodNumber>;
+    /** Cap on a sub-agent result's serialized size, in chars (0 = unbounded). */
+    maxAgentResultChars: z.ZodOptional<z.ZodNumber>;
+    /** Max tool calls run concurrently within a turn. */
+    maxConcurrency: z.ZodOptional<z.ZodNumber>;
+    /** Max depth of agent-calls-agent recursion. */
+    maxAgentDepth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxIterations?: number | undefined;
+    tokenBudget?: number | undefined;
+    maxToolResultChars?: number | undefined;
+    maxAgentResultChars?: number | undefined;
+    maxConcurrency?: number | undefined;
+    maxAgentDepth?: number | undefined;
+}, {
+    maxIterations?: number | undefined;
+    tokenBudget?: number | undefined;
+    maxToolResultChars?: number | undefined;
+    maxAgentResultChars?: number | undefined;
+    maxConcurrency?: number | undefined;
+    maxAgentDepth?: number | undefined;
+}>;
+export declare const AgentDefinitionSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    /** Model identifier — provider-specific. */
+    model: z.ZodOptional<z.ZodString>;
+    /** System prompt / rules. */
+    system: z.ZodOptional<z.ZodString>;
+    /** Tools the agent may call (its allowlist). */
+    tools: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        task: z.ZodOptional<z.ZodString>;
+        flow: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }>, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    /** JSON Schema for the agent's final answer. */
+    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Hard run bounds. */
+    budget: z.ZodOptional<z.ZodObject<{
+        /** Max model turns. */
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+        tokenBudget: z.ZodOptional<z.ZodNumber>;
+        /** Cap on a single tool result's serialized size, in chars. */
+        maxToolResultChars: z.ZodOptional<z.ZodNumber>;
+        /** Cap on a sub-agent result's serialized size, in chars (0 = unbounded). */
+        maxAgentResultChars: z.ZodOptional<z.ZodNumber>;
+        /** Max tool calls run concurrently within a turn. */
+        maxConcurrency: z.ZodOptional<z.ZodNumber>;
+        /** Max depth of agent-calls-agent recursion. */
+        maxAgentDepth: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxAgentResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    }, {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxAgentResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    }>>;
+    /** Sampling temperature. */
+    temperature: z.ZodOptional<z.ZodNumber>;
+    /** Per-call max output tokens. */
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    /** Per-call timeout in ms. */
+    timeout: z.ZodOptional<z.ZodNumber>;
+    /** Transport retries per call. */
+    retries: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    tools: {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }[];
+    description?: string | undefined;
+    retries?: number | undefined;
+    model?: string | undefined;
+    system?: string | undefined;
+    schema?: Record<string, unknown> | undefined;
+    budget?: {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxAgentResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    } | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    timeout?: number | undefined;
+}, {
+    description?: string | undefined;
+    retries?: number | undefined;
+    model?: string | undefined;
+    system?: string | undefined;
+    tools?: {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    schema?: Record<string, unknown> | undefined;
+    budget?: {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxAgentResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    } | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    timeout?: number | undefined;
+}>;
 /** Minimal config shape the engine requires. Consumers extend with their own sections. */
 export declare const EngineConfigSchema: z.ZodObject<{
     tasks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -916,6 +1123,139 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }>>>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        /** Model identifier — provider-specific. */
+        model: z.ZodOptional<z.ZodString>;
+        /** System prompt / rules. */
+        system: z.ZodOptional<z.ZodString>;
+        /** Tools the agent may call (its allowlist). */
+        tools: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            task: z.ZodOptional<z.ZodString>;
+            flow: z.ZodOptional<z.ZodString>;
+            agent: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }>, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }>, "many">>;
+        /** JSON Schema for the agent's final answer. */
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Hard run bounds. */
+        budget: z.ZodOptional<z.ZodObject<{
+            /** Max model turns. */
+            maxIterations: z.ZodOptional<z.ZodNumber>;
+            /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+            tokenBudget: z.ZodOptional<z.ZodNumber>;
+            /** Cap on a single tool result's serialized size, in chars. */
+            maxToolResultChars: z.ZodOptional<z.ZodNumber>;
+            /** Cap on a sub-agent result's serialized size, in chars (0 = unbounded). */
+            maxAgentResultChars: z.ZodOptional<z.ZodNumber>;
+            /** Max tool calls run concurrently within a turn. */
+            maxConcurrency: z.ZodOptional<z.ZodNumber>;
+            /** Max depth of agent-calls-agent recursion. */
+            maxAgentDepth: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxAgentResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        }, {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxAgentResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        }>>;
+        /** Sampling temperature. */
+        temperature: z.ZodOptional<z.ZodNumber>;
+        /** Per-call max output tokens. */
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        /** Per-call timeout in ms. */
+        timeout: z.ZodOptional<z.ZodNumber>;
+        /** Transport retries per call. */
+        retries: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        tools: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[];
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxAgentResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }, {
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        tools?: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxAgentResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     tasks: Record<string, {
         options: Record<string, unknown>;
@@ -979,6 +1319,32 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }>;
+    agents: Record<string, {
+        tools: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[];
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxAgentResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }>;
 }, {
     tasks?: Record<string, {
         options?: Record<string, unknown> | undefined;
@@ -1042,10 +1408,39 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }> | undefined;
+    agents?: Record<string, {
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        tools?: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxAgentResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }> | undefined;
 }>;
 export type TaskOptions = z.infer<typeof TaskOptionsSchema>;
 export type TaskDefinition = z.infer<typeof TaskDefinitionSchema>;
 export type FlowStep = z.infer<typeof FlowStepSchema>;
 export type FlowDefinition = z.infer<typeof FlowDefinitionSchema>;
+export type AgentTool = z.infer<typeof AgentToolSchema>;
+export type AgentBudget = z.infer<typeof AgentBudgetSchema>;
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
 export type EngineConfig = z.infer<typeof EngineConfigSchema>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}

package/dist/config/schema.js

@@ -60,9 +60,71 @@ export const FlowDefinitionSchema = z.object({
     /** If true, invoke rollback records from completed steps in reverse order on failure. */
     rollback_on_failure: z.boolean().optional(),
 });
+// ---------------------------------------------------------------------------
+// Agents — the AI-native layer. Additive: CumulusCI never had an `agents:` key,
+// so adding one leaves `tasks:`/`flows:` byte-identical to a cumulusci.yml.
+// ---------------------------------------------------------------------------
+/**
+ * A tool an agent may call. References an existing flowkit primitive — a `task`,
+ * a `flow`, or another `agent` — so tool dispatch reuses the registry, options,
+ * and `${...}` reference machinery rather than inventing a parallel concept.
+ * `name` (defaulted from the reference) is what the model sees.
+ */
+export const AgentToolSchema = z
+    .object({
+    name: z.string().optional(),
+    task: z.string().optional(),
+    flow: z.string().optional(),
+    agent: z.string().optional(),
+    description: z.string().optional(),
+    parameters: z.record(z.unknown()).optional(),
+})
+    .refine((t) => !!(t.task || t.flow || t.agent || t.name), {
+    message: 'agent tool must reference a task, flow, or agent, or declare a name',
+});
+/**
+ * Hard bounds on an agent run. A tool-using agent with no caps is unbounded
+ * spend, so a budget is the intended companion to every agent definition.
+ */
+export const AgentBudgetSchema = z.object({
+    /** Max model turns. */
+    maxIterations: z.number().int().positive().optional(),
+    /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+    tokenBudget: z.number().int().positive().optional(),
+    /** Cap on a single tool result's serialized size, in chars. */
+    maxToolResultChars: z.number().int().positive().optional(),
+    /** Cap on a sub-agent result's serialized size, in chars (0 = unbounded). */
+    maxAgentResultChars: z.number().int().nonnegative().optional(),
+    /** Max tool calls run concurrently within a turn. */
+    maxConcurrency: z.number().int().positive().optional(),
+    /** Max depth of agent-calls-agent recursion. */
+    maxAgentDepth: z.number().int().positive().optional(),
+});
+export const AgentDefinitionSchema = z.object({
+    description: z.string().optional(),
+    /** Model identifier — provider-specific. */
+    model: z.string().optional(),
+    /** System prompt / rules. */
+    system: z.string().optional(),
+    /** Tools the agent may call (its allowlist). */
+    tools: z.array(AgentToolSchema).default([]),
+    /** JSON Schema for the agent's final answer. */
+    schema: z.record(z.unknown()).optional(),
+    /** Hard run bounds. */
+    budget: AgentBudgetSchema.optional(),
+    /** Sampling temperature. */
+    temperature: z.number().optional(),
+    /** Per-call max output tokens. */
+    maxTokens: z.number().int().positive().optional(),
+    /** Per-call timeout in ms. */
+    timeout: z.number().int().nonnegative().optional(),
+    /** Transport retries per call. */
+    retries: z.number().int().nonnegative().optional(),
+});
 /** Minimal config shape the engine requires. Consumers extend with their own sections. */
 export const EngineConfigSchema = z.object({
     tasks: z.record(TaskDefinitionSchema).default({}),
     flows: z.record(FlowDefinitionSchema).default({}),
+    agents: z.record(AgentDefinitionSchema).default({}),
 });
 //# sourceMappingURL=schema.js.map

package/dist/config/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}

package/dist/flow/runner.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '../logger.js';
-import type { TaskDefinition, FlowDefinition } from '../config/schema.js';
+import type { TaskDefinition, FlowDefinition, AgentDefinition } from '../config/schema.js';
 import type { TaskResult } from '../task/base-task.js';
 import type { TaskContext } from '../task/base-task.js';
 import type { TaskRegistry } from '../task/registry.js';
@@ -121,6 +121,12 @@ export interface FlowRunnerConfig {
      * values, e.g. `{ project, org, env }`. `steps` and `error` are always built in.
      */
     references?: Record<string, unknown>;
+    /**
+     * Declarative agents. Each becomes runnable as a flow step (`task: <name>`)
+     * and as another agent's `agent:` tool, and the runner wires `ctx.runFlow` /
+     * `ctx.runAgent` so agents can call flows and sub-agents as tools.
+     */
+    agents?: Record<string, AgentDefinition>;
 }
 export declare class FlowRunner {
     private logger;
@@ -131,8 +137,19 @@ export declare class FlowRunner {
     private hooks;
     private conditionEvaluator?;
     private references?;
+    private agents;
     private runDepth;
     constructor(config: FlowRunnerConfig);
+    /** Map an agent definition onto AgentTask options (everything but the prompt). */
+    private compileAgent;
+    /** Run a configured flow as an agent tool, returning a compact step summary. */
+    private runFlowTool;
+    /**
+     * Run a configured agent as an agent tool (sub-agent), threading recursion
+     * depth and the caller's token ledger so the sub-agent's spend charges the
+     * same budget.
+     */
+    private runAgentTool;
     run(options: FlowRunOptions): Promise<FlowRunResult>;
     /**
      * Run a single task by name, directly — the leaf unit of work, without a flow.