DEV Community: PTODesk

How to Write a Goal an AI Agent Can Actually Finish (6 Templates)

PTODesk — Sun, 27 Sep 2026 06:01:48 +0000

By KattebTeam, AI Agents Platform

Most disappointing AI agent runs fail before the first click. The agent was not bad; the instruction was. "Find me some leads" or "keep an eye on competitors" reads fine to a person, but to an agent it has no finish line, no definition of good, and no idea what it is not allowed to do.

After watching a lot of agent runs, we think a useful goal always answers five questions. Below are the five, followed by six copy-paste templates.

The five parts of a finishable goal

Outcome - what exists when the job is done? A sheet with 20 rows, three replies posted, one report. Countable beats vague.
Source - where should the agent look? Name the sites, the inbox, the dashboard, the file.
Quality bar - what makes one result acceptable and another not? "Companies with 10-50 employees in Germany that sell B2B software" is a filter; "good companies" is not.
Limits - what must it never do? No purchases, no more than N messages, no deleting, ask before publishing.
Report - how should it prove what it did? Links, row counts, screenshots, and a plain list of what failed.

If you can't fill in all five, the agent can't either.

Six templates

1. Lead research

Find 20 companies in [niche] in [country] with [size] employees. Use [directory / search engine]. For each: name, website, one decision-maker's public profile, and one sentence on why they fit. Skip companies already in [sheet]. Do not contact anyone. Report the rows as a table.

2. Competitor price watch

Open the product pages at [list of URLs] every morning. Record price, stock status and any promotion banner. Flag any change greater than 5% compared to yesterday's row. Report only the changes.

3. Review replies

Read new reviews on [platform] since the last run. Draft a reply to each one in the reviewer's language, thanking them and addressing the specific point they raised. Post replies to 4 and 5 star reviews; for 1-3 stars, save the draft and ask me before posting.

4. Invoice follow-up

Check [billing tool] for invoices more than 14 days overdue. Send one polite reminder per client using [template], at most 10 emails per run. Never change an invoice amount. Report who was reminded and when they were last contacted.

5. Content publishing

Publish the article in [doc] to [platform] with the title, tags and cover image given. After publishing, open the public URL while signed out and confirm it loads and contains the link to [site]. Report the URL and the check result.

6. Weekly SEO check

For the keywords in [sheet], record our position and the top three competitors on [search engine]. Compare with last week. List keywords that dropped more than 3 positions and the page that replaced us.

Why the "report" part matters most

An agent that says "Done!" is not useful. An agent that says "Posted 3 of 4; the fourth platform asked for a phone number, so I stopped" is. Ask for evidence and for failures explicitly, and you will be able to trust the agent with longer jobs over time.

Try it

Take one task from your week, fill in the five parts, and run it. If the first report surprises you, the goal was missing a part; fix that part rather than rewriting everything.

We build browser-based AI agents for small teams at https://katteb.com. Questions about writing agent goals are welcome in the comments.

وكلاء الذكاء الاصطناعي (AI Agents): دليل مبسط للمبتدئين مع أمثلة عملية

PTODesk — Sat, 26 Sep 2026 02:17:17 +0000

لم يعد الذكاء الاصطناعي مجرد نافذة محادثة نكتب فيها سؤالًا فنحصل على إجابة. خلال العامين الأخيرين ظهر جيل جديد من الأنظمة يسمى "وكلاء الذكاء الاصطناعي" أو AI Agents، وهي أنظمة لا تكتفي بالرد، بل تخطط وتنفذ وتراجع نتائج عملها حتى تصل إلى هدف محدد. في هذا الدليل نشرح الفكرة من الصفر، بلغة بسيطة، مع أمثلة عملية يمكن لأي شخص أن يتخيلها في عمله اليومي.

ما هو وكيل الذكاء الاصطناعي؟

وكيل الذكاء الاصطناعي هو برنامج يعتمد على نموذج لغوي كبير، لكنه يمتلك ثلاث قدرات إضافية تجعله مختلفًا عن روبوت المحادثة العادي:

