AI Agents

AI Agents are configurable personas that can act on your organisation’s data inside Takonaut. Each agent combines a system prompt (instructions), a granted set of tools from the Tool Catalog, and a model tier. Agents run autonomously — reading context, calling tools, and producing a written result — while still giving you fine-grained control over which actions require your approval before they execute.

Agents are org-scoped and available on plans that include the ai_agents feature. When the feature is not enabled for your organisation, the Agents section is hidden and all agent API routes return 404.

Creating an agent

Agents are managed from Settings → Agents (/admin/agents). You need the Manage AI agents permission to create, edit, or delete agents; any org member can view the list and invoke agents.

To create a new agent:

1. Click New agent.
2. Fill in the Name and Handle (slug). The handle must be unique within your org and becomes the @handle used to mention the agent in future surfaces (Phase 2). Examples: pr-reviewer, task-triager.
3. Optionally upload an avatar and write a short description so teammates know what the agent does.
4. Write the Instructions — the system prompt that defines the agent’s persona, scope, and rules. Be explicit: tell the agent what it should and shouldn’t do, what tone to use, and which parts of the org it is responsible for.
5. Choose a Model tier (standard or advanced). Higher tiers consume more AI credits per run but produce higher-quality reasoning.
6. Configure Tools — see the next section.
7. Click Save.

Tools & autonomy

Every agent has access to a Tool Catalog — a curated set of capabilities drawn from Takonaut’s MCP layer. When creating or editing an agent you can enable any combination of tools for that agent.

Current catalog entries:

GitHub tools are only available when your org has a GitHub integration connected.

The web.search tool lets an agent search the web for current information and research topics. It requires a web-search provider API key to be configured in Settings → Integrations → Web Search. Once configured, any agent with web.search enabled can issue search queries and incorporate the results into its output.

Autonomy: Auto vs Approval

For each write tool you enable, you choose how the agent executes it:

• Auto — the tool runs immediately as part of the agent’s response. Use this for low-risk writes where you trust the agent to act without a human checkpoint (e.g. creating a draft task, adding a label).
• Approval — the agent proposes the action and pauses. The run enters an awaiting_approval state and the action appears in the Pending actions queue. A human must approve or reject it before the run continues.

Read-only tools (tasks.read, github.review) always execute immediately regardless of this setting.

Running an agent

Go to the Agents page (/agents) to invoke any agent manually.

1. Select the agent from the list.
2. Enter your input — describe the task, paste context, or ask a question.
3. Click Run.

Takonaut enqueues the run as a background job. The page polls for progress and streams the agent’s output as it becomes available. Each run is recorded in the agent’s run history so you can review past results.

Runs are metered to your organisation’s AI credits. The cost depends on the model tier chosen for the agent and the number of LLM calls the run makes (one per iteration of the tool loop). See AI Credits & BYOK for details.

Approvals

When an agent hits a write tool configured with Approval autonomy, the run pauses and the proposed action appears in the Pending actions panel on the run detail page.

Each pending action shows:

