Clerkly

An AI agent that reads your paperwork, decides what needs to happen, and does it — pays the bill, sends it for signature, or flags it for you. Built with Strands Agents SDK + Bedrock.

Comment

Inspiration

Everyone has a pile of paperwork they keep meaning to deal with a renewal buried in an email, a contract that needs a signature, an invoice sitting unpaid because nobody got around to reading it properly. None of these tasks are hard on their own, but together they add up to hours of tedious, easy-to-forget admin work every month.

We wanted to build something that didn't just remind people about paperwork, but actually understood it read the document, figured out what needed to happen, and took the next step itself wherever it safely could. The AWS "Agents for Humans" hackathon was the perfect excuse to build exactly that.

What it does

Clerkly takes in paperwork from three places a direct document upload, a connected Gmail inbox, or a manually entered task and runs it through a small pipeline of AI agents:

  1. It reads the document and pulls out what matters: what it is, key dates, amounts, and what action is actually required.
  2. It decides what to do next. Some tasks are simple enough to complete on their own; anything involving money or a legal signature is automatically routed to a human for approval first no exceptions, enforced in code rather than left to the AI's judgment.
  3. It acts. Once approved, Clerkly can complete a real payment through Stripe, or send the actual uploaded document out for a real e-signature through DocuSign the real PDF or DOCX, not a generated summary or simply mark a task done.
  4. It keeps watch. A daily summary agent checks in on anything still pending, so nothing quietly misses its deadline and can email that summary directly, instead of requiring someone to check in.

Every step created, approved, paid, signed, completed is written to an audit trail, so there's always a clear record of what happened and why. Every task also shows exactly who created it and who approved it, since paperwork now lives inside a shared workspace rather than a single account people can be invited in by email with owner/admin/member roles, all enforced server-side. A dashboard with real-time charts (AI source breakdown, task status, activity over time) gives an at-a-glance view of what the system is actually doing.

How we built it

Clerkly's backend is built on FastAPI, with three real agents built using the Strands Agents SDK: a Document Analyzer, a Paperwork Planner, and a daily Paperwork Watch agent. Data is stored in SQLite via SQLAlchemy, with schema changes managed through Alembic migrations. Authentication uses JWT tokens with Argon2 password hashing.

We connected three real external services rather than simulating them:

  • Stripe for payments (real Checkout sessions, real webhook-driven completion)
  • DocuSign for e-signatures (real OAuth connection, real envelope creation and delivery, real signature confirmation via webhook)
  • Gmail API for reading paperwork out of a connected inbox

Every one of these uses OAuth 2.0 with PKCE where required, and every integration was tested end-to-end, not just wired up and left unverified.

The frontend is built with Next.js, Tailwind CSS, and Framer Motion, giving the whole app landing page, dashboard, task management, settings a cohesive, polished feel.

Each agent runs a three-layer AI fallback: Amazon Bedrock (Nova Lite) first, OpenAI (GPT-4o) second if Bedrock is unreachable, and a deterministic rule-based result as a last resort if neither AI provider responds. This design meant the system kept producing genuine AI-quality output through every stage of real, unplanned AWS account trouble and every time the underlying access issue changed, Bedrock started working again automatically, with zero code changes required, exactly as the architecture was designed to handle.

Challenges we ran into

The hardest part of this project wasn't the AI it was making real infrastructure actually work correctly end-to-end, which meant debugging problems that only show up when you connect to genuine external services instead of mocking them.

Getting DocuSign signatures working reliably took the most persistence:

  • A SQLite quirk that silently drops timezone information on stored dates, causing a token-refresh comparison to crash
  • A signer email field that was accidentally set to an internal user ID instead of a real email address
  • DocuSign's "embedded signing" mode silently suppressing the confirmation email because of one extra parameter
  • A webhook URL path mismatch after an ngrok tunnel restarted
  • An HMAC signature verification failure that turned out to be caused by a webhook configuration needing its own scoped signing key, separate from the account-wide key we'd already set up

Each of these needed to be diagnosed from real logs and real DocuSign responses, one layer at a time, before the full loop send, sign, confirm, auto-complete finally worked.

We also hit a bigger, unrelated obstacle: partway through building, our AWS account's access to Amazon Bedrock was blocked at the account level, with no clear timeline for resolution despite an open support case. We built deterministic fallbacks into every agent and later added OpenAI as a genuine second AI provider so the application kept producing real AI-quality results the entire time. Bedrock access was eventually restored on that account. Then, near the very end of the hackathon, the account was suspended entirely during a payment-verification review, unrelated to Bedrock a genuinely stressful moment this close to a deadline.

Rather than wait on a support ticket with no guaranteed timeline, we set up a brand-new AWS account. We configured fresh credentials, and the first real test both in the Bedrock Playground and through Clerkly's actual document upload worked immediately, with zero application code changes. The exact same fallback chain that had been quietly running on OpenAI simply started succeeding at its primary layer again, on an entirely different AWS account, because nothing about our architecture was ever tied to a specific account, only to standard AWS credentials and a model ID.

Adding multi-user support meant a real schema migration against a database with live data in it, which came with its own lessons SQLite refuses to add a column with a foreign key through a plain ALTER TABLE, requiring batch-mode table rebuilding instead.

Accomplishments that we're proud of

We're proud that Clerkly isn't a demo built around mocked integrations every payment, every signature request, and every email sync in this project is real and independently verifiable. We're also proud of the safety design: no task involving money or a legal signature can complete without explicit human approval, a rule enforced directly in the execution logic rather than left to an AI model's discretion.

We're especially proud of the resilience we built and then watched play out for real, twice: Amazon Bedrock went from working, to blocked, to running on a genuine second AI provider, to working again — and when the entire AWS account was later suspended days before submission, moving to a brand-new account required editing zero lines of application code, just fresh credentials. That's not a hypothetical resilience story; it's exactly what happened during this hackathon, under real time pressure. And we're proud of turning Clerkly from a single-user tool into a genuinely multi-tenant one without breaking anything that already worked 50 automated backend tests pass, covering the full organization lifecycle through real HTTP requests, not just internal logic.

What we learned

We learned that integrating with real third-party services surfaces a different, more valuable class of bugs than anything you'd catch testing against mocks timezone handling, exact signer field requirements, webhook signature schemes, and configuration scoping all had to be worked out from real system behavior, not assumptions. We also learned the importance of designing for graceful degradation from day one: building the fallback path into our agents before we needed it meant an unexpected AWS-side outage never blocked our progress, made adding a second AI provider a smaller decision later, and meant that even losing an entire AWS account days before the deadline was a config change, not a rebuild.

What's next for Clerkly

  • Deploy the agents to Amazon Bedrock AgentCore for production-grade hosting
  • Turn the Paperwork Watch agent's email digest into a proactive, scheduled push rather than something triggered on request
  • Expand the dashboard's analytics further trend lines over longer windows, per-organization breakdowns

Built With

Share this project:

Updates

Submission history