هدف واضح: لا ينتظر سؤالًا تلو الآخر، بل يُعطى مهمة كاملة مثل "اجمع لي أسعار المنافسين وضعها في جدول".
أدوات: يستطيع استخدام أدوات خارجية مثل المتصفح، والبريد الإلكتروني، وجداول البيانات، وواجهات البرمجة (APIs).
حلقة تفكير وتنفيذ: يقسم المهمة إلى خطوات، ينفذ الخطوة الأولى، يقرأ النتيجة، ثم يقرر الخطوة التالية، ويكرر ذلك حتى ينتهي.

بعبارة أخرى: روبوت المحادثة يشبه موظف استقبال يجيب عن الأسئلة، أما الوكيل فيشبه مساعدًا تنفيذيًا تكلفه بمهمة فيعود إليك بعد إنجازها.

كيف يعمل الوكيل من الداخل؟

يمكن تبسيط دورة عمل أي وكيل في أربع مراحل:

الإدراك: يقرأ الوكيل المدخلات، سواء كانت تعليمات المستخدم، أو صفحة ويب، أو ملفًا مرفقًا.
التخطيط: يحول الهدف إلى قائمة خطوات. مثلًا: افتح موقع المنافس، ابحث عن صفحة الأسعار، استخرج الباقات، قارنها بأسعارنا.
التنفيذ: يستدعي الأداة المناسبة لكل خطوة، كأن يفتح المتصفح أو يكتب في ملف.
المراجعة: يتحقق من النتيجة. إذا فشلت خطوة يعدل خطته ويحاول بطريقة أخرى.

هذه الحلقة البسيطة هي سر قوة الوكلاء؛ فهي تسمح لهم بالتعامل مع مهام متعددة الخطوات كانت تحتاج سابقًا إلى إنسان يتابعها باستمرار.

الفرق بين الوكيل والأتمتة التقليدية

قد يسأل البعض: أليست لدينا أدوات أتمتة منذ سنوات؟ الإجابة نعم، لكن الأتمتة التقليدية تعمل وفق قواعد ثابتة: "إذا حدث كذا، افعل كذا". إذا تغير شكل صفحة الويب أو جاءت رسالة بصيغة غير متوقعة، تتوقف الأتمتة.

الوكيل في المقابل يفهم السياق. إذا تغير تصميم الموقع، يبحث عن الزر الجديد. وإذا كتب العميل رسالته بلهجة عامية، يفهم المقصود. هذه المرونة هي ما يجعل الوكلاء مناسبين للمهام التي تتضمن قراءة وفهمًا واتخاذ قرارات صغيرة متتالية.

أبرز استخدامات وكلاء الذكاء الاصطناعي

1. البحث وجمع المعلومات

يمكن للوكيل أن يزور عشرات المواقع، ويقرأ الصفحات، ويستخرج البيانات المطلوبة، ثم يلخصها في تقرير أو جدول. مهمة كانت تستغرق يوم عمل كاملًا قد تنتهي في دقائق.

2. خدمة العملاء

وكيل يقرأ رسائل العملاء، ويبحث في قاعدة المعرفة، ويرد على الأسئلة المتكررة، ويحول الحالات المعقدة إلى موظف بشري مع ملخص جاهز للمشكلة.

3. كتابة المحتوى وإدارته

من اقتراح الأفكار، إلى البحث عن المصادر، إلى كتابة المسودة الأولى وتنسيقها. أدوات مثل منصة كتّاب Katteb تقدم هذا النوع من الوكلاء الذين يساعدون صناع المحتوى على البحث والكتابة والنشر ضمن سير عمل واحد.

4. العمليات الإدارية

متابعة الفواتير غير المدفوعة، وإرسال التذكيرات، وتحديث جداول المتابعة، وجدولة الاجتماعات.

5. المبيعات

البحث عن العملاء المحتملين، وتجهيز رسائل تواصل مخصصة لكل عميل بناءً على نشاطه، ومتابعة من لم يرد.

مثال عملي: وكيل لمراقبة الأسعار

لنفترض أنك تدير متجرًا إلكترونيًا صغيرًا وتريد معرفة أسعار ثلاثة منافسين كل صباح. بدون وكيل، ستفتح المواقع يدويًا وتنسخ الأسعار في جدول. مع وكيل، تكتب له تعليمات واحدة:

