[AI DX] AI Agent Task vs Sub-process implementation

[mesellings]

Issue: AI Agent Task vs Sub-process implementation differences are unclear

Docs improvements prompted by AI-Assisted Camunda Development: Developer Experience Feedback.

What happened

The AI Agent connector has two implementations:

• AI Agent Task (io.camunda.agenticai:aiagent:1) — applied to a service task

• AI Agent Sub-process (io.camunda.agenticai:aiagent-job-worker:1) — applied to an ad-hoc sub-process

• Both share most configuration fields but have subtle differences:

• The Task variant requires data.tools.containerElementId; the Sub-process resolves tools automatically

• The agentContext field is required for Task but optional for Sub-process

• They have separate element template files with slightly different field sets

• The documentation describes both implementations but doesn't provide a clear diff of which fields apply to which, or a decision guide for when to use each.

Why it matters

• Easy to apply the wrong field set and get cryptic validation errors
• Debugging a field mismatch between implementations wastes time
• The recommended approach (Sub-process) should be the prominent one

Suggestion

• Add a comparison table to the AI Agent connector overview showing which fields are shared, Task-only, and Sub-process-only
• Lead with the Sub-process implementation in the docs (since it's recommended) and treat Task as the advanced/alternative option
• Consider aligning the task definition types to make the distinction clearer (e.g., aiagent-task:1 vs aiagent-subprocess:1 instead of aiagent:1 vs aiagent-job-worker:1)