# AI Agents

## Summary
Agents is a flow step type (backed by `@activepieces/piece-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

## Edition Availability
Gated by `platform.plan.agentsEnabled`. When disabled, the agent step type is hidden from the piece selector. All editions can run agents if the flag is enabled; by default it is off on Community, on on Cloud plans that include it.

## 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 `@activepieces/piece-agent`. Its `settings.input` contains:
- `agentTools` — `AgentTool[]`
- `structuredOutput` — `AgentOutputField[]`
- `prompt` — string (may include `{{variables}}`)
- `maxSteps` — number
- `aiProviderModel` — `AgentProviderModel` (`{ provider, model }`)
- `webSearch` / `webSearchOptions` — optional web search tool configuration

## 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 `apAxios`, whose http/https agents are built by `ssrf-agents.ts` 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 Activepieces 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