• The tool the agent wants to call (e.g. Comment on PRs).
• A human-readable preview of what the action will do (e.g. “Comment on PR #42: ‘Looks good, minor nit on line 12’”).
• The Approve and Reject buttons.

Two roles can act on a pending action:

• The person who started the run (the invoker).
• Anyone with the Manage AI agents permission.

On Approve — Takonaut executes the tool with the agent’s proposed arguments, appends the result to the run’s transcript, and resumes the agent loop. The run continues until it completes or hits another approval gate.

On Reject — Takonaut appends a synthetic “action rejected by user” result and resumes, letting the agent respond to the rejection (it may try an alternative or conclude the task).

Mentioning an agent

Beyond the manual Agents page, you can summon any enabled agent by @mention — in a task comment or in the Tako chat panel.

In a task comment

Inside any task’s Comments tab, type @ to open an autocomplete list of your org’s enabled agents. Select the agent (e.g. @pr-reviewer) and finish your message, then submit the comment.

What happens next:

1. Takonaut reads the full task context (title, description, current comments, linked sprint, assignees) and passes it to the agent alongside your comment text.
2. The agent runs its tool loop as normal — it can call any of its enabled tools (subject to the same Auto/Approval rules described above).
3. When the run completes, the agent’s response is posted as a new comment authored by the agent. The comment displays the agent’s name and avatar and an Agent badge so it’s clearly distinguishable from human comments.

The invoking user is the person who wrote the @mention comment. Agent actions (e.g. tasks.write calls) are still bound by that user’s permissions — if the mentioning user cannot update a field, the agent cannot update it either.

In Tako chat

In the Tako chat panel, prefix your message with @<handle> to route that turn through the named agent instead of Tako’s default persona.

@pr-reviewer Can you summarise the open review comments on this PR?

• The agent’s configured system prompt (instructions) and enabled tools replace Tako’s defaults for that single turn.
• The next message you send without an @handle prefix reverts to the standard Tako persona automatically — you don’t need to do anything to switch back.
• Tool calls made during an agent turn follow the agent’s per-tool autonomy setting (Auto executes immediately; Approval pauses and shows the pending action inline in the chat).

Eligibility

@mention in both surfaces is gated by the ai_agents plan feature. If the feature is not enabled for your org, the @ autocomplete does not list agents and any manual @handle in a comment is treated as plain text.

Automatic triggers (workflows)

Agents can run automatically as part of a board Automation rule — no manual invocation or @mention needed. This is configured in the board’s Automations editor using the Run Agent action.

Setting up a Run Agent action

In the board’s Automations editor:

1. Create or open an existing Automation rule (choose a trigger such as Task moved to column, Task created, PR opened, etc.).
2. Add an action and select Run Agent from the action list.
3. Pick the agent to run from your org’s enabled agents.
4. Write the prompt template — a Jinja-style template string that is rendered against the trigger event before the run starts.

Prompt templates have access to the trigger’s context object. Common placeholders:

Example template for a Task moved to “In Review” rule:

Review the following task and check whether the acceptance criteria are clearly defined.

Task: {{ task.title }}

Description:
{{ task.description }}

Please list any gaps you find and suggest improvements as a comment.

Identity and credit metering

Automated runs do not run as the agent’s creator. Instead they act as the rule owner’s identity (the user who last saved the automation rule) — unless a specific run-as user has been configured on the rule. This determines which permissions the agent carries when it calls write tools.

All automated agent runs are metered to the organisation’s credit pool, not to any individual’s wallet. See AI Credits & BYOK for credit pool configuration.

Gating and approvals

• The Run Agent action is only available when the ai_agents plan feature is enabled for your org. If the feature is off, the action type is hidden in the Automations editor.
• Per-tool autonomy (Auto vs Approval) still applies to automated runs exactly as it does to manual runs. If a write tool is configured for Approval, the automated run enters awaiting_approval state and the action appears in the Pending actions queue — a human must approve it before the run continues.

Prebuilt agents

Takonaut ships a gallery of prebuilt agent templates — ready-made agents you can enable with one click. Each template comes with a sensible system prompt, pre-selected tools, and recommended autonomy settings. Once enabled, the agent is cloned into your org as a fully editable agent — you can tweak the instructions, swap tools, or rename it like any other agent.

To enable a prebuilt agent: go to Settings → Agents (/admin/agents) and open the Prebuilt agents tab. Click Enable on any template to add it to your org.

PR Reviewer

Reviews open pull requests on your organisation’s linked GitHub repository. The agent lists open PRs, reads their diffs, and produces a structured code-review comment covering potential bugs, style issues, and suggestions.

By default, posting a review comment is approval-gated — the agent drafts the comment and pauses for a human to confirm before it is posted. You can switch this to Auto once you are comfortable with the agent’s output quality.

Task Triager

Reads newly created or unassigned tasks and suggests a priority, assignee, and labels for each one, based on the task description and your org’s historical patterns.

Applying changes is approval-gated by default. The agent proposes its triage recommendations and a human confirms before the task fields are updated.

Market Analyst

Researches a market, competitor, or topic by performing a series of web searches and synthesises the findings into a structured report (summary, key players, trends, risks, opportunities).

This agent requires the web.search tool, which needs a web-search provider key configured in Settings → Integrations → Web Search. The report is returned as the agent’s output — no write tools are used, so no approval steps are required.

All capabilities — creating custom agents, @mention in tasks and Tako chat, workflow triggers, and prebuilt templates — are fully available in the current release.