AI Agents

Summary

Agents is a flow step type (backed by @aiqadam/qadam-agent) that executes an LLM-driven autonomous loop. The agent is given a prompt, a set of tools, an AI provider/model, and optional structured-output fields. It runs a ReAct-style loop (up to maxSteps) where the model can call any configured tool before producing a final answer. Tools can be piece actions, other flows, MCP servers, or knowledge-base files. The feature is entirely configured inside the Flow Builder as a special step and does not have its own backend entity — the agent configuration lives inside the flow version's step settings.

Key Files

Shared Types

• packages/shared/src/lib/automation/agents/index.ts — enums (AgentToolType, AgentTaskStatus, ContentBlockType, ToolCallType, AgentOutputFieldType), types (AgentProviderModel, AgentResult, AgentStepBlock, AgentOutputField), and AgentPieceProps property name enum
• packages/shared/src/lib/automation/agents/tools.ts — all tool Zod schemas: AgentPieceTool, AgentFlowTool, AgentMcpTool, AgentKnowledgeBaseTool, AgentTool discriminated union; McpAuthConfig, PredefinedInputsStructure

Frontend

• packages/web/src/features/agents/index.ts — barrel export
• packages/web/src/features/agents/hooks/agent-hooks.ts — agentQueries.useFlowsForAgent(), agentMutations.useValidateMcpTool()
• packages/web/src/features/agents/agent-tools/ — tool management UI (add dropdown, per-tool dialogs, stores)
• packages/web/src/features/agents/agent-tools/stores/ — Zustand stores for piece-tools dialog (pieces-tools.ts) and knowledge-base tools (knowledge-base-tools.ts)
• packages/web/src/features/agents/agent-tools/piece-tool-dialog/ — multi-page dialog: piece list → action list → predefined inputs form → connection picker
• packages/web/src/features/agents/agent-tools/flow-tool-dialog/ — dialog to attach another flow as a tool
• packages/web/src/features/agents/agent-tools/mcp-tool-dialog/ — MCP server URL + auth config dialog; calls mcpToolApi.validateAgentMcpTool to verify connectivity
• packages/web/src/features/agents/agent-tools/knowledge-base-dialog/ — dialog to attach a knowledge-base file
• packages/web/src/features/agents/agent-timeline/ — AgentTimeline component that renders step-by-step execution blocks (markdown + tool calls) from AgentResult.steps
• packages/web/src/features/agents/ai-model/ — AIModelSelector component; PROVIDER_EMBEDDING_MODELS constant
• packages/web/src/features/agents/ai-providers.ts — SUPPORTED_AI_PROVIDERS list with metadata per provider
• packages/web/src/features/agents/structured-output/ — AgentStructuredOutput component for defining output field schema
• packages/web/src/app/builder/step-settings/agent-settings/index.tsx — builder panel for configuring an agent step
• packages/web/src/app/builder/test-step/agent-test-step/index.tsx — test panel for running a single agent step and viewing results
• packages/web/src/app/builder/qadams-selector/index.tsx — the only gate on the agent step: lines 147-149 show the tab only when platform.plan.agentsEnabled && !isNil(aiProviders) && aiProviders.length > 0. The plan flag is never the blocker (getPlan() in platform.service.ts hardcodes agentsEnabled: true), but with no configured AI provider the tab is still hidden.

Domain Terms

• AgentTool — a discriminated union of the four tool types a user can attach to an agent step
• AgentToolType — PIECE, FLOW, MCP, KNOWLEDGE_BASE
• AgentPieceTool — references a specific piece action by pieceName, pieceVersion, actionName; can carry predefinedInput locking certain fields
• AgentFlowTool — calls another flow by externalFlowId; the flow is executed as a child run
• AgentMcpTool — connects to an MCP (Model Context Protocol) server; supports SSE, StreamableHTTP, and SimpleHTTP protocols with None/Bearer/ApiKey/Headers auth
• AgentKnowledgeBaseTool — performs semantic search over a knowledge-base file or table; uses cosine similarity on 768-dim embeddings
• PredefinedInputsStructure — per-field config (AGENT_DECIDE, CHOOSE_YOURSELF, LEAVE_EMPTY) baked into the tool so the agent knows which inputs it controls
• AgentResult — runtime output containing prompt, steps[], status, and optional structuredOutput
• AgentStepBlock — either MarkdownContentBlock or ToolCallContentBlock describing one turn in the agent loop
• ToolCallStatus — IN_PROGRESS (streaming) or COMPLETED
• AgentTaskStatus — COMPLETED, FAILED, IN_PROGRESS

