Inspiration
Freelancers often lose money through small, informal requests: “Can you also add this feature?” or “This should only take a few
minutes.”
Each request may seem harmless, but checking the contract, finding supporting evidence, estimating the impact, writing a change
order, requesting approval, and following up on payment takes real time. Because that administrative process is tedious, freelancers
frequently begin work without documenting the change or agreeing on additional payment.
We built ScopeGuard to handle this repetitive work while preserving the decisions that should remain human. We did not want
another chatbot that produces unsupported opinions or sends messages without permission. We wanted an evidence-backed professional
agent that works quietly in the background and surfaces only when the freelancer needs to make a decision.
Our guiding principle became:
Agents prepare. Deterministic services verify and act. Humans authorize commitments.
## What it does
ScopeGuard converts informal client requests into evidence-backed scope decisions and, when appropriate, client-ready change orders.
The freelancer begins by creating a client and project, uploading a contract or statement of work, and reviewing the scope items
extracted from that document. Extracted items remain candidates until the freelancer explicitly confirms them as the project’s
baseline.
When ScopeGuard receives a client request, it:
- Routes the request to the correct project.
- Compares it with the confirmed scope and previously accepted amendments.
- Retrieves exact supporting or contradictory evidence.
- Classifies it as covered, previously approved, irrelevant, ambiguous, or a potential scope change.
- Requests clarification when the evidence is incomplete or contradictory.
- Estimates the impact of supported additional work.
- Calculates the suggested price and terms deterministically.
- Drafts a change order and client email.
- Pauses for the freelancer to edit and approve the exact revision.
- Sends the approved message through Gmail.
- Gives the client a secure page to approve, reject, or request changes.
- Creates and reconciles a Razorpay Test Mode payment request after approval.
The AI cannot send emails, select arbitrary recipients, calculate the final price, or create payment links. Deterministic
application services perform those actions using frozen, human-approved values.
## How we built it
ScopeGuard uses a Next.js and React frontend with a FastAPI backend. PostgreSQL stores the authoritative business state,
while SQLAlchemy and Alembic manage persistence and schema migrations.
The agent workflow is built with the Strands Agents SDK and Amazon Bedrock Nova Lite. We separated reasoning into six
specialized roles:
- Contract Structure Agent: Extracts candidate scope items from authorized contract chunks.
- Scope Agent: Classifies requests against the confirmed baseline.
- Evidence Agent: Finds supporting and contradictory evidence.
- Impact Agent: Estimates effort ranges, dependencies, and assumptions.
- Change Order Agent: Creates the structured proposal.
- Communication Agent: Drafts the client-facing message.
Every role returns a strict Pydantic schema. Unknown fields, invalid evidence references, unsafe HTML, malformed estimates, and
unauthorized recipients are rejected. Agent roles receive only explicitly reviewed, read-only tools.
A deterministic evidence gate sits between classification and proposal creation. A billable proposal cannot be produced without
sufficient project-authorized evidence. If evidence is missing or contradictory, ScopeGuard creates a clarification decision
instead.
Commercial calculations use integer paise and Python Decimal, rather than model-generated numbers or binary floating-point.
Conceptually, the rounded recommendation is:
[
\text{price}
=
\left\lceil
\frac{\max(h \times r, m)}{i}
\right\rceil i
]
Where:
- (h) is the recommended effort.
- (r) is the confirmed hourly rate.
- (m) is the minimum charge.
- (i) is the configured rounding increment.
The deployed AWS architecture uses:
- Amazon API Gateway
- AWS Lambda
- Amazon Aurora PostgreSQL
- Amazon RDS Proxy with TLS
- Amazon Cognito with Authorization Code and PKCE
- Amazon S3 and AWS KMS
- Amazon EventBridge
- AWS Secrets Manager
- Amazon Bedrock
- Amazon Bedrock AgentCore
- Amazon CloudWatch and AWS X-Ray
- Amazon SES
The frontend is deployed on Vercel, while CloudFormation manages the AWS foundation and staging infrastructure.
We also built durable job execution with leases, fencing generations, retries, idempotency keys, immutable proposal revisions,
content hashes, and explicit unknown-outcome reconciliation for external actions.
## Challenges we ran into
One of the hardest challenges was deciding where agent autonomy should end. Letting a model draft a proposal is useful; letting it
independently choose a recipient, determine a final price, send an email, or request payment is unsafe.
We redesigned the architecture around a clear authority boundary so model output remains advisory until deterministic validation and human approval occur.
Evidence quality was another major challenge. A model can confidently classify a request while citing the wrong contract section or
ignoring a previous amendment. We addressed this by requiring immutable evidence identifiers, validating every identifier against
the current tenant and project, and allowing the deterministic evidence gate to overturn the preliminary model classification.
Durable external actions were also difficult. An email or payment-link request may succeed at the provider while the local worker
crashes before saving the result. Blindly retrying could send duplicate emails or create duplicate payment links.
To prevent this, we introduced:
- Persistent action records
- Stable idempotency keys
- Explicit
UNKNOWN_OUTCOMEstates - Provider reconciliation before retries
- Worker leases and fencing generations
Deployment exposed several real integration challenges. The browser uploads contracts directly to Amazon S3, so CORS had to be
aligned across Vercel, API Gateway, FastAPI, S3, and Cognito callback URLs.
We also worked through:
- CloudFormation deployment permissions
- Lambda container-image updates
- RDS Proxy connectivity
- EventBridge rule resolution
- Production Cognito OAuth configuration
- Secure direct-to-S3 uploads
- Gmail and Razorpay webhook handling
Finally, testing agent behavior required more than traditional unit tests. We created a frozen 120-case synthetic dataset containing ambiguous, contradictory, covered, stale-source, and additional-scope scenarios. This allowed us to evaluate both correct proposals and safe refusals.
## Accomplishments that we're proud of
We are especially proud that ScopeGuard is more than a prompt wrapped in a web interface. It combines agent reasoning with a durable business workflow, human approval, security controls, provider integrations, and auditable state transitions.
Highlights include:
- A deployed Next.js application and AWS backend
- Six specialized Strands roles with strict structured output
- A deterministic evidence gate that prevents unsupported proposals
- Human-confirmed contract baselines with exact source provenance
- Immutable, hash-addressed proposal revisions
- A no-account client review experience using scoped capabilities
- Gmail lifecycle and recovery services
- Razorpay Test Mode payment-link, webhook, and reconciliation logic
- Cross-tenant authorization verified using separate Cognito identities
- Durable jobs with leases, fencing, idempotency, and recovery states
- A deployed Amazon Bedrock AgentCore readiness path
- A 120-case synthetic evaluation dataset with a 60-case held-out split
- Three live Bedrock classifier evaluations with perfect proposal precision and recall
- Zero abstentions and zero invalid evidence references during those evaluations
- A current automated suite with 87 passing tests
- Successful frontend linting, type checking, and production builds
We are also proud that the project reports its verification boundaries honestly. Provider adapters may be implemented and tested
without claiming every controlled live-provider acceptance scenario has already been completed.
## What we learned
We learned that trustworthy agents need strong deterministic systems around them. Better prompts alone cannot guarantee:
- Tenant isolation
- Correct prices
- Valid recipients
- Fresh evidence
- Idempotent actions
- Safe recovery
- Accurate payment state
We also learned that “I do not have enough evidence” is a successful outcome. An agent that always produces an answer is less
useful in a professional workflow than one that knows when to request clarification.
Separating business-request identity from provider-delivery identity was another important lesson. The same request may arrive
through multiple messages, while one message may contain several requests. Treating every email as one business event would create
duplicate or incorrect decisions.
Human approval also needs to be precise. Approving “the proposal” is not sufficient when its content might change afterward.
Approval must bind the exact revision, evidence, recipient, terms, and content hash.
Finally, we learned how much production readiness depends on details outside the model. OAuth state, CORS, signed webhooks, database constraints, retries, deployment permissions, observability, and recovery procedures are all part of building a useful agent.
## What's next for ScopeGuard
Our next priority is completing the remaining controlled provider-acceptance journeys, including:
- A complete Gmail read-and-send workflow
- Confirmed Amazon SES inbox delivery
- One ScopeGuard-created Razorpay Test Mode payment completed and reconciled through its signed webhook
After that, we plan to:
- Add approved or dismissed overdue-payment reminders
- Add privacy export, retention, and account-deletion controls to the UI
- Add GitHub and Slack as optional evidence sources
- Support additional currencies and commercial policies
- Add milestone, deposit, and installment payment structures
- Support team workspaces and delegated approvers
- Expand the evaluation dataset with more adversarial contracts and request styles
- Run full cloud-recreation, backup-restore, and disaster-recovery exercises
- Build revenue-protected and time-saved dashboards from authoritative workflow facts
Our long-term vision is for ScopeGuard to become a quiet commercial safety layer for independent professionals: continuously
monitoring commitments, preparing repetitive administrative work, and involving the human only when judgment or authorization is
genuinely required.
Built With
- amazon-web-services
- fastapi
- next.js
- python
- strand-sdk
Log in or sign up for Devpost to join the conversation.