skills/freckle/workflow/research-agent.md

# Research Agent

Research Agent (`researchAgent` in the node catalog) does open-ended web research. Each Research Agent node plays one of two roles, and a Workflow can carry several — one per job (recover a URL mid-waterfall, score at the end). The role choice is a plan-shape decision made during contract mapping.

Contract facts that shape the plan (inspect `researchAgent` for the full contract):

- Its config requires `prompt`, `inputs`, and `resultType`; `webResearch` is optional, and only an explicit `false` disables web research.
- Omit `model` or set `{ "mode": "managed" }` for managed OpenAI GPT-6 Luna.
- BYOK uses `mode: "byok"` with `provider`, `modelId`, and `credentialId` for an existing matching-provider workspace connection. Supported pairs: `openai` / `gpt-6-luna` (existing workflows may keep `gpt-5.6-luna`) or `anthropic` / `claude-sonnet-5` or `claude-opus-5`.
- BYOK costs zero Freckle credits, including web research; the provider bills usage, the workspace connection is revalidated on every model call, and failures never fall back to managed.
- Each `inputs` entry requires `portId`, `label`, and `type` (`description` is optional).
- `resultType` must resolve to an exact object type: no optional fields, no `unknown`, no additional properties, no tagged unions. Declare values research may not find as `nullable<...>` fields. This constrains the result-fields table you plan in step 4.
- It emits `result` (typed by `resultType`), `steps`, and an optional `sources` output port; it selects no branch cases.
- A "not found" outcome lives inside a successful `result`; a runtime node failure fails the Workflow Run.

When the user chooses BYOK, follow [OpenAI setup](../CONNECTIONS.md#openai-for-research-agent) or [Anthropic setup](../CONNECTIONS.md#anthropic-for-research-agent) to select an authorized workspace credential before setting `model.credentialId`.

**Use Jev instead when nothing needs looking up.** If the job is to classify rows into categories (such as tier 1, 2, or 3) or answer yes/no from data the row already has, use Jev › Decision agent (`decision` in the node catalog) and not Research Agent. Jev is free, it returns a tier string or a true/false that If and Switch nodes can read directly, and it fails loudly instead of guessing. It cannot browse the web, so when the answer depends on facts the row does not hold yet, use Research Agent or a provider to fetch them first, then let Jev decide on the result. Inspect `decision` for its config.

**Decision rule:** inspect the node catalog first. If a structured provider's contract covers the objective, build a waterfall with Research Agent as the backstop. If the data still has to be looked up and no structured provider covers it, Research Agent is primary — there is no waterfall to fall out of.

## Backstop: final fallback in a waterfall

The last rung of a [waterfall](waterfall.md), running only after structured providers fail or return insufficient data.

- Activate it from the last structured provider's insufficiency branch.
- Plan what it should attempt: the concrete question it must answer and the fields it must fill, not "research the row".
- Its output converges through the same collector as the structured fallbacks.
- **Exception — contact info.** Research Agent cannot reliably dig up phone numbers or email addresses from the open web, so a contact-info waterfall ends at its last structured provider, and its all-fallbacks-failed path emits the miss. Everything else — titles, companies, domains, URLs, firmographics, qualitative facts — backstops fine.

## Primary: no structured provider fits

When the requested data has no obvious integration — niche facts, qualitative judgments, anything the catalog's structured providers do not contract for — use Research Agent as the primary enrichment node.

- It stands alone: a provider whose contract does not match the objective is noise, not a rung, so a token waterfall of ill-fitting providers adds nothing.
- Still plan failure behavior: what the Workflow emits when research comes up empty.