Common AI Operators¶
Choosing the right operator¶
The common-ai provider ships five operators (and matching @task decorators). Use this table
to pick the one that fits your use case:
Need |
Operator |
Decorator |
|---|---|---|
Single prompt → text or structured output |
|
|
Analyze files, prefixes, images, or PDFs with one prompt |
|
|
LLM picks which downstream task runs |
|
|
Natural-language → SQL generation (no execution) |
|
|
Multi-turn reasoning with tools (DB queries, API calls, etc.) |
|
LLMOperator / @task.llm — stateless, single-turn calls. Use this for classification,
summarization, extraction, or any prompt that produces one response. Supports structured output
via an output_type Pydantic model.
LLMFileAnalysisOperator / @task.llm_file_analysis — stateless, single-turn file analysis.
Use this when the prompt should reason over file contents or multimodal attachments already chosen
by the DAG author. The operator resolves files via ObjectStoragePath and keeps the interaction
read-only.
AgentOperator / @task.agent — multi-turn tool-calling loop. The model decides which tools to
invoke and when to stop. Use this when the LLM needs to take actions (query databases, call APIs,
read files) to produce its answer. You configure available tools through toolsets.
AgentOperator works without toolsets — pydantic-ai supports tool-less agents for multi-turn
reasoning — but if you don’t need tools, LLMOperator is simpler and more explicit.