"كل يوم الساعة الثامنة صباحًا، افتح صفحات هذه المنتجات عند المنافسين، سجل السعر الحالي وحالة التوفر، وأرسل لي تنبيهًا إذا انخفض أي سعر أكثر من 10٪ عن سعرنا."

ينفذ الوكيل المهمة يوميًا، وإذا تغير تصميم موقع أحد المنافسين فإنه يحاول العثور على السعر في مكانه الجديد بدل أن يتوقف تمامًا.

فوائد الاعتماد على الوكلاء

توفير الوقت: المهام المتكررة تنتقل من جدول الموظف إلى الوكيل.
الاستمرارية: الوكيل يعمل ليلًا ونهارًا دون إرهاق.
تقليل الأخطاء البشرية في المهام الروتينية مثل نسخ البيانات.
قابلية التوسع: يمكنك تشغيل عدة وكلاء في وقت واحد لمهام مختلفة.
تركيز الفريق على الإبداع: عندما تختفي المهام المملة، يتفرغ الفريق للتفكير والتخطيط.

ما الذي يجب الانتباه إليه؟

رغم كل هذه المزايا، الوكلاء ليسوا سحرًا. هناك نقاط مهمة:

المراجعة البشرية ضرورية للمهام الحساسة مثل إرسال رسائل للعملاء أو الدفع.
الصلاحيات: لا تمنح الوكيل وصولًا أكثر مما يحتاجه.
وضوح التعليمات: كلما كان الهدف أوضح، كانت النتائج أدق.
الخصوصية: تأكد من طريقة تعامل الأداة مع بياناتك وبيانات عملائك.

كيف تبدأ؟

ابدأ بمهمة صغيرة ومتكررة تستهلك وقتك أسبوعيًا، مثل تلخيص رسائل البريد أو جمع بيانات من موقع معين. اكتب خطوات المهمة كما لو كنت تشرحها لموظف جديد، ثم جربها مع وكيل وراقب النتيجة. بعد أن تثق في أدائه، انتقل إلى مهام أكبر.

الخلاصة

وكلاء الذكاء الاصطناعي هم الخطوة التالية بعد روبوتات المحادثة: أنظمة تفهم الهدف، وتستخدم الأدوات، وتنجز المهام من البداية إلى النهاية. من يبدأ في تجربتها اليوم بمهام بسيطة سيكون مستعدًا عندما تصبح جزءًا أساسيًا من طريقة عمل كل فريق وكل شركة.

Five accrual denominators, one engine: modelling US sick-leave rules in code

PTODesk — Wed, 23 Sep 2026 05:33:42 +0000

If you have ever added "track paid sick leave" to a backlog, you have probably written down the rule as one hour accrued for every thirty hours worked and moved on. That constant is wrong often enough to matter, and the way it is wrong is instructive if you build anything that has to encode law.

The rule surface is wider than one constant

Seventeen states and the District of Columbia mandate paid sick-leave accrual, and they do not agree on the denominator:

1:30 — the majority, including California, New York, Colorado, New Jersey
1:35 — Rhode Island
1:37 — DC, and it varies by employer size
1:40 — Washington
1:52 — Vermont

Caps differ too. Minnesota and Washington set no annual cap at all, while California limits use to 40 hours a year and accrual to 80, which are two separate numbers people routinely collapse into one.

So the first modelling mistake is storing the denominator as a constant in the accrual service. It belongs in data.

The second mistake: no effective date

Legislatures change these numbers, and they change them on a date. If your rules table is a flat lookup keyed on state, then the day a change ships you have silently rewritten history: last year's balances recompute under this year's law, and the numbers your customers reconciled against payroll no longer reproduce.

The fix is boring and worth doing on day one — key rules on (jurisdiction, effective_from) and resolve them per ledger entry, not per employee:

create table sick_leave_rule (
  jurisdiction   text not null,
  effective_from date not null,
  hours_worked_per_hour_accrued numeric not null,  -- 30, 35, 37, 40, 52
  accrual_cap_hours  numeric,      -- null means uncapped
  annual_use_cap_hours numeric,
  carryover_allowed  boolean not null,
  citation       text not null,
  primary key (jurisdiction, effective_from)
);

