Embedding AI Agents into a File Portal — From AgentCore MCP to Multi-Agent Teams (Part 3)

Let an AI agent work the NAS, with a human approving — Amazon Bedrock AgentCore and MCP (part 3 of 3)

A Japanese version of this article is available: 日本語版

Introduction

In Part 1 I built the file portal foundation on the S3 Access Points of Amazon FSx for NetApp ONTAP (hereafter FSx for ONTAP), and in Part 2 I embedded storage operations (ARP/AI incident response, Tamperproof Snapshots, regulatory retention management). At that point the UI was sufficient for anyone who already knew which button to press — but a different kind of friction was still there. "Where did I put last week's simulation results?" "Summarize the key points of this PDF in three lines." The intent is perfectly clear; the cost of translating it into system operations was what stayed high.

So I integrated AI agents into the portal. Express your intent in natural language, and the agent finds the files, reads them, analyzes the content, and proposes storage management operations when needed. Because storage management includes irreversible operations, the execution decision stays with a human through a Human-in-the-Loop (HITL) flow.

Here's the conclusion up front:

• Combining the Amazon Bedrock Converse API with MCP tools lets you explore and analyze files on an S3 AP in natural language
• Connecting a Bedrock Knowledge Base directly to an S3 AP means you can reach a file through semantic search without knowing its name
• Wrapping destructive operations in a HITL approval modal keeps agent autonomy and safety in the same design
• Multi-agent collaboration pays off only for tasks with several phases — "discover → analyze → judge"

In this article, I'll cover the 3-mode AgentChat design, file access via MCP tools, the HITL flow, and the implementation patterns for multi-agent collaboration.

Light theme shown. A dark theme version is available, and every figure is listed in the architecture diagram index.

Repository: solutions/amplify-portal/

Terminology note: "MCP" in this article refers to Model Context Protocol — a standard protocol that allows AI models to invoke external tools (file operations, database queries, etc.). AgentCore Gateway acts as the MCP server, exposing Lambda-based tools to the AI model.

If You're Already Using ChatGPT / Copilot / Claude for Document Analysis

When using general-purpose AI assistants (ChatGPT, GitHub Copilot, Claude, etc.) for file analysis, the typical flow is "upload file → AI analyzes → returns results." The portal agent takes a different approach.

This portal does not attempt to replace general-purpose AI assistants. It adds NAS-connected file intelligence — file discovery, content understanding, and storage operation proposals. For general Q&A, ChatGPT and Copilot remain well-suited tools for those tasks.

Verification status: how far each feature in this article has actually been confirmed is recorded in verification results, split four ways (live E2E / live read / tests only / DemoMode). Agent and team execution sits in the "tests only" category: handler and component tests pass, but it has not been driven from a browser against a real system.

What I Built

The portal moved from "browse files and check operational state" to "ask in natural language, and the agent finds files, understands content, and proposes storage operations." Here's what was added:

• AgentChat: Multi-tool AI chat with 3 switchable modes
• SemanticSearch: Vector search via Bedrock Knowledge Base — resolves "where did I put that file?" in natural language
• Agent Directory / Creator: Define custom agents and share them with your team
• Agent Teams: Run multiple agents in collaboration
• ActionApproval (HITL): Insert a human approval flow before destructive operations
• Multimodal input: Drag and drop an image into the chat for file analysis

Why Embed AI Agents in the Portal

The admin features from Part 2 work well for people who already know "what to operate and how." But what I actually hear in practice sounds more like:

• "Where did I put last week's simulation results?"
• "Can you summarize what caused the error in this log file?"
• "I want to run legal review on the contracts folder, but I don't know the steps"

These aren't cases of "not knowing how to operate the system." They're cases of "I know what I want, but translating that intent into system operations is tedious." This applies equally to non-technical team members:

• "Where's the attachment for last month's expense report?"
• "Summarize this PDF in 3 lines"
• "Compile a file list from this folder for my weekly report"

The motivation for embedding AI agents was to eliminate this translation cost entirely. Express your intent in natural language, and the agent finds files, reads them, analyzes content, and proposes admin operations if needed. Users only need to think about "what they want to accomplish."

