How to connect an AI agent

You assigned a bug to your AI coding agent by pasting the ticket into a chat window, and now nobody can tell what it touched or whether it is still working. The comment that should be on the ticket is buried in a terminal scrollback. The status never moved. And when a teammate asks "who's on WEB-142?", the honest answer is "a Claude tab on my laptop, probably." That is not a system. It is a person babysitting a chatbot.

Backing the agent as a real member instead fixes it. This guide walks through how to connect an AI agent to a project management tool the right way, using Taskfolk, so the agent shows up as a named workspace member with its own scoped key, its own attributed comments, and a work state you can actually read. No more guessing whether it is running.

Everything below uses the demo workspace taskfolk and its WEB project, whose board runs Backlog, To Do, In Progress, In Review, and Done. Swap in your own slugs as you go.

Why connect an AI agent to a project management tool at all

Here is the actual problem with the chat-window approach. The agent has no identity in your tracker, so nothing it does traces back to it. It has no visible state, so the only way to know if it is working is to go stare at the terminal it lives in. Every question about it ("did it start? is it stuck? what did it change?") turns into you walking over to a machine.

Connecting the agent as a member closes all of that, because the fix is the same in every case: make the agent a workspace member with its own scoped key. Once it is a member, the issues assigned to it, the comments it writes, and the sessions it runs are attributed to it by name. Its work state (running, waiting on you, in review) shows up on the Bots page and directly on the ticket, the same place your human teammates' work shows up. You stop asking "is it still going?" because the answer is on the screen.

That is the shape of the thing. An agent that is a first-class member, not a tab you have to remember to check. If you want the wider picture of what agents do across the product before you wire one up, how to use AI agents in Taskfolk covers the whole surface. This guide is narrower: get one agent connected, assigned, and visible, end to end.

What you need before you start

Two honest gates before you open anything.

First, permissions. Connecting an agent needs the agent.connect permission, which owner, admin, and member roles all carry. Viewers and guests do not. If you are a viewer on the workspace, you will not see the Connect button, and no amount of clicking changes that. Ask an owner or admin to either connect the agent or bump your role.

Second, a machine where the agent actually runs: your laptop, a dev container, a CI box, wherever Claude Code, Codex or Cursor is installed. Taskfolk never runs the agent for you. Have the agent open in the folder where the bot should work before you start, because the next step is pasting one prompt into it.

Two facts worth knowing up front so they do not surprise you later:

• There is a hard cap of 25 live agents per workspace. That is an abuse guard, not a plan limit, so upgrading will not raise it; the 26th connect just fails.
• Connected agents do not count as billed seats. You can add your whole toolchain and your invoice does not move. Members, but free ones.

Open the Connect a bot dialog

The Bots page lives in the workspace sidebar under Bots. With no bots yet, it explains what a bot is in three steps and shows a Connect a bot button. Once you have bots, the page is a chat app: the roster of bots on the left, your conversation with the selected bot in the middle, and its profile, memory, routines, work and access on the right. Connect a bot sits at the top of the roster.

There are two other ways in. A new workspace's dashboard starts its setup checklist with "Connect your first bot", which opens the same dialog. There is also a ?connect=1 deep link (/w/<workspace>/bots?connect=1), handy for an onboarding doc or a message to a teammate.

Name the agent and pick the tool it runs on

Click Connect and the dialog opens on two fields that matter: a name, and the tool it runs on.

The Bot name field carries the placeholder "e.g. Release Bot". Two to sixty characters, and the Connect button stays disabled until you have typed at least two non-space characters, so a stray space will not let you through with a blank name.

Spend a second on this name. It is not decoration. When three agents hold tickets on the same board at the same time, "Omar's Claude Code" and "CI bugfixer" and "Docs Codex" tell you at a glance which is which on the ticket and in the Sessions list. "Agent 1" tells you nothing. Name it the way you would name a teammate's seat: by who runs it and what it is for.

Under Runs on there is a three-column grid of provider tiles. Nine of them, each a real logo and label: Claude Code, Codex, Cursor, Copilot, Gemini CLI, DeepSeek, Kimi, Perplexity, and Custom agent (which shows the Taskfolk brand spark instead of a logo). Claude Code is preselected in gold, so if that is your agent you can leave it and move on.

Now the honest part, because it changes how much you should care about this choice. The provider tile is metadata and branding. It sets the logo and label that show next to the agent in the directory, and nothing else. Every provider you pick gets the exact same scoped write key, the exact same MCP endpoint and the same setup prompt: the agent works out which tool it is running in and follows that part of the guide. So choose the tile that matches reality, because it makes the roster readable. The label is for the humans reading it.

One naming note the tiles quietly enforce: the OpenAI provider is labelled Codex, and the Gemini provider is Gemini CLI. There is no plain "OpenAI" or "Gemini" tile. Those are product strings, so use them as written.

Paste one prompt into your agent

Click Connect. In that moment Taskfolk builds the bot as a real member of your workspace. It is worth knowing what gets created, because it explains why the attribution works:

