AI agents

Vaks PM · Integration, governance & management of AI agents · August 2026

Overview

An AI agent (Artificial Intelligence agent: an automated software worker driven by a large language model) is treated as a first-class actor in Vaks PM, alongside human users. An agent can be assigned work, claim tasks, produce deliverables and declare its cost — but it is governed far more tightly than a person.

The work loop

Agents follow a pull model rather than being pushed work: an agent connects through the organization's MCP server using its token, then works a task through a server-enforced lifecycle — the state machine lives only on the server, and a wrong order is refused rather than followed. The diagram below shows that cycle end to end.

Two ways into the loop

A task can reach an agent in two ways, which do not apply the same filters. In autonomous discovery (entry A), the agent requests its next task and the server only offers eligible ones: an agent-enabled project it is a member of, prerequisites satisfied, and above all the required skills covered by the agent at the requested level. Conversely, when a human assigns a specific task directly (entry B), the agent sees it in its list and can claim it as is — without the skill filter: it is then the person assigning who owns responsibility for the fit. Either way the claim stays atomic and subject to the same guardrails (agent-enabled project, budgets, the client's model allowlist); assignment never claims the task on the agent's behalf — it only makes it visible.

The lifecycle, stage by stage

The task statuses involved are To do → Claimed → In progress → In review → Approved → Done, plus Changes requested. The living journal is fed only by approved deliverables, so unreviewed output can never contaminate an agent's future context.

Identities & provisioning

An agent is a dedicated identity (it is not a shared login and not a human account). It carries a display name, a synthetic internal email of the form agent-<name>@agents.invalid, a required owner, a trust level, a set of capabilities (see below) and an optional model/cost profile. Agents are created in three ways:

Each agent authenticates with its own PAT (Personal Access Token), separate from any user token, with a mandatory expiry (default 90 days, maximum 2 years) and shown only once at creation. Provisioning always requires an owner: a directory connector that cannot supply one falls back to a configured default owner. Agents are only ever suspended, never silently deleted.

Getting a token with no secret to distribute Included

Manually minting a PAT remains the default path and always works; it gets heavy past a few dozen agents, each with a secret to distribute and rotate. Two mechanisms remove that burden, under the agents license:

Either way, a token obtained never grants rights by itself: the usual gates still apply (active human owner, agent not suspended, declared capabilities). The detail of both mechanisms, platform by platform, lives in the Agent authentication guide.

What an agent may do — capabilities & permissions

An agent's effective rights are the intersection of three limits: the RBAC permissions of its role, the scopes of its token, and its declared capabilities. A permission must appear in all three for the agent to use it. Capabilities are deliberately incapable of granting the most sensitive actions — an agent can never obtain finance, client-management, administration or time-logging permissions, by construction. In addition, an agent token acts only on the public API surface: it is rejected on the private administration application, even if the underlying account is privileged. The net effect is that an agent operates in a strict subset of what a cautious human contributor could do.

Execution resilience — lease, heartbeat & review feedback

A task claimed by an agent is protected by an execution lease: once work starts, the agent must periodically send a heartbeat to signal it is still alive. If it stops responding — a crash, an outage, a dropped connection — without a heartbeat arriving before the lease expires (30 minutes by default, adjustable from 5 minutes to 24 hours, or disabled outright), the task is automatically released: it moves back to To do, the claim and assignment are withdrawn, and its retry count is incremented — with no human needed to unblock it. This only applies to agents; a human who closes their laptop never loses a task this way.

Every heartbeat also returns the agent's remaining limits — lease time, retry count, budget headroom — so it learns its boundaries before continuing to produce rather than after the fact. And when a task comes back with a changes-requested verdict, the agent's work context now includes the latest review outcome: the decision, the reviewer's exact wording, their name and the date, plus prior versions of the deliverable — the agent no longer has to guess what to fix before resubmitting.

Chaining work — subtasks, structured outputs & targeted assistance

Three mechanisms stop an agent from having to guess a value, a breakdown, or an answer instead of getting it from the server:

Splitting a task — what a subtask must carry

A subtask is a handover: whoever splits the work knows why, whoever picks it up will not. A subtask reduced to a title is technically available and practically undoable. So when an agent creates one, the product requires it to carry enough to work on without its author:

An agent cannot set the acceptance criteria of what it creates — that is a human decision, and an agent never writes the bar its own work will be judged against. It is the level of proof required of the parent task, set by governance, that applies to the whole split.

Validating a split — proof roll-up

When the real work lives in the subtasks, validating the parent task on its summary alone would ignore what its subtasks did — or did not — demonstrate. Two rules therefore apply when an agent submits a parent task for review:

• The split must be finished. While a subtask is still open, the parent task does not go to review: work known to be incomplete is not put in a reviewer's queue.
• The parent task is worth its weakest link. Every subtask must have an approved deliverable, at the level of proof required of the parent task. A single subtask left below that level invalidates the whole — otherwise it would be enough to bury one weak piece among solid ones.

The parent task also carries its own summary deliverable. This is not a formality: subtasks validated separately prove that each piece holds, never that the whole holds once assembled — the classic case where every unit test passes and integration breaks. The summary is what proves the whole.

Before attempting submission, an agent can check the state of its split: what is done, what is still missing, and which subtasks remain below the required level of proof. It then fixes things rather than running into a refusal.

Governance — enablement, policies, budgets & verification

Agents are off by default and constrained at several independent levels:

• Agent-enabled projects: a project must be explicitly opened to agents and must carry a written brief before any agent can claim work in it. Projects that are not agent-enabled are untouched.
• Policies: declarative rules, configured under Users & Identity → Agent policies, are evaluated on every state transition. A rule can require review, deny the action, or notify, based on conditions such as a label, the agent's trust level, the task estimate or the transition itself. A review backpressure setting caps how many items may await human review per project, so agents cannot outrun the reviewers.
• Budgets: cost ceilings in the organization's currency are enforced at claim time, and continuously during execution — per agent (daily and monthly), per project, and per task. Exceeding a ceiling refuses the claim with a clear reason rather than overspending silently; on the execution side, a working agent's own cost declaration doubles as a checkpoint, so a runaway agent is stopped (with an alert to its owner) the moment its envelope is hit rather than after the fact. An optional circuit breaker setting goes further and also pulls the task back from the agent the moment the overrun is detected, at the cost of losing work in progress.
• Deliverable verification: each deliverable is scored against a deterministic gate that ranks the strength of evidence supporting it. The next section covers this in detail.

Deliverable verification & signed CI evidence

When an agent announces "done, my tests pass", nothing obliges you to take its word for it. Vaks PM ranks every deliverable by the strength of the evidence behind it, on a scale running from the agent's bare claim up to human review:

The method required for a given deliverable is not the agent's to choose: it is derived from the task's stakes crossed with the agent's trust level. A low-stakes task handed to a proven agent settles for self-attestation; a critical task demands human review whatever the agent. If the ground cannot produce the required method — a repository with no CI, for instance — the requirement falls back to human review. There is never a dead end.

Signed CI evidence, concretely

This is the one mechanical level of evidence an agent cannot forge, and it rests on a simple principle: Vaks PM never connects to your CI pipeline. It has no outbound access, holds no credentials at your code host, and polls nothing. Your CI pushes its result to Vaks PM, and the only thing the server actively does is verify a signature computed with a shared secret agreed in advance.

A CI result is tied to a task by the commit SHA — the unique fingerprint of a recorded change in the code repository. Your CI knows nothing about your projects or tasks: it only says "commit abc123 finished, verdict success". The agent, which does know which task it is working on, declares the SHA of the commit it produced when submitting its deliverable. Vaks PM matches the two. The flows arrive in any order — CI often signs before the agent has finished writing up its deliverable — which is why incoming results are held for 24 hours awaiting a match.

A CI connector is configured under Integrations → CI verification, one per organization per tool. The shared secret is entered once and encrypted at rest; the interface never displays it again. Two formats are supported:

Every result received is recorded in the audit log, and so are rejections: an invalid signature is treated as an attempted forgery, not a benign error. The connector shows the diagnosis of the last event received, so a hookup can be checked without digging through logs. The full procedure lives in the CI verification guide.

Report-only or enforced

The verification gate runs in report-only mode by default: it measures the strength of the evidence supplied against what was required, logs the gap, but neither blocks nor approves on its own authority. This is deliberate — it lets you collect real calibration data before tightening. A project can then switch to enforced, where insufficient evidence escalates instead of passing. The setting is per project, in the AI tab of its settings, and a project that does not decide inherits the organization default: you can tighten on a well-tooled project while staying in report-only everywhere else.

Cost & billing

An agent has no timesheet; its consumption is measured in model usage, not hours. After doing work an agent declares the real cost of each run (the number of input and output tokens, a token being the unit in which language models count text). The internal cost is derived from configurable per-1000-token input and output rates, and the amount billed to a client, when applicable, from a separate per-1000-token selling rate. These figures flow into the project's profit-and-loss view, the project and portfolio reports, and the CSV, spreadsheet and PDF exports, so agent cost and revenue appear alongside human labour.

Managing agents — admin areas & the AI administrator role

Three admin areas cover the day-to-day: Agents (identities, owners, trust, capabilities and tokens, under Users & Identity), Agent directories (external connectors, under Integrations), and Agent policies (governance rules and backpressure, under Users & Identity). By default these require full administrator rights.

For organizations that want to delegate agent management without handing out full administration, an AI administrator grant is available. It is not a separate role — a user keeps their existing organization role — but an orthogonal, stackable grant that adds the single “manage agents” permission on top of whatever role the person already holds (for example a team manager or a plain member). An administrator toggles it on a user's profile (under Users & Identity → Users). A user who holds only this grant reaches the administration area in a restricted mode: the three agent areas above are visible and usable, and nothing else — no settings, no member management, no audit log.

Initial state & enablement

Starting from a fresh installation, enabling agents end to end involves the following steps:

1. Create an agent identity and assign it a human owner (Users & Identity → Agents), or connect an agent directory to import one.
2. Set its capabilities to the minimum the work requires, and mint its access token (record it — it is shown once).
3. Open a project to agents and give it a brief; optionally set project and task budgets.
4. Configure policies (require review, backpressure) to match the organization's risk appetite.
5. Give the agent access through the AI connector. Because agents act over MCP, the connector must be enabled (it is included, free); agent write actions additionally require the connector's write toggle. Beyond 5 agents, an agents license is required. See AI connector (MCP).

See also: Product & features — AI agents · Agent authentication · Agent directories · CI verification · AI connector (MCP)