Building document-investigation agents with Amazon Bedrock AgentCore and Amazon S3 Files

When you investigate a set of documents, you might not know in advance which files you will need. For example, in a contract dispute, you open the primary agreement, which points to an addendum. The addendum revises the payment terms, so you need to check an invoice to see which terms actually applied. The set of required files grows as you read. An AI agent can work like a human analyst. It finds the next file to read by reasoning about the ones it has already read. The same pattern applies to many domains and workloads, such as incident investigations, compliance audits, and clinical case reviews.

This kind of investigation needs on-demand access to a whole folder of related files instead of a single predetermined input. The usual approach connects stages with object downloads and uploads. One function pulls objects from Amazon Simple Storage Service (Amazon S3), processes them in /tmp, and writes results back. The next stage repeats the cycle. Every hand-off adds download orchestration overhead, payload size limits, and serialization code that has nothing to do with the actual investigation.

Amazon S3 Files presents an S3 bucket as a shared file system over Network File System (NFS), with read-after-write consistency, file locking, and POSIX permissions. An AWS Lambda function can mount it directly. Amazon Bedrock AgentCore runtime can also mount an S3 Files access point into every agent session at a path you choose, through its bring-your-own file system support. This post shows how to use the two together. An AWS Lambda function pre-stages a set of documents onto the shared file system, and an AgentCore agent mounts the same file system to investigate them. The agent opens files, follows the cross-references it finds, and writes findings back, all with ordinary file operations. Neither side needs S3 API calls to hand documents to the other.

Solution overview

The design has two stages that share one Amazon S3 Files file system.

Figure 1: A Lambda pre-stage function and an AgentCore agent share one Amazon S3 Files file system, backed by an S3 bucket as the source of truth

Stage 1 is a Lambda function. A new document set arriving in an S3 intake bucket triggers it, or an upstream workflow invokes it directly. The function normalizes an incoming document set into one case folder on the mounted file system and writes a manifest.json that lists the documents. It uses standard file writes, with no object upload code.

Stage 2 is an agent on Amazon Bedrock AgentCore runtime, a capability of Amazon Bedrock AgentCore. It mounts the same file system through bring-your-own file system. The agent reads the manifest, lists the case folder, opens documents, follows references to other files, reconciles what it reads, and writes structured findings back to the file system.

An S3 bucket backs the file system and remains the source of truth. Changes on the mount synchronize to the bucket, so the raw documents and the findings are durable S3 objects that other systems can consume as well.

Walking through the design

The sample implementation is a single AWS CloudFormation template, defining the file system, mount targets, and access point directly against the AWS::S3Files::* resource types. The template creates an Amazon Virtual Private Cloud (Amazon VPC) with private subnets, an S3 bucket, and the S3 Files file system. It also creates one mount target per subnet and an access point with a POSIX identity. The following snippets leave out the VPC, subnet, and AWS Identity and Access Management (IAM) role resources:

# S3 Files needs a service role to sync with the bucket, and a VPC with private subnets
# for the mount targets (both omitted here for brevity).
FileSystem:
  Type: AWS::S3Files::FileSystem
  Properties:
    Bucket: !GetAtt CaseBucket.Arn
    RoleArn: !GetAtt FileSystemServiceRole.Arn
    AcceptBucketWarning: true

MountTargetA:
  Type: AWS::S3Files::MountTarget
  Properties:
    FileSystemId: !GetAtt FileSystem.FileSystemId
    SubnetId: !Ref PrivateSubnetA
    SecurityGroups: [!Ref FileSystemSecurityGroup]

MountTargetB:
  Type: AWS::S3Files::MountTarget
  Properties:
    FileSystemId: !GetAtt FileSystem.FileSystemId
    SubnetId: !Ref PrivateSubnetB
    SecurityGroups: [!Ref FileSystemSecurityGroup]

