Warp Oz Agent Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Warp Oz Agent Orchestration coordinates the lifecycle of automated lead discovery and human-in-the-loop contribution drafting. The system manages a hierarchy of data providers and large language models (LLMs) to identify relevant social conversations and prepare verified responses for users.
Orchestration operates across two primary domains: Provider Routing for data collection and Model Routing for drafting. The system prioritizes cost-effective search-based collection before escalating to expensive browser agents and uses a triage-based LLM pipeline to minimize token usage for non-actionable opportunities.
Sources: README.md:27-36, test/contribution-model-routing.test.ts:31-39
Collector Provider Orchestration
The orchestration layer executes a prioritized fallback sequence when collecting data from social platforms. It attempts the most cost-effective provider first, only escalating to high-cost methods if initial attempts fail or provide insufficient data.
Platform Fallback Logic
The system implements specific provider orders for complex platforms like YouTube and Product Hunt.
This diagram illustrates the fallback hierarchy used during data collection to balance cost and reliability.
| Platform | Orchestration Order |
|---|---|
| YouTube | Scavio Comments → TinyFish Search → TinyFish Agent → YouTube API → Fixture |
| Product Hunt | TinyFish Search+Fetch → Homepage Fetch → TinyFish Agent → PH Token → Fixture |
| Scavio Search → Fixture | |
| X (Twitter) | Scavio Search → Fixture |
Sources: README.md:27-36, test/social-provider-routing.test.ts:77-85
Contribution Drafting Pipeline
Orchestration for drafting uses a "Triage and Generate" pattern. This reduces costs by filtering out irrelevant content with cheaper models before engaging premium models for high-quality prose generation.
Model Routing Triage
When INCO_TRIAGE_ENABLED is active, the system routes the request to a triage model (e.g., DeepSeek) to decide if a contribution is worthwhile.
- Triage: The system sends document context to
deepseek-v4.1-flash. - Decision: If triage returns
abstain, the process terminates. If it returnscontinue, the system escalates. - Generation: The system calls the premium model (e.g.,
openai/gpt-6.1-sol) to produce the final draft.
Sources: test/contribution-model-routing.test.ts:31-45
Drafting Decisions
The orchestration pipeline returns one of three quality kinds based on model output and venue restrictions:
| Kind | Description | Logic Condition |
|---|---|---|
draft | A full response ready for human review. | Model decides to continue and venue allows AI text. |
brief | Reference material only; user must write the reply. | Venue prohibits AI text or provider failure occurs. |
abstain | No reply recommended. | Model determines context is not actionable or already replied. |
Sources: test/contribution-quality.test.ts:25-35, test/contribution-model-routing.test.ts:41-45
Review and Handoff State Machine
The orchestrator enforces a Human-in-the-loop (HITL) review process before allowing any agent-generated text to be used in a live conversation.
The sequence of events required to move a draft from generation to an approved handoff state.
Factual Verification
The system validates the draft against stored opportunity_evidence. Every significant claim in a draft must include a citation referencing a specific documentId and a verbatim quote from the source material.
- Claim Validation: Rejects drafts where claims reference unknown document IDs.
- Tamper Protection: Rejects approval if the
editedTextwas changed between the review start and the final approval. - Prohibited Venues: Automatically downgrades generated prose to a
brieffor platforms like Hacker News (HN) or Stack Overflow that prohibit AI-generated content.
Sources: test/draft-handoff.test.ts:35-45, test/contribution-quality.test.ts:35-50, app/opportunities/[id]/draft-panel.tsx:210-230
Data structures
Draft orchestration relies on the opportunity_draft table to maintain the state of model outputs and human edits.
| Field | Type | Purpose |
|---|---|---|
original_text | text | The immutable output from the generation model. |
edited_text | text | The user's current version of the contribution. |
citations | jsonb | Array of labels, URLs, and document IDs. |
quality | jsonb | Persists model metadata (version, kind, targetDocumentId, claims). |
approved_at | timestamp | Timestamp marking completion of human review. |
Sources: lib/db/schema.ts:286-310
Warp Oz Agent Orchestration ensures that while Vantage leverages high-scale collection and automated drafting, the final output remains grounded in evidence and subject to human oversight before external publication.
Sources: README.md:71-75, app/opportunities/[id]/draft-panel.tsx:300-310