Agent Step Configuration (stored in flow version)

The agent step is a PIECE action on @aiqadam/qadam-agent. Its settings.input contains:

• agentTools — AgentTool[], allowed at most MAX_AGENT_TOOL_PINS (100) entries per step. Each entry is walked by the engine and costs a pin lookup on the API/worker, so the flow write stores an over-cap step but marks it invalid (flow-version-validator-util.ts), the publish gate recomputes the cap so skip and imported steps cannot slip past it, and ap_validate_flow reports it under "Agent Tool Limits". The worker refuses to provision such a step, and agentToolPins.fromInput reads at most the same 100 entries so an MCP report cannot fan out (#879).
• structuredOutput — AgentOutputField[]
• prompt — string (may include {{variables}})
• maxSteps — number
• aiProviderModel — AgentProviderModel ({ providerId?, provider, model })
• webSearch / webSearchOptions — optional web search tool configuration

providerId addresses one AI provider row; provider names its type. Both are stored, because they answer different questions:

• Only the id can pick between several rows of the same type — a platform may hold many custom OpenAI-compatible providers, and a bare name resolves to its oldest matching row. providerId is optional and permanently so: steps written before id-addressing carry none, and a pinned qadam version builds v1/ai-providers/${provider}/config from the enum whatever is stored.
• The name cannot be dropped once an id is present. Capability decisions happen before any config is fetched and are keyed on the enum — which web-search tool builder applies (common/web-search.ts), whether the OpenAI responses API is used (run-agent.ts), which advancedOptions schema is rendered, and getEffectiveProviderAndModel's Cloudflare-Gateway unwrapping. None of those can consume a row id.

createAIModel and createEmbeddingModel (packages/qadams/community/ai/src/lib/common/ai-sdk.ts) both take providerId ?? provider as the route's providerRef, and then build their SDK client from the answering row's provider, not from the name the step stored — the row's auth and config are shaped by its own type.

PIECE Tool Execution (engine)

agentTools.tools (packages/server/engine/src/lib/tools/index.ts) runs each PIECE tool call as a one-step execution through the normal qadamExecutor, with constants from EngineConstants.fromAgentToolCall:

• Run identity is the parent step's. flowRunId and runEnvironment come from the agent step's own constants, so run-scoped engine RPCs the worker checks against the job's run (an inline callFlow's resolveInlineFlow, #643) pass unchanged. flowId/flowVersionId stay the DEFAULT_MCP_DATA placeholders, so a tool's FLOW-scoped store keys and flows.current are what they were before #643.
• Not a step of that run. isAgentToolCall makes the progress reporter ignore the tool's step (sendUpdate and output.update are no-ops), so it can never replace the parent run's snapshot.
• Never pauses. An action with pauses: true is refused before run(), and createWaitpoint / waitForWaitpoint throw for any action that creates a waitpoint (a Queue-mode Call Flow with Wait for Response, approval links, …): a tool call cannot wait, and a waitpoint on the parent's real run would be left PENDING. The refusal is an ordinary FAILED step, which reaches the agent as a tool error.
• Failures stay with the agent. A failed tool step — including a failed inline child — is returned to the agent as ExecutionToolStatus.FAILED; it does not fail the agent's run. Inline children are created with failParentOnFailure: false, so nothing fails the parent out of band either.

Tool Validation

External MCP servers configured as agent tools are validated server-side via POST /v1/projects/:projectId/agent-tools/mcp/validate (see packages/server/api/src/app/agents/). The handler performs the JSON-RPC initialize → notifications/initialized → tools/list handshake against the target and returns its tool names. The outbound call is routed through safeHttp.axios from @aiqadam/server-utils (see packages/server/utils/src/safe-http.ts), whose http/https agents are built on request-filtering-agent to reject private / loopback / link-local / meta IPs by default. Operators can allow specific ranges via AP_SSRF_ALLOW_LIST (CIDR supported). All error paths collapse to a single generic message to avoid leaking reachability signal.

The validator lives under agents/ (not mcp/) because it belongs to the agent piece domain — validating an external MCP server the agent will connect to at flow-execution time. The mcp/ module handles the opposite direction: exposing Qadam Flow itself as an MCP server to external clients.

Timeline Rendering

AgentTimeline receives AgentStepBlock[] from the step output and renders:

• Markdown blocks as formatted text
• Tool call blocks as expandable cards showing tool name, type-specific metadata (piece icon, flow name, MCP URL, KB name), input, output, and status badge