Scripts are the agent interface

TL;DR

ProForma integrations are becoming manifest-backed Scripts: normal workspace Scripts with enough metadata for the agent to call them directly. The Script does the work; the manifest tells the agent the inputs, outputs, secrets, writes, and side effects. That lets a request like "find tech founders in SF" become one Script call plus a warehouse verification query, instead of a long chain of guessed API calls.

Why this matters

Agents fail slowly when every tool is just a bag of affordances. They ask for schemas, inspect code, guess enums, recover from provider errors, and only then do the actual work. We saw that pattern in a Prospeo debugging thread: the agent found a contacts Script, but wrapped it in ad hoc code, misread the child Script result, fell through to raw provider docs, and spent many turns reconstructing what the installed integration already knew.

The fix was not "add a Prospeo tool." It was to make the Script itself carry the contract the agent needed.

That keeps the product model small. A prospecting integration is still a Script. A scheduled sync is still a Script. A webhook handler is still a Script. The agent interface lives on the Script as a manifest, rather than in a parallel integration system.

What changed

• Workspace context now includes compact manifest input fields for installed integration Scripts.
• The agent prompt is explicit: run saved integrations with run_script({ script, input }); use ad hoc code only for composition or recovery.
• Script composition docs now spell out the execution envelope: scripts.run(...) returns { success, output, logs, error?, durationMs? }.
• The Prospeo target-contact Script now resolves friendly person locations and returns its documented contacts.dedupedByCompany field correctly.
• The Scripts runtime docs now explain the manifest contract directly.

How it works

A Script has one runtime shape:

export default async function run(input = {}, context) {
  // Do the work.
}

The manifest is the AI-facing contract:

{
  "provider": "Prospeo",
  "operation": "find_target_contacts",
  "requiredSecrets": ["PROSPEO_API_KEY"],
  "inputSchema": {
    "properties": {
      "companyKeywords": { "type": "array" },
      "personLocations": { "type": "array" },
      "jobTitles": { "type": "array" },
      "database": { "type": "string" },
      "writeTable": { "type": "string" }
    }
  },
  "writes": [{ "table": "prospeo_target_contacts" }],
  "sideEffects": ["external_api", "warehouse_write"]
}

With that context, the agent can call:

{
  "script": "Prospeo Find Target Contacts",
  "input": {
    "companyKeywords": ["software", "AI", "startup"],
    "personLocations": ["San Francisco"],
    "jobTitles": ["Founder", "Co-Founder", "CEO"],
    "database": "scratch",
    "writeTable": "sf_tech_founders",
    "writeMode": "replace"
  }
}

The agent does not need to load provider code, scrape docs, or invent a new API client. It can run the Script, verify scratch.sf_tech_founders, and continue with a Model or Page.

Why not MCP or direct APIs?

MCP servers are useful when you need to expose an external capability to many agents or clients. Direct APIs are useful when an application has a stable service boundary and humans are comfortable owning the client code. ProForma needs something slightly different: repeatable data work inside a workspace, with warehouse writes, Secrets, execution history, Schedules, webhooks, Pages, Models, and chat transcripts all in the same object graph.

A Script manifest gives the agent the good part of a typed tool without creating a new primitive. The implementation remains editable code. The contract remains inspectable data. The execution remains auditable in Script history. The output lands in the warehouse where Models and Pages can use it.

There will still be room for MCP and direct APIs at the edges. The inside of ProForma should feel simpler: if work needs to happen again, make it a Script; if the agent should call it reliably, give it a manifest.

What's next

The next pressure point is evaluation. We should replay traces like the Prospeo founder search and score whether the agent takes the shortest manifest-backed path. We also want richer provider metadata in manifests where it matters, such as enum examples and friendly value normalization.

The direction is set: Scripts do the work, manifests explain the call, and the warehouse verifies the result.