However, giving an agent unrestricted authority in a storage management context is dangerous. Enabling SnapLock is irreversible. Modifying an export-policy immediately cuts off user access. So I combine the Human-in-the-Loop (HITL) pattern: "the agent proposes, but humans approve execution."

AgentChat — 3-Mode Integrated Chat

A persistent AI chat in the portal's right panel, fully replacing the previous "Bedrock Q&A" (single-file question-answering).

3 Modes

Modes switch via pill buttons below the header. Welcome screen task cards change per mode, showing "what you can do in this mode."

Architecture

Browser (React)
    ↓ AppSync Query (agentQuery)
Lambda: Agent Orchestrator (outside VPC)
    ├── mode=kb   → Bedrock KB RetrieveAndGenerate
    ├── mode=agent → Bedrock Converse + MCP Tools
    └── mode=multi → Multi-agent collaboration
                         ↓ MCP Client
                    AgentCore Gateway
                         ↓ Lambda Invoke
                    MCP Tool Lambda (list_files / read_file / search_files)
                         ↓ S3 API
                    FSx for ONTAP S3 Access Point

Light theme shown. A dark theme version is available.

The VPC split principle applies here too. The Agent Orchestrator Lambda is placed outside VPC, accessing Bedrock API and S3 AP (Internet-origin). Admin operations calling ONTAP REST API are handled by a separate VPC-internal Lambda.

Tool Execution Visibility

When the agent invokes tools, a timeline appears in the chat:

🔧 Tool Calls (3)                          2.1s
├── ✅ 🔍 file-explorer: list_files         {"prefix": "/engineering/"}
├── ✅ 📄 file-explorer: read_file          {"key": "/engineering/thermal-spec-v3.pdf"}
└── ✅ 🧠 knowledge-analyst: analyze_file   {"key": "...", "question": "..."}

Each tool's input/output examples:

Displayed in <details> — expanded by default when 3 or fewer tool calls, collapsed when 4+. This balances Nielsen's "visibility of system status" with Wroblewski's "progressive disclosure."

Chat History Persistence

Conversation sessions auto-save to DynamoDB (2-second debounce). Past sessions can be recalled from the history panel to continue questioning.

// Auto-save: 2 seconds after message change → DynamoDB
useEffect(() => {
  if (messages.length === 0 || !currentSessionId) return;
  const timer = setTimeout(() => saveCurrentSession(), 2000);
  return () => clearTimeout(timer);
}, [messages, currentSessionId]);

The rationale: forcing an explicit "Save" button interrupts the natural flow of chat. Close the browser, and next time you open it, you can pick up from "where we left off yesterday."

Multimodal Input

Drag-and-drop images into the chat for Bedrock Vision analysis:

• Circuit diagram image → "Where's the bottleneck in this circuit?"
• Screenshot → "What's causing this error screen?"
• Graph image → "Explain this performance degradation trend"

Supports JPEG/PNG/GIF/WebP under 5MB. Base64-encoded and sent to Bedrock Converse API.

SemanticSearch — Vector Search

Keyword search on file names has limits. When you want to find "the spec document about thermal design limits," you might find thermal-spec-v3.pdf by name, but TC-2024-0089.pdf? No chance.

Keyword / Semantic Mode Toggle

Mode toggle pills in the search bar:

🔍 [Search files...                        ] [🔍]
   [📂 Keyword]  [🧠 Semantic]

• Keyword mode: S3 AP ListObjectsV2 + prefix filter. Auto-searches with 500ms debounce after 2+ characters
• Semantic mode: Bedrock Knowledge Base RetrieveAndGenerate API. Vectorizes natural language queries for similarity search

Bedrock Knowledge Base Integration

FSx for ONTAP's S3 AP can be specified directly as a Knowledge Base data source (AWS official tutorial).

FSx for ONTAP Volume
    ↓ S3 AP (Data Source)
Bedrock Knowledge Base
    ↓ Embeddings (Titan V2)
OpenSearch Serverless (Vector Store)
    ↓ RetrieveAndGenerate
Results: related chunks + source file path + relevance score