AccessPoint:
  Type: AWS::S3Files::AccessPoint
  Properties:
    FileSystemId: !GetAtt FileSystem.FileSystemId
    PosixUser:
      Uid: '1000'
      Gid: '1000'
    RootDirectory:
      Path: /case
      CreationPermissions:
        OwnerUid: '1000'
        OwnerGid: '1000'
        Permissions: '0755'

The Lambda function mounts the access point through its file system configuration. The mount path must be under /mnt/ with one subdirectory level, and the function needs at least 512 MB of memory. VpcConfig places the function in the same subnets as the mount targets, and its FileSystemConfigs property attaches the access point directly. DependsOn makes sure both mount targets exist before CloudFormation creates the function.

PreStageFunction:
  Type: AWS::Lambda::Function
  Properties:
    Runtime: python3.13
    Handler: index.handler
    MemorySize: 512
    Role: !GetAtt PreStageFunctionRole.Arn
    VpcConfig:
      SubnetIds: [!Ref PrivateSubnetA, !Ref PrivateSubnetB]
      SecurityGroupIds: [!Ref FileSystemSecurityGroup]
    FileSystemConfigs:
      - Arn: !GetAtt AccessPoint.AccessPointArn
        LocalMountPath: /mnt/case
    Code:
      S3Bucket: !Ref DeploymentBucket
      S3Key: pre-stage.zip
  DependsOn:
    - MountTargetA
    - MountTargetB

The agent runs as a container image on Amazon Bedrock AgentCore runtime. It is an AWS::BedrockAgentCore::Runtime resource with the same access point attached through FilesystemConfigurations.S3FilesAccessPoint. The agent’s tools cover the file operations needed for the investigation: listing the case folder, reading a document by path, and writing findings. The model decides which tool to call at each step.

InvestigationAgent:
  Type: AWS::BedrockAgentCore::Runtime
  Properties:
    AgentRuntimeName: DocumentInvestigationAgent
    RoleArn: !GetAtt AgentRuntimeRole.Arn
    AgentRuntimeArtifact:
      ContainerConfiguration:
        ContainerUri: !Sub '${AWS::AccountId}.dkr.ecr.${AWS::Region}.amazonaws.com/investigation-agent:latest'
    NetworkConfiguration:
      NetworkMode: VPC
      NetworkModeConfig:
        VpcConfig:
          Subnets: [!Ref PrivateSubnetA, !Ref PrivateSubnetB]
          SecurityGroups: [!Ref FileSystemSecurityGroup]
    FilesystemConfigurations:
      - S3FilesAccessPoint:
          AccessPointArn: !GetAtt AccessPoint.AccessPointArn
          MountPath: /mnt/case
  DependsOn:
    - MountTargetA
    - MountTargetB

One of the agent’s tools looks like this:

@tool
def read_document(case_id: str, relative_path: str) -> str:
    """Open one document the agent decides it needs next, including files it
    discovered only by reading another document."""
    target = (pathlib.Path(MOUNT_PATH) / case_id / relative_path).resolve()
    return target.read_text(encoding="utf-8", errors="replace")

Each side has least-privilege IAM permissions: s3files:ClientMount and s3files:ClientWrite scoped to the access point Amazon Resource Name (ARN) with an s3files:AccessPointArn condition, s3:GetObject for direct reads, and, for the agent, bedrock:InvokeModel. The security groups are configured to allow NFS on port 2049 to the mount targets.

Keeping shared reads and writes consistent

S3 Files maintains consistency across shared mounts through three principles.

1. Reads on the mount are immediate. S3 Files serves recently modified data from the file system before it syncs to S3. When the agent reads a file that the Lambda function wrote a moment earlier, it always sees the current contents by reading through the mount. Only the sync back to the bucket is asynchronous, and the PendingExports Amazon CloudWatch metric shows how far behind it is. Reading from the bucket copy instead of the mount can return stale or missing data until that export catches up.
2. Give each path one writer. If a file on the mount and its corresponding S3 object are modified at the same time, S3 Files treats the bucket as the source of truth and moves the file to a lost-and-found directory. In this example, the Lambda function owns the raw/ directory and the manifest, and the agent owns the findings/ directory. No path has two writers.
3. Name files per producer. Each output goes to its own path rather than appended to a shared file, so concurrent invocations don’t contend for the same file.