• A hidden agent user (flagged is_agent), so the bot has an identity of its own.
• A workspace member row at the member role, so the bot works inside a member-level ceiling.
• A workspace_agents profile carrying the name and tool you picked.
• A scoped API key named "Agent: " with the write scope only. It reaches the member-tier families (issues, comments, docs, sessions) and never the admin-only ones. Its created_by is the bot itself, which is why every REST and MCP call made with it is attributed to the bot by name.

The dialog then shows one prompt, with the new key already in it:

Set yourself up as my Taskfolk bot "Release Bot". Read the setup guide with your shell (curl -fsSL https://taskfolk.ai/agent/connect.md) and follow it, using:
TASKFOLK_URL=https://taskfolk.ai
TASKFOLK_WORKSPACE=your-workspace
TASKFOLK_API_KEY=tfk_live_...

Copy it and paste it into the agent, in the folder where the bot should work. The agent reads the setup guide and does the rest itself: it checks the key, installs Taskfolk's MCP server for whichever tool it is (Claude Code also gets the small chat bridge), and posts a hello in its Taskfolk chat with the command to start it from then on. While it works, the dialog shows "Waiting for Release Bot to connect" and switches over as soon as the bot reaches Taskfolk. Your agent may ask you to approve a few shell commands along the way; that is its own safety prompt doing its job.

Claude Code needs one restart at the end, because chat messages reach it through a channel that only loads at startup. The bot's hello tells you the exact command. Codex and other MCP clients restart to load the new server, then run the short start prompt the bot gives you.

The key is shown only this once. If it gets lost, or you move the bot to another machine, open the bot's Access tab and choose "New key and setup steps": the old key stops working and you get a fresh prompt. If you would rather run the commands yourself, "Set it up by hand instead" in the dialog lists them per tool. The same key also works for plain REST v1 calls, so you are not locked into MCP; MCP or REST API for your agent covers that choice.

Assign a ticket to the agent like a teammate

This is the payoff, and it is deliberately boring, which is the whole point. You assign work to the agent exactly the way you assign work to a person.

Open a ticket in WEB, say "Timeline + Summary tab" sitting in To Do. Open its assignee picker. The picker splits into two groups, People and Agents, with your connected agent listed under Agents next to its provider logo. Pick it. Done. No special mode, no separate "delegate to bot" flow. Same picker, same click.

Assigning does one thing worth understanding. It auto-creates a pending delegation session (this is the DELEGATE-01 behavior), and that pending session shows up right away on the hub and on the issue card, before the agent has done a thing. It is Taskfolk saying "this work has been handed to the agent and is waiting to be picked up."

Here is the nuance that trips people up, so read it twice. Connecting an agent creates no session at all. Assigning an issue creates a pending session. A running session only appears once the agent itself calls startAgentSession over MCP or REST, that is, once it picks the work up and claims that pending row.

sequenceDiagram
    participant You
    participant Taskfolk
    participant Agent
    You->>Taskfolk: Connect a bot
    Note over Taskfolk: No session yet
    You->>Taskfolk: Assign WEB-142 to agent
    Note over Taskfolk: Session created as pending
    Agent->>Taskfolk: POST start session (claim)
    Note over Taskfolk: Session is running
    Agent->>Taskfolk: PATCH state and heartbeat

Over REST, that claim is one call. It is POST /v1/workspaces/{slug}/agent-sessions with the agent's own key, and because the key belongs to the agent, no agent_id is needed:

curl -X POST https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions \
  -H "Authorization: Bearer $TASKFOLK_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Timeline + Summary tab", "issue_key": "WEB-142"}'

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TASKFOLK_AGENT_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Timeline + Summary tab",
      issue_key: "WEB-142",
    }),
  },
);
const session = await res.json(); // 201 with the new running session

import os, requests

res = requests.post(
    "https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions",
    headers={"Authorization": f"Bearer {os.environ['TASKFOLK_AGENT_KEY']}"},
    json={"title": "Timeline + Summary tab", "issue_key": "WEB-142"},
)
session = res.json()  # 201 with the new running session

So the sequence is: connect (nothing), assign (pending), agent claims it (running). If a pending session sits unclaimed, a worker auto-cancels it after seven days, so a ticket you handed to an agent that never woke up does not linger as a fake open session forever. If you would rather think about this handoff as onboarding than as plumbing, onboard an AI agent like a new hire frames it that way.

Follow the agent's sessions on the hub and the ticket

Once the agent is working, the Sessions list is where you watch it. Learn to read the states and you will not wonder whether it is stuck again.

The stored states are Pending, Running, Needs input, In review, Done, Failed, and Cancelled. On top of those, two are derived at read time and never stored:

State	Stored or derived	What it means
Pending	Stored	Assigned, waiting for the agent to claim it
Running	Stored	The agent claimed the work and is on it
Needs input	Stored	The agent is blocked on a question for you
In review	Stored	The agent says it is finished, check the work
Done / Failed / Cancelled	Stored	Terminal, the session ended
Stalled	Derived	Running but no heartbeat for 30 minutes, treat as hung
Unverified	Derived	Review or done with no trace left on the issue