Light theme shown. A dark theme version is available.

Results include scores (percentage display) and snippets. Clicking a result navigates to the file in the All Files view.

Semantic Search Input Examples

When KB is unconfigured, help text guides users:

💡 Semantic search examples:
• "Files with anomalies in last month's sales reports"
• "Test results exceeding thermal design specifications"
• "Description of the approval process for contract renewal"

Constraints

• KB sync is asynchronous (minutes to tens of minutes lag after file changes)
• Large file environments incur OpenSearch Serverless indexing costs
• PDF/Office text extraction accuracy depends on file quality
• If bedrockKbId is empty in portal-config.ts, semantic mode shows a "KB not configured" error

KB sync detection: Data source sync status can be checked via the bedrock-agent:GetIngestionJob API. Periodic sync can be scheduled in the Bedrock console. If immediate search reflection after file changes is required, consider an EventBridge + StartIngestionJob API configuration for on-demand sync triggers.

Agent Directory — Agent Catalog

A UI for discovering "what agents are available."

Preset Agents

Custom Agent Creation (Agent Creator)

When presets aren't enough, define your own agents:

Agent Creation Wizard:
1. Set name and icon
2. Write system prompt
3. Select tools to use (checkboxes)
4. Test execution
5. Sharing settings (personal only / team-shared)

Created agents appear in the Agent Directory, available to team members (when shared). This lets you codify patterns like "this department frequently does this kind of analysis" as reusable agents.

Agent Teams — Multi-Agent Collaboration

For complex tasks that a single agent can't handle alone, multiple agents collaborate.

When to Use Multi-Agent vs Single Agent

Decision criteria: Multi-agent is effective when the task has multiple phases ("discover → analyze → judge") requiring different expertise at each phase. For simple tasks, multi-agent adds cost and latency without benefit — use single agent instead.

Example Team Configuration

Team: "Security Audit Team"
├── 🔍 file-explorer (Collaborator): Identify target files
├── 🛡️ safety-controller (Supervisor): Verify ARP/security state
└── 📋 compliance-auditor (Reviewer): Final compliance judgment

Roles

Team Creation Wizard

1. Enter team name and description
2. Add agents from Agent Directory (minimum 2)
3. Assign roles to each agent
4. Sharing settings

Team execution flow:

User: "Analyze all simulation results in the engineering/ folder"
    ↓
Supervisor (safety-controller):
    → Instructs file-explorer: "Get file listing for engineering/"
    ↓
Collaborator (file-explorer):
    → list_files → read_file (multiple)
    → Result: 12 files found, 8 are simulation results
    ↓
Supervisor:
    → Instructs knowledge-analyst: "Create summaries for each file"
    ↓
Collaborator (knowledge-analyst):
    → Analyzes each file, generates summaries
    ↓
Reviewer (compliance-auditor):
    → "Verify no PHI data is included"
    → Result: 2 files may contain personal information → recommends guardrail application
    ↓
Final response to user:
    "Analyzed 8 of 12 files. Summaries below.
     Note: 2 files were filtered due to potential personal information."

Light theme shown. A dark theme version is available.

Each agent leverages its specialty while the Supervisor coordinates the overall flow. From the user's perspective, a single chat message completes a complex task.

ActionApproval — Human-in-the-Loop

When the AI agent proposes a destructive or irreversible operation, a modal requesting human approval appears before execution.

Why HITL Matters

In a storage management context, some operations are irreversible or have immediate impact. Enabling SnapLock can never be undone. A SnapMirror break severs the replication relationship. If an AI agent autonomously executes these, recovery may be impossible. The HITL pattern ensures the agent "proposes" but the final execution decision rests with a human.

Which Operations Require Approval

Operations flagged with isDestructive: true or isReversible: false require approval:

How the Approval Flow Works

1. Agent proposes a destructive operation
2. UI displays modal (showing action, target, reason)
3. User reviews the details
4. [Approve] → operation executes / [Reject] → operation cancelled, agent notified

Example: SnapMirror Break Approval Flow

User: "Execute failover to the DR site"
    ↓
Agent: Determines SnapMirror break is required
    ↓