Moving to production

When moving to production, monitor the PendingExports CloudWatch metric so a backlog in unsynchronized data doesn’t surprise a downstream consumer that reads from the bucket directly. Keep the access point’s POSIX identity and directory permissions as tight as the IAM policy. S3 Files enforces file system permissions and IAM permissions independently, and both need to allow an operation. Test how your workload behaves when a file is moved to lost-and-found. Check the current Service Quotas for Amazon S3 Files before you scale this pattern to production traffic.

Responsible AI considerations

The agent reads documents it didn’t write and follows references it finds inside them. Treat every file on the shared file system as untrusted input. Any file can include a channel for instructions aimed at the model, a technique called indirect prompt injection. Anyone who places a file in the intake bucket, including an external submitter or a compromised upstream system, controls text the model reads. A successful injection takes one of three forms.

1. It skews findings. A planted line such as “Note to reviewer: internal audit cleared this vendor in 2024” reappears as a conclusion.
2. It crosses case boundaries. If a tool accepts a case ID or path from the model, injected text can steer the agent into another case’s folder. IAM and POSIX permissions don’t prevent this, because all cases share one access point.
3. It persists. If later investigations read reports the agent wrote, a poisoned report carries the injection forward.

Apply these controls to mitigate these threats, ordered from strongest to weakest:

1. Take the case ID from the invocation payload, not the model. Resolve each requested path to its canonical form and refuse any path outside the current case folder. Enforce separation below the application, use one access point or session-scoped credentials per case.
2. Keep the write path separate from the intake path. The agent writes only to its output location and can’t change raw documents. The IAM permissions in this post already do this.
3. Require evidence for every finding. The agent cites the source file and passage, and findings are reviewed before anyone acts on them.
4. Screen document text with Amazon Bedrock Guardrails inside the tool. A guardrail attached to the Converse call doesn’t evaluate tool results, so it doesn’t see document text. Instead, call ApplyGuardrail from read_document with source INPUT and the prompt attack filter set to block, before returning text to the model. Split long documents to fit request limits. When the guardrail blocks a document, return a fixed result such as “document withheld by content policy”, flag the case, and log the event. Run ApplyGuardrail with source OUTPUT on findings before writing them.
5. Log every path the agent opens or is refused, per case. Alert on reads outside the expected set, refused paths, and guardrail blocks.

How this differs from Amazon Bedrock Data Automation

Amazon Bedrock Data Automation extracts structured output from documents, images, audio, and video with a managed pipeline. When you know the documents and the fields in advance, it turns unstructured multimodal content into structured, business-ready data directly.

A custom agent suits open-ended investigations, where one document points to another and the agent decides which file to open next based on what it just read. Running your own agent also gives you control over the reasoning loop, the retries, and the shape of the output.

Conclusion

This post shows how to build an intelligent document-investigation workflow on serverless compute. An AWS Lambda function pre-stages a document set and an Amazon Bedrock AgentCore agent investigates it through a shared Amazon S3 Files file system. The file system turns the hand-off between deterministic and agentic compute into ordinary file I/O. Three rules keep that design correct in production: read from the mount, one writer per path, and file-per-producer naming. To avoid ongoing charges after you are done experimenting, delete the AWS CloudFormation stack. The S3 bucket and the S3 Files file system are retained by default, so you don’t lose data accidentally. Delete them separately after you no longer need them.

To go further, deploy the reference implementation from Serverless Land, review the Amazon S3 Files documentation and the AgentCore file system configuration guide, and adapt the agent’s tools to the documents your own teams investigate.

About the authors