DEV Community: Nitish kumar

Our first AI agent task board had a status column agents could write to whenever they liked. Tasks got stuck. Updates raced each other. The UI showed states that made no sense. The fix was boring and it worked. Full write-up 👇

Nitish kumar — Sat, 03 Oct 2026 13:33:42 +0000

Nitish kumar

Oct 3

How we built a live Kanban board for AI agents

#ai #productivity #architecture #webdev

3 min read

How we built a live Kanban board for AI agents

Nitish kumar — Sat, 03 Oct 2026 13:30:45 +0000

At Deskferry we run AI agents that work inside tools like Gmail, Slack and HubSpot. For a long time, the only way to see what an agent was doing was a run log. Useful for debugging, useless for actually managing work.

So we built Tasks: a Kanban board where users plan work, assign it to agents, and watch cards move from Backlog to Done in real time. This post covers the three design problems that mattered most: modelling task state, pausing for human approval, and keeping the board live.

1. A task is a state machine, not a status field

The first version had a status column and agents wrote to it whenever they felt like it. That fell apart fast: tasks got stuck, two updates raced each other, and the UI showed states that made no sense.

We replaced it with an explicit state machine. Every task is in exactly one state, and only defined transitions are allowed:

backlog -> in_flight (agent assigned and picks it up)
in_flight -> needs_you (agent hits an action that requires approval)
needs_you -> in_flight (user approves or answers)
needs_you -> backlog (user rejects, task returns for rework)
in_flight -> done (agent completes all steps)
in_flight -> backlog (agent fails; error attached to the card)

The four board columns map directly to these states, so the UI can never show something the backend doesn't consider valid. Every transition is written as an event with a timestamp and the actor (agent or user), which gives us an audit trail for free.

Lesson: if agents and humans both change the same object, make illegal states impossible at the data layer, not in the UI.

2. Human-in-the-loop as a first-class state

Most human in the loop AI setups we've seen treat approval as a blocking prompt: the agent waits on a promise until someone clicks a button. That's fine in a demo and terrible in production. Users approve things hours later, servers restart, and you can't hold a process open all afternoon.

We treat "waiting for a human" as a durable state instead:

Before any action tagged as sensitive (send, spend, write to a record), the agent stops and serialises what it was about to do, including the full proposed action and the context it used to decide.
The task transitions to needs_you and an approval item appears on the user's Desk.
The agent process ends. Nothing is held in memory.
When the user approves, edits or rejects, we rehydrate the agent from the saved checkpoint and continue from the exact step it paused on.

This makes approvals cheap. A task can sit in Needs You for a minute or a weekend with no cost. It also makes the approval screen better, because the user sees precisely what will happen, not a vague "Agent wants to continue."

Lesson: approval is a pause in a workflow, not a modal dialog. Persist it.

3. Keeping the board live

A board where cards move on their own only works if the user actually sees them move. Polling every few seconds felt sluggish and wasted requests on idle boards.

Instead, every state transition from point 1 publishes an event, and the board subscribes to events for the current workspace over a persistent connection. The client applies each event to its local copy of the board, so a card slides between columns the moment the backend commits the change.

Two details made this reliable:

Events carry a version number per task. The client ignores any event older than what it already has, which handles out-of-order delivery after a reconnect.

On reconnect, the client refetches the board once, then resumes applying events. Simple, and it avoids building a replay system.

Lesson: for AI agent monitoring, the event log you already need for auditing is also the best feed for your UI.

What changed for users

The technical work was in service of one product shift. Before Tasks, people had to design an AI agent workflow before getting any value. With Tasks, they write a sentence and assign it. The agent works out the steps, the board shows progress, and the Desk collects every decision that needs a human.

That turned out to be the right abstraction for AI agent orchestration from the user's side: not a graph of nodes, but a list of tasks with owners.

Takeaways if you're building something similar
Model agent work as an explicit state machine with logged transitions.
Make human approval a persisted state with checkpoints, not a blocking call.
Drive your live UI from the same events you use for auditing.
Show users tasks and owners, not pipelines. They already know how to manage those.

Tasks is live in Deskferry now. If you want to see the board in action, you can try it free at deskferry.app. Happy to answer questions about any of this in the comments.

Your AI employees can now work as a team: introducing Agent Orchestration

Nitish kumar — Wed, 02 Sep 2026 18:29:32 +0000

Until now, a DeskFerry agent was a very good solo employee. You described a job in plain English, it connected to your tools, and it ran that job on a schedule or trigger. That worked well for one job at a time.

But real work isn't one job. Qualifying a lead is research, then scoring, then CRM hygiene, then outreach, then follow-up. Each of those is a different skill, with different tools and different failure modes. Cramming all of it into a single agent meant one giant prompt, one giant blast radius, and a lot of "why did it do that?"

As of September 1, that changes. Agent Orchestration is live in DeskFerry.

What it does

Orchestration lets one agent coordinate others. You give a brief to a lead agent, and it breaks the work down and delegates each piece to a specialist agent you've already built (or lets DeskFerry build the missing ones for you).

Concretely, agents can now:

Delegate. A lead agent hands a sub-task to another agent and waits for the result, the same way a manager assigns work.
Share context. The research agent's findings are available to the outreach agent without you copying anything between them. Memory is scoped to the workflow, not trapped in one agent.
Hand off mid-flight. A support triage agent can escalate a ticket to a billing agent with the full thread attached, then step back in when billing is done.
Run in parallel. Independent steps (enrich five leads, check three inboxes) fan out and come back together.
Pause for humans where it matters. Approvals work exactly as before, but now you can put the checkpoint at the team level — approve the final email, not every intermediate step.
What it looks like

You still describe the outcome, not the plumbing:

Every weekday at 8am, pull new HubSpot leads, research each company, score them against our ICP, draft a first-touch email for anything above 70, and post the drafts to #sales for approval before sending.

DeskFerry turns that into a small team: a coordinator, a researcher, a scorer, and a writer. Each one is a normal DeskFerry agent — you can open it, edit its instructions, swap its model, or reuse it in a different workflow. The scorer you built for inbound leads can be the same scorer your partnerships agent calls next month.

Why we built it this way

We looked at two approaches. One was a visual canvas where you draw boxes and arrows between agents. The other was letting you describe the team the way you'd describe it to a new hire. We chose the second, because the whole point of DeskFerry is that you shouldn't need to become a workflow architect to get work done.

Under the hood, the coordinator is doing the planning, but everything it decides is visible. Every delegation, every handoff, and every intermediate result shows up in the run log, so when something goes sideways you can see exactly which agent made which call.

What it means in practice
Smaller, more reliable agents. A specialist with one job and three tools is much harder to confuse than a generalist with fifteen.
Reuse. Build a skill once, call it from anywhere.
Less babysitting. The coordinator handles retries and routing so you don't get paged for a single flaky step.
Try it

Orchestration is available now. Open any existing agent, and you'll see a new option to let it delegate to other agents, or start fresh with a multi-step brief and let DeskFerry assemble the team.

If you're on a trial, this is included. If you're not, the trial is free and doesn't auto-convert.

We'd love to hear what you build. Drop your workflows in the comments, or tell us where orchestration falls short — that's the feedback that shapes what ships next.

Your agent doesn't need more tools, it needs better tool descriptions

Nitish kumar — Sun, 02 Aug 2026 16:31:35 +0000

Most agent failures I've debugged weren't reasoning failures. The model reasoned fine. It just picked the wrong tool, because the tool description didn't tell it what it needed to know.

This is an under-discussed problem, and it gets worse the more integrations you add. Here's what we've learned.

The setup

Say your agent has four calendar-ish tools available:

[
  { "name": "calendar_create_event",   "description": "Creates a calendar event" },
  { "name": "calendar_quick_add",      "description": "Adds an event from text" },
  { "name": "scheduling_book_slot",    "description": "Books a scheduling slot" },
  { "name": "meeting_schedule",        "description": "Schedules a meeting" }
]

Now: "Book me 30 minutes with Sarah on Thursday."

Which one? You don't know either, and you have context the model doesn't. The model will pick one, it'll probably work about 60% of the time, and when it's wrong the failure will be silent — an event created in the wrong system that nobody notices for a week.

Roughly 40% of our agent failures traced back to tool selection, not reasoning. That was surprising and it changed where we spent engineering time.

Why OpenAPI schemas aren't enough

A schema tells you what a tool accepts. It doesn't tell you:

What the tool is for — the use case, not the signature
When it's appropriate versus the four adjacent tools that look identical
Whether it's reversible — can you undo it, and how
What it costs — a rate-limited call and a free one shouldn't be equally attractive
What it assumes — does it require the user's calendar to be connected first?

Documentation doesn't have this either, because docs are written for humans who already know which product they're integrating with. The model is choosing between products.

What a description for an agent looks like

Here's the template we converged on:

name: calendar_create_event
purpose: >
  Create an event on the user's primary Google Calendar when you already
  know the exact date, time, and duration.
use_when:
  - The time is fully specified ("Thursday 2pm for 30 minutes")
  - The user owns the calendar being written to
do_not_use_when:
  - The time is approximate or needs negotiation → use scheduling_book_slot
  - Inviting external participants who need to pick → use scheduling_book_slot
  - The user said "find a time" rather than naming one
reversible: yes — event can be deleted via calendar_delete_event
side_effects: sends invitations to all attendees immediately
cost: low
requires: google_calendar connection active

The do_not_use_when block with explicit redirects is doing most of the work. It's not describing this tool — it's describing the boundary between this tool and its neighbours, which is exactly what the model is uncertain about.

Generating these at scale

Writing these by hand doesn't scale past a few dozen tools. Our loop:

Generate a first draft from the schema and whatever docs exist, using a model.
Ship it. It'll be mediocre.
Log every selection, along with what the agent was asked and what it picked.
When a selection is wrong, don't patch the prompt — patch the description of the tool that should have been chosen and the one that was.
Over time the descriptions become a record of every mistake the system has made.

def record_misselection(task, chosen_tool, correct_tool):
    # The fix goes in the tool metadata, not the system prompt.
    # System prompt fixes don't generalize; description fixes do.
    boundary_note = infer_distinguishing_feature(task, chosen_tool, correct_tool)
    tools[correct_tool].use_when.append(boundary_note)
    tools[chosen_tool].do_not_use_when.append(
        f"{boundary_note} → use {correct_tool}"
    )

That step 5 is the important one. Every instinct says to fix selection errors by adding rules to the system prompt. Resist it. Prompt fixes are global, they collide with each other, and they don't survive a model upgrade. Description fixes are local to the tools involved and they compose.

A cheap win: prune before you send

Related, and it saves real money: don't send every tool schema on every step of the loop. Schemas can be a large share of your token spend, because they're re-sent on every iteration, not once per run.

def relevant_tools(context, all_tools, k=8):
    # Cheap pre-filter — embedding similarity between the current
    # goal and each tool's `purpose` field
    scored = rank_by_similarity(context.goal, all_tools, key="purpose")
    return scored[:k] + always_include(all_tools)

Fewer tools in context also means better selection accuracy, so this helps twice. Most frameworks encourage handing the agent everything up front; that's the wrong default past about a dozen tools.

The bigger point

The industry is competing on model quality and integration count. Neither is where agent reliability actually comes from right now.

The semantic layer — what each tool means, when it applies, how it differs from its neighbours — is unglamorous curation work that nobody ships as a feature. It's also, in our experience, the difference between an agent that demos well and one that runs unattended.

If I were starting again I'd treat it as core product from day one instead of infrastructure to get through.

Building DeskFerry — agents across 1,500+ integrations, which is how we ended up caring about this. Questions welcome below.