[Hackathon] Add OpenRouter AI Agent operator

[ImJordanNetz]

Demo: https://youtu.be/AyJ_fjezdx8

The Story

Texera users often want to enrich rows with AI: classify support tickets, extract fields from PDFs, summarize web pages, tag biomedical notes, or normalize messy text before downstream analysis.

Today, doing that inside a workflow usually means leaving Texera, writing custom scripts, manually calling an LLM API, then bringing the results back. That breaks the workflow model. It also makes common AI enrichment tasks hard to reuse, hard to configure, and hard to run row-by-row at scale.

What if users could drag an AI operator onto the canvas, choose a model, select input columns, optionally enable tools, and produce structured output directly in the workflow?

What We Built

An OpenRouter-backed AI Agent operator for Texera workflows. It lets users call modern LLMs row-by-row, emit text or structured columns, estimate per-row cost, capture errors, and optionally let the model use URL/PDF/MCP tools.

AI Agent Operator

New workflow operator: AI Agent

Users can configure:

• OpenRouter API key
• Model from OpenRouter
• Input columns sent to the AI
• System prompt
• Text or structured output mode
• Text classification labels
• Structured output fields
• Optional cost and error columns
• Per-row cost cap
• Parallelism
• Response caching
• Built-in URL/PDF tools
• MCP server tools

OpenRouter Model Selector

The property editor includes a searchable OpenRouter model selector:

• Fetches model metadata from OpenRouter
• Groups models by provider
• Allows manually entered model IDs
• Supports an env-backed OPENROUTER_API_KEY
• Reuses cached model responses
• Serves stale model lists during temporary OpenRouter outages

Structured Output

Users can define output columns directly in the operator config.

Example fields:

Column	Type	Instructions
sentiment	classification	positive, neutral, negative
summary	text	one sentence summary
topic	classification	billing, technical, product

The agent is forced to return a final structured result, and Texera appends those fields as normal output columns.

Tool Use

The operator supports built-in tools:

• read_url fetches public web pages and returns cleaned Markdown
• read_pdf extracts text from public PDF URLs

MCP servers can also be configured so external tools appear as namespaced model-callable tools.

Safety and Reliability

This PR also hardens the implementation:

• Blocks private/local URL targets to reduce SSRF risk
• Disables local filesystem PDF reads
• Validates structured classification labels
• Scopes response cache entries by API key and operator config
• Keeps response cache instance-local
• Closes MCP clients on executor shutdown
• Avoids duplicate cost/error output columns
• Gates OpenRouter model discovery behind the copilot setting
• Avoids repeated synchronous upstream retries when serving stale model cache

How It Works Under the Hood

The operator is implemented as a standard Texera map operator.

For each input row:

1. Selected columns are rendered into a row prompt.
2. The configured system prompt and output mode are applied.
3. OpenRouter chat completion is called.
4. If tools are enabled, the model can request tool calls through a bounded loop.
5. The final answer is parsed into text or structured output columns.
6. Optional _cost_usd and _error columns are appended.

The operator uses Texera's existing schema propagation and execution infrastructure, so downstream operators see normal columns.

Demo

Open a workflow and add AI Agent.

Example:

• Input column: review_text
• Output mode: structured
• Fields:
  • sentiment
  • reason
• Model: openai/gpt-4o-mini
• Prompt: classify the review sentiment and explain briefly

Run the workflow. Each input row is enriched with AI-generated structured output.

Testing

• sbt clean compile
• sbt "WorkflowOperator / Test / compile" "AccessControlService / Test / compile"
• sbt "WorkflowOperator / testOnly org.apache.texera.amber.operator.aiagent.AIAgentResponseCacheSpec org.apache.texera.amber.operator.aiagent.AIAgentUrlSafetySpec org.apache.texera.amber.operator.aiagent.AIAgentOutputParserSpec org.apache.texera.amber.operator.aiagent.AIAgentOpDescSpec"
• sbt "AccessControlService / testOnly org.apache.texera.OpenRouterModelsResourceSpec"
• git diff --check