How do you design clear and effective tasks for agents?

What you need to know

Six rules

1. One deliverable per task. "Research, write and publish" is three tasks. A compound task cannot be checked or retried in parts.
2. description = the instruction. What to use, what to do, what to leave out.
3. expected_output = the acceptance test. Specific enough to say yes or no.
4. Explicit context. Name the earlier tasks this one needs.
5. output_pydantic when anything downstream is code.
6. A guardrail for the one rule that must not break.

A task in YAML

In a project made with crewai create crew --classic, tasks live in config/tasks.yaml:

1draft_task:2  description: >3    Write a blog post for {brand} on "{topic}" using only the4    research notes. Audience: first-time mutual fund investors.5    Do not mention specific fund names or returns.6  expected_output: >7    A Markdown post of 700-900 words with an H1 title, 3-5 H28    sections, and a short "Key points" list at the end. Every9    number must appear in the research notes.10  agent: writer11  context:12    - research_task

The agent and context entries refer to method names in your @CrewBase class. {brand} and {topic} are filled from kickoff(inputs=...).

Checklist before shipping a task

A real-life example

A content team crew for a mutual-fund distributor produced posts that varied from 400 to 2,000 words and sometimes named specific funds — a compliance problem.

The original task: description="Write a blog post about {topic}", expected_output="A good blog post".

The rewrite used the YAML above, plus a guardrail that rejects any draft containing a name from a list of 300 fund names. Over the next 50 posts, all were between 700 and 900 words, and the guardrail caught 3 drafts that named funds; each passed on its first retry. Editing time per post fell from about 25 minutes to about 10. Nothing about the agents changed.

Follow-up questions to expect

• "How long should a description be?" — As long as a clear ticket: usually 3 to 8 sentences. Longer usually means it is two tasks.
• "Should I put examples in the task?" — A short example of the output format in expected_output helps; long examples cost tokens on every step.
• "YAML or Python?" — YAML keeps prompts readable and reviewable by non-engineers; Python is needed for output_pydantic, guardrails and tools, which you attach in the @task method.