┌──────────────────────────────────────────┐
│ ⚠️  The agent is requesting approval     │
├──────────────────────────────────────────┤
│                                          │
│ Action:  SnapMirror break                │
│ Target:  vol_production → vol_dr         │
│ Reason:  DR failover execution           │
│                                          │
│ 🔴 This operation severs the replication │
│    relationship. Re-sync requires manual │
│    intervention.                         │
│                                          │
│ [❌ Reject]              [✅ Approve]     │
└──────────────────────────────────────────┘

UI Design

┌──────────────────────────────────────────┐
│ ⚠️  The agent is requesting approval     │
├──────────────────────────────────────────┤
│                                          │
│ Action:  User block                      │
│ Target:  DOMAIN\suspicious_user          │
│ Reason:  ARP detected abnormal write     │
│          patterns                        │
│                                          │
│ ⚠️ This operation will immediately cut   │
│    off the target user's SMB access      │
│                                          │
│ [❌ Reject]              [✅ Approve]     │
└──────────────────────────────────────────┘

Safe-side default: Reject button has autoFocus. Reflexively pressing Enter falls to the safe side. Clicking outside the modal also triggers "reject."

Irreversibility warning: Operations with isReversible: false show a red warning bar, ensuring users visually recognize the severity of the operation.

Bedrock Guardrails — Response Filtering

Bedrock Guardrails are applied to all AgentChat responses. While the PHI guardrail (Part 2) blocks based on path patterns, Guardrails filter response content itself.

Applied Checks

When Guardrails are applied, a 🛡️ badge appears on the message. Users see "some information was filtered" with filter reason details available via tooltip.

Model, Cost, and Fallback

Model Configuration

Model is configurable via bedrockModelId in portal-config.ts. Recommended: Nova Lite for testing, Claude 3.5 Haiku for production.

Cost note: Token cost per conversation depends on tool call count and file sizes. A typical "file search + summarize" conversation costs ~$0.005–$0.02 with Nova Lite. To control context window size, adjust maxHistoryMessages in portal-config.ts (default: 10). Reducing history lowers cost but loses conversation context in longer sessions.

Data residency note: When using Bedrock in ap-northeast-1 (Tokyo), input data processing completes within the same region. Deploying FSx for ONTAP, the portal, and Bedrock in the same region ensures file contents never leave the region. Important for financial institutions and healthcare organizations with data residency requirements.

Security note: File contents are included in Bedrock API request bodies, but a VPC-contained configuration is possible. Bedrock does not use request data for model training (AWS Bedrock Data Protection). With VPC endpoint routing, data never leaves the VPC.

Bedrock KB Configuration Parameters

These are starting-point recommendations. Adjust based on average file size and content characteristics.

Chunk Size tradeoff: Smaller chunks (256 tokens) improve recall but fragment context, reducing precision. Larger chunks (1024 tokens) provide richer context but allow irrelevant content to mix in. 512 tokens balances well for "file-level search." For technical documents (long sections), consider 768–1024.

Fallback Behavior

When Bedrock API is unavailable (regional outage, throttling, etc.), the agent chat displays "Cannot connect. Please use conventional search" and falls back to keyword search. The design ensures "agent unavailable ≠ portal unavailable."

Chat History Retention Policy

Set TTL on DynamoDB conversation history. Default: auto-deleted after 90 days. If auditing "who asked what" is required, separately retain CloudTrail API call logs.

Right to deletion: If a user requests deletion of their chat history, administrators can manually delete the relevant DynamoDB sessions. For GDPR/privacy law environments, implementing a self-service "Clear history" button is recommended.

Design Tradeoffs

On Streaming Responses

The current implementation uses AppSync Query (synchronous), so agent responses display only after full generation completes. For long responses (file analysis, etc.), users wait several seconds.

Token-level streaming via AppSync Subscription (WebSocket) is technically possible, but implementation complexity (reconnection handling, partial response parsing, error management) increases substantially. I've deferred this as a next step for when latency becomes a problem.

Security Model (AI Agent Specific)

Monitoring

Recommended operational metrics:

Key design decision: The agent can propose storage-admin operations, but execution is authorized against the user's Cognito Group. If a regular user asks the agent "enable SnapLock," it fails with an authorization error. The agent explains "you don't have permission for this operation."

Compliance note: When acting on AI responses about regulated data, the final judgment responsibility lies with the human who approved the operation. Agent responses are "assistive information" — not substitutes for legal or regulatory judgment. Audit trail via CloudTrail + DynamoDB session logs records "who asked what, and what was approved."

Frequently Asked Questions

The following addresses common questions from different perspectives.

Cost note: "What's the token cost per conversation? How do I control context window size?" — With Nova Lite, ~$0.005–$0.02/conversation (varies by tool call count). Adjust maxHistoryMessages to balance cost vs. context retention.

Security note: "What data leaves the VPC? Can Bedrock see file contents?" — File contents are included in Bedrock API requests, but Bedrock does not use data for model training. With VPC endpoint configuration, data stays within the VPC. S3 AP access in Internet-origin configuration also completes within the same region.

Operations note: "How do I add a new MCP tool? What's the deploy process?" — New tools are implemented as Lambda functions and registered as targets in AgentCore Gateway. Deploy via sam deploy or Amplify CI/CD pipeline. See AgentCore MCP Tools Reference for details.

End-user note: "Can I just ask 'find my expense report from last month' and it works?" — Yes. With Knowledge mode and semantic search enabled, you can search by intent without knowing file names. File Agent mode can also traverse folder structures to locate files.

Scaling note: "How does this work with multiple Knowledge Bases across departments?" — KB data sources can be specified per-volume via S3 AP, so you can create separate KBs per department volume. The agent switches target KB via bedrockKbId configuration.

Front-end note: "How do I customize the chat UI? Can I add my own components?" — The chat UI is implemented as a React component (AgentChat.tsx), supporting style customization and custom message renderers. Tool call result displays are also extensible via the ToolCallTimeline component.

Staged Adoption Steps

All AI agent features support DemoMode. They work without FSx for ONTAP for evaluation.

Step 1: No KB, No Agent (File Search Only)

Leave bedrockKbId empty in portal-config.ts. Only keyword search available.

Step 2: Add Bedrock Knowledge Base

1. Register FSx for ONTAP S3 AP as KB data source
2. Set bedrockKbId in portal-config.ts
3. Semantic search mode becomes active

Step 3: Enable AgentChat (File Agent Mode)

Deploy MCP tool Lambda. list_files, read_file, search_files become available.

Step 4: Multi-Agent Mode and HITL

Add admin operation tools (block_user, enable_snaplock, etc.). HITL modal activates automatically.

Step 5: Agent Teams and Custom Agents

Define team-specific analysis patterns as agents. Share via Agent Directory.

Resources

• GitHub: solutions/amplify-portal/
• Implementation Guide
• Getting Started Guide
• AgentCore MCP Tools Reference
• Quick Desktop MCP Setup
• PoC → Production Guide
• Scaling Guide
• AWS: Build RAG with Bedrock KB + FSx for ONTAP
• AWS: Bedrock Guardrails
• Part 1: Putting a File Portal on FSx for ONTAP S3 Access Points
• Part 2: From ARP/AI Incident Response to Regulatory Retention Management

Summary and Next Steps

I integrated AI agents into the "file portal + storage operations" foundation built in Parts 1 and 2:

This three-part series documented the portal's evolution:

1. Part 1 covered the file portal foundation (S3 AP + Amplify Gen2 / Nextcloud)
2. Part 2 added storage operations (ARP/AI, Tamperproof, regulatory retention)
3. Part 3 integrated AI agents (natural language operations, semantic search, multi-agent)

Through the progression of "browse files" → "manage storage" → "talk to AI," the portal reached a point where daily operations and data utilization complete in the browser — without opening ONTAP System Manager or the CLI.

All code is published in the GitHub repository.

For next steps, I'd suggest starting with keyword search in DemoMode, then adding a Bedrock Knowledge Base for semantic search, and layering on MCP tools and HITL after that. When you move on to a production connection, see the PoC → Production Guide.

I hope this post helps someone out there.

See you next time.