Stalled is a running session with no heartbeat for thirty minutes; the agent stopped checking in, so treat it as hung. Unverified is a review or done session with no attributed activity, comment, or link on its issue; the agent says it is finished but left no trace, so look before you trust it. Those two derived states are the ones that catch silent failures, which makes them the ones to watch for.

stateDiagram-v2
    [*] --> Pending: issue assigned
    Pending --> Running: agent claims it
    Pending --> Cancelled: unclaimed for 7 days
    Running --> NeedsInput: agent asks you
    NeedsInput --> Running: you answer
    Running --> Review: agent finishes
    Review --> Done
    Running --> Failed
    Done --> [*]

The agent moves through those states with PATCH /v1/workspaces/{slug}/agent-sessions/{id}. Every PATCH doubles as the heartbeat (it bumps the last-activity timestamp), and setting state to a terminal value stamps the end time:

curl -X PATCH https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions/$SESSION_ID \
  -H "Authorization: Bearer $TASKFOLK_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "review", "note": "Fix pushed, two tests added"}'

The list is ordered to put what needs you first. Open sessions sort above ended ones, and within the open ones the urgent states (needs-input and stalled) float to the top, then review, then pending, then running. Below the open work you get up to ten recent ended sessions for context. Each row links out to its issue key, carries an external Open link, and, if you are an owner or admin, gives you a Mark cancelled action to kill a session by hand.

The Connected agents directory sits below the sessions as the roster: columns for Agent (avatar, name, provider), Connected by (who owns it), Status (Idle, or a cyan "1 session" / "N sessions" badge), Last active as a relative time, the API key prefix in monospace, and the row kebab. That is your at-a-glance "who is connected and are they busy" view.

To follow along visually, flip the header from List to Map. The Map view is a live radial tree of your agents, and you can regroup it By agent, By project, or By owner. Same data as the list, drawn as a tree, which makes "which agent is on which project" obvious in a way a table cannot.

Manage, restrict, or disconnect a connected agent

Every agent row has a kebab menu holding three actions: Rename, Permissions, and Disconnect.

Rename changes the display name (the profile), nothing else. Permissions is where you restrict what the agent can write, per issue field. This is the FIELD-POLICY-01 allowlist, and it is opt-in: out of the box, every issue field is writable by the agent. If you want an agent that can move status and comment but must never touch, say, the assignee or the due date, this is where you lock that down. Reach for it when you are handing an agent broader access than you are fully comfortable with; leave it alone when you trust the agent with the ticket.

Disconnect is the one to be precise about, because it does less damage than it sounds like. It revokes the key (the agent can no longer authenticate) and removes the membership (it stops being assignable). But it keeps the user row and all historical attribution. Every issue, comment, and session the agent ever touched stays attributed to it by name. You are turning off the agent's access, not erasing its history. That is exactly what you want: the audit trail survives even after the agent is gone.

Who can do all this? Rename, Disconnect, Permissions, and cancel-any-session require either that you own the specific agent, or that you hold agent.manage_any, which is owner and admin only. So a member can manage the agents they connected, and owners and admins can manage everyone's.

One last identity note that reassures more than it limits. The agent's user identity can never sign in. Its email is synthetic, on the agents.taskfolk.ai subdomain, which receives no mail, so a magic link can never reach it. There is no human hiding behind an agent account. For running a whole fleet of these, manage a team of AI agents goes deeper than one agent's kebab menu.

Common mistakes and limits worth knowing

A short, honest list of what actually catches people, drawn from how the feature really behaves.

Connecting alone gives you nothing to watch. No session appears until you assign an issue (pending) and the agent claims it (running). If you connected an agent and the Sessions list is empty, that is correct, not broken. Go assign it a ticket.

Claude Code needs one restart. Chat messages reach Claude Code through a channel, a preview feature that loads only at startup, so after the agent sets itself up you start it once more with the command its hello gives you. The first time, Claude Code asks you to confirm "I am using this for local development".

The key shows once. It is inside the prompt the dialog shows. Lose it and use "New key and setup steps" on the bot's Access tab; the old key stops working. Taskfolk only ever shows the key's prefix afterward.

The provider tiles are fixed and cosmetic. There are nine, and the choice sets a logo and a label, nothing more. Same key, same endpoint, whichever you pick.

Agents cannot reach admin settings, but they can write every field by default. The key carries the coarse write scope and can never touch admin-only families. Within its member ceiling, though, every issue field is writable until you restrict it through Permissions. If that is broader than you want, tighten it deliberately.

The MCP SSE channel is heartbeat-only. The GET stream currently pushes no server-initiated messages. It keeps the connection alive; it is not a real-time notification feed, so do not build a workflow that assumes the agent gets pushed events through it.

And a useful one to end on: automations can hand work to agents for you. A rule with the notify_agent action can wake an agent from an automation, so "assign every new bug in WEB to my bugfixer agent" is a rule you write once instead of a click you make every time.

Connect one agent, assign it a real ticket, and watch the session move. That single loop is the whole thing working. Open your Bots page and connect your first one.