The citation column looks like decoration until the first support ticket that says "our lawyer disagrees with your number." Then it is the whole product.

Balances are a fold, not a column

The related design decision: do not store a balance. Store ledger entries — opening balance, each accrual, each use, each adjustment, each carryover expiry — and compute the balance by summing them.

It costs a little at read time and it buys two things you cannot get otherwise. You can answer "why is my balance 12.5 days?" with arithmetic rather than an apology. And a rule change becomes a recomputation you can diff, instead of a migration that overwrites the evidence.

Proration is where the off-by-one lives

A mid-year hire is the classic failure. Someone joins on 15 June on a 20-day annual entitlement. The naive answer is 20 ÷ 2 = 10. The correct answer depends on what you are prorating against: 200 remaining days of the year gives 20 × 200 ÷ 365 = 10.96. Whether you then round, and in which direction, is a policy choice you should expose rather than bury — rounding down by default quietly shorts every employee a fraction of a day, every year.

What I would put in the test suite

Hire dates on 1 Jan, 29 Feb of a leap year, and 31 Dec
An employee who moves between two jurisdictions mid-year
A rule whose effective date falls mid pay period
Semi-monthly pay periods, which are not two-week periods and break any code that assumes a fixed period length
Termination mid-accrual-period, with and without payout

None of this is hard. It is just detailed, and detail is exactly what gets skipped when leave tracking is a side feature of a payroll product rather than the product itself.

I work on PTODesk, a flat-priced PTO and leave tracker for small teams, and this rules engine is the part I have rewritten most. If you are building something similar, the two decisions I would make earlier next time are: rules in data with effective dates, and balances as a fold over a ledger. Everything else was recoverable.

PTO accrual is date math, not a spreadsheet column: four things that break

PTODesk — Tue, 22 Sep 2026 21:45:11 +0000

Most small teams track paid time off in a shared spreadsheet. It works right up until it doesn't, and the failures are always the same four. I have spent the last while building a leave tracker, so here is what I learned about the math.

1. A balance should be a sum, not a cell

If the balance lives in a cell, you can never answer "why do I have 12.5 days?". Store every event instead — opening balance, each accrual, each booking, each adjustment — and derive the balance as a sum of the ledger. It costs you a join and buys you an audit trail plus the ability to show an employee the arithmetic instead of asking them to trust it.

opening   +10.96
accrual   + 0.63   (pay period 17)
usage     - 1.00
--------------------
available   10.59

2. Accrued, available and projected are three different numbers

Employees read one number and assume it is theirs. It usually isn't:

accrued — what the ledger says has been earned to date
available — accrued minus days already booked but not yet taken
projected — accrued plus what will accrue by a future date

A request in June for two weeks at Christmas is valid against projected, not against available. Systems that only model available force managers back into a side calendar, which defeats the point of tracking at all.

3. Mid-year proration is a real formula, and it is easy to get wrong

Hire someone on 15 June on a 20-day policy and they do not get 20 days, and they do not get 10 either. Over a calendar year:

20 × 200 / 365 = 10.96 days

200 being the days remaining in the year from the hire date. Rounding this to "half the year, so half the entitlement" is the single most common spreadsheet bug I have seen, and it compounds because next year's carryover is computed from it.

4. US state sick leave does not use one denominator

If you are building for US teams: seventeen states and DC mandate paid sick leave accrual, and they do not agree on the rate.

Rate	Where
1 hr / 30 worked	14 states
1 hr / 35 worked	Rhode Island
1 hr / 37 worked	DC (varies by employer size)
1 hr / 40 worked	Washington
1 hr / 52 worked	Vermont

Caps differ too — Minnesota and Washington have no annual cap at all. The practical lesson is that the rule cannot be a constant in your code. It needs an effective date and a citation, so that when a legislature changes something you can see what changed, when, and which balances were computed under the old rule.

Takeaway

If you are writing this yourself: model the ledger first, keep the three balance types distinct, prorate on days rather than months, and version your jurisdiction rules by effective date. If you would rather not write it, this is what I build at PTODesk — happy to answer questions about any of the above in the comments.