AI Social Agency
From fragmented content research to a traceable, human-approved AI workflow. A multi-agent system built on API integration, data integrity, and human oversight.
Quick view for recruiters
Problem solved
A content operation needs more than separate AI prompts. Research has to be traceable, each agent’s responsibility explicit, and publishing has to wait for an accountable human decision. Repeating paid research while debugging adds cost for nothing.
My role
Independent builder. I designed the workflow architecture, built the backend integrations, and diagnosed the API failures along the way. The framework defines 11 human-supervised roles, built out in stages.
Technologies
Key accomplishments
- Built Python and FastAPI REST integrations backed by Oracle to persist task context, research evidence, audit logs, and approval decisions.
- Integrated vidIQ through MCP into Docker-hosted n8n workflows.
- Diagnosed HTTP 422 and 403 failures and built a zero-credit replay utility.
- Implemented authenticated webhooks and an owner-approval boundary.
Verified results
- 20 keyword opportunities and 10 Shorts outliers persisted and validated in Oracle.
- 0 additional vidIQ calls to recover the research.
- Publishing stayed off after a valid owner approval.
- Results measured in engineering terms: data integrity, cost control, and safe operation.
What the build proved.
Keyword opportunities validated and persisted
YouTube Shorts outliers preserved in storage
Additional vidIQ calls needed to recover the research
Engineering outcomes: data integrity, cost control, and safe operation.
The strategy handoff is the next link in the chain. A model-availability error (HTTP 503) interrupted the last end-to-end run, and I treat provider availability as an engineering problem to design around before the stage goes live.
Who does what, and who decides.
- EntryAuthenticated webhookEvery request must carry valid credentials before anything runs.
- Internal · orchestrationn8n task routerRoutes the task and checks whether validated research is already stored.
- External · paid callsvidIQ MCP researchKeyword and Shorts research. Skipped when validated research already exists.
- Internal · validationFastAPIValidates and normalizes results and rejects ambiguous payloads.
- Internal · source of truthOracle databaseTask context, research evidence, agent runs, and audit records, outside any one workflow run.
- In validationGemini role-specific agentProduces the structured Researcher to Strategist handoff.
- Human controlOwner approval gateA person must approve before any external action.
- Off by defaultPublishingExternal actions stay off until deliberately enabled. Approval alone does not turn them on.
A high-level view. Prompts, workflow configuration, and data design stay private as this heads toward a product.
Open a layer
n8n task router
- Input
- An authenticated task request.
- Responsibility
- Decide whether validated research is already stored, then route the task. n8n coordinates and does not own state.
- Output
- A research call, or reuse of saved evidence.
- Diagnostic takeaway
- I checked whether workflow configuration survived node changes instead of assuming it did.
vidIQ MCP research
- Input
- A research task.
- Responsibility
- Keyword and YouTube Shorts research from an external service with paid calls.
- Output
- Keyword and Shorts data, delivered inside a text content wrapper.
- Diagnostic takeaway
- Valid data can arrive wrapped in an unexpected shape. Check what the boundary really returns.
FastAPI
- Input
- Research output from n8n.
- Responsibility
- Validate against the API contract, normalize, and reject ambiguous payloads instead of dropping data silently.
- Output
- Validated records ready to persist.
- Diagnostic takeaway
- The HTTP 422 was a contract mismatch, not a service fault: an array arrived where a dictionary was expected.
Oracle database
- Input
- Validated records and run events.
- Responsibility
- Source of truth for task state, evidence, agent runs, and audit records, independent of any single n8n execution.
- Output
- Persisted state that later steps read.
- Diagnostic takeaway
- Count what the database stored. The tool returned 20 keywords while my first check showed none persisted.
Owner approval gate
- Input
- A completed stage waiting for a decision.
- Responsibility
- Require an accountable human decision before external actions. External actions are off by default.
- Output
- An approved stage with the publisher unassigned and publishing still off.
- Diagnostic takeaway
- Approval and permission to publish are separate. A valid owner approval did not grant that permission.
Five decisions, each with proof.
Oracle as source of truth
Evidence, task state, and audit records live outside any single workflow run.
Proof20 keywords and 10 Shorts outliers persisted.
Structured JSON handoffs
Responsibilities and handoffs are explicit and validated between steps.
ProofRegression tests built on the real n8n output shape.
Authenticated webhooks
Requests are authenticated, and credentials are rotated and isolated.
ProofRequest accepted after credential rotation; the 403 is resolved.
Human in the loop
External actions are off by default and need a separate decision.
ProofApproval left the publisher unassigned.
Replay, do not repurchase
Saved validated research can be replayed instead of bought again.
Proof20 records written with no new vidIQ or Gemini calls.
20 returned, 0 stored. Fixed. 20 persisted.
The tool returned 20 keywords. Stored: 0.
Validated keywords: 20. Shorts preserved: 10.
Summarized from my validation runs.
Issue 1: the keywords were there, but not stored
The vidIQ tool returned 20 keywords, but my first persistence check showed zero stored.
I traced the boundary between the n8n node output, Python normalization, and API storage. The valid keyword JSON was embedded inside a text content wrapper.
I corrected the nested JSON handling and wrote regression tests that replicate the real n8n output format.
The offline normalizer regression passes, including the 20-keyword n8n output shape.
Issue 2: FastAPI rejected the saved export with HTTP 422
Replaying the saved export failed with HTTP 422.
The exported n8n response was an array. The endpoint required a dictionary.
I updated the replay utility to convert a single-item envelope into the expected request and to reject ambiguous multi-item payloads instead of silently discarding data.
The corrected script wrote 20 related keyword records and kept 10 previously stored Shorts outliers, with no additional calls to vidIQ or Gemini.
Results from the validation runs.
PASS n8n live-shape fixture: 20 keyword opportunities, offline. PASS empty keyword evidence is flagged.
Test output covering the real n8n response shape.
PASS FastAPI and Oracle now store 20 keywords and 10 Shorts outliers.A separate run from the offline test.
Stage: research Research validated: yes Keywords persisted: 20 Shorts outliers: 10 External actions: disabled
Identifiers, addresses, and credentials removed for publication.
Owner approval: valid Stage: approved Publisher: unassigned Publishing: disabled
A valid owner approval did not grant permission to publish: the publisher remained unassigned.
Checks, and their results.
- Offline normalizer regression, including the 20-keyword n8n output shapePass
- FastAPI health and safety control: healthy, external actions disabledPass
- Oracle research persistence: 20 related keywords and 10 Shorts outliersPass
- Owner approval boundary: approved stage with no publisher assigned and publishing offPass
- Authenticated n8n webhook: request accepted after credential rotationPass
- Gemini Researcher to Strategist handoff: next stage, after an HTTP 503 interrupted the last runIn validation
What I learned
The most important engineering work was not writing an agent prompt. It was validating each system boundary: the shape of returned data, what the database really stored, whether workflow configuration survived node changes, how authentication behaved, and which operations were safe to retry.
Each skill, with the proof beside it.
- Solutions architectureDiscovery · requirements mapping · API contracts · workflow diagrams
A multi-agent design with a structured handoff specification.
See architecture → - Systems integrationPython · FastAPI · REST · Oracle · SQLAlchemy · n8n · MCP
20 keyword records and 10 Shorts outliers persisted and validated.
See results → - Reliability and troubleshootingJSON schema validation · PowerShell · Python testing · API debugging
Fixed a malformed request body and an HTTP 403 credential issue, with offline regression coverage.
See the debug story → - Security and governanceHeader authentication · human approval · least privilege · kill switch
An owner-approval checkpoint with publishing disabled.
See the proof → - Agile, iterative deliveryUser stories · acceptance criteria · iterative validation
Built in verified milestones, each with a pass or fail check.
See the checks →
AI Social Agency is designed to grow into a product, so the source code, agent prompts, workflow configuration, data design, and infrastructure stay private. This page shows the engineering that makes it trustworthy, and I am happy to walk through the architecture and decisions in conversation.
Ask me how I designed the integration.
I enjoy turning an ambiguous business workflow into a secure, testable, integrated system that real users can operate.
spauleyinthecloud@gmail.com