Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Architecture/Executions

Executions

View, monitor, and manage task executions across all agents. Executions are created by manual tasks, schedules, MCP calls, and chat interactions.

See it in the product

Nothing an agent does is off the ledger

1:35Enterprise
8 chapters

What Is an Execution

An Execution is a single run of a task on an agent. Each execution records: status, started_at, completed_at, duration, message, response, error, cost, model_used, triggered_by, and claude_session_id.

Trigger Types

How an execution was initiated:

TriggerSource
manualTasks tab in agent detail
scheduleCron-based schedule
retryAn automatic retry of a failed run (charted under Scheduled)
chatChat tab in agent detail
sessionA resumable conversation turn (the Workspace)
agentAgent-to-agent call
mcpMCP client call
publicPublic chat link
webhookWebhook trigger URL
fan_outFan-out to multiple agents
loopSequential agent loop iteration
reminderAn agent's own deferred self-trigger
roomA turn inside a shared multi-agent room
a2aA task sent in by an external A2A orchestrator
operator_responseAn answer to a parked request waking the agent, on an agent with the ask-ending wake turned on (see Approvals)
operator_endingA parked request that was cancelled or dismissed waking the agent — one turn per agent per sweep, same switch; an expiry wakes nobody
caller_wakeA run this agent delegated to another agent ended, waking it for one turn (see Agent Network → Wake on Ending)
validationThe audit run that follows a scheduled run with post-run validation on (see Scheduling). Recorded and shown on the row, but not accepted as a triggered_by filter
skill_gateA request for a gated skill that waited for an operator's approval, run once it was approved (see Approvals)

Channel and voice triggers (telegram, slack, whatsapp, voip, voice, paid) are recorded too and are folded into the Channels, Voice, and Public groups on the analytics charts. Rooms and operator answers get their own Rooms and Operator queue groups, beside Loops and Reminders.

Execution Status

Every execution moves through a lifecycle: queued → running → success, failed, cancelled, or skipped, with pending_retry in between when a run is awaiting an automatic retry. A run you stop yourself terminates as cancelled — a distinct state, not a failure: it has its own filter option and badge in the Executions list, and renders neutral (not red) on the activity timeline. Some long-lived installs still carry historical rows with a legacy error status; the fleet stat cards count those alongside failed.

Parallel Capacity

Each agent has a configurable slot system (default: 3 concurrent slots). Slot TTL equals the agent timeout plus a 5-minute buffer. When all slots are occupied, new executions queue until a slot frees up.

Task Execution Service

A unified execution lifecycle layer used by all callers (UI, schedules, MCP, chat, paid). Handles slot management, activity tracking, and input sanitization.

Live Streaming

Running executions stream logs in real time via Server-Sent Events (SSE) to the Execution Detail page.

Turn Integrity

A turn that ends while a background command it started is still running has that command killed a few seconds later, so its announced result may describe work that never happened. Such a run is not recorded as a clean success: the stored response opens with a visible notice (⚠️ Background work lost: N background task(s) … were still running when this turn ended and were killed at CLI exit), and the row carries a structured turn_integrityrecord on the API. An empty record means "no evidence", never "verified healthy".

A chat turn the runtime itself reports as an error is recorded as failed, with the runtime's error as the cause — even when the turn had already printed some text (an API Error: …line, say). The one exception: when the agent's own transcript proves the turn finished, the finished answer is kept and opens with a recovery notice.

When the runtime names the API error that ended a run — for example API Error: 400 Output blocked by content filtering policy— that error is what the failed run records, rather than a guess at the cause such as an out-of-memory kill or a missing credential. This needs an agent on a current base image.

Executions Tab (Operations Page)

Operations page — Executions tab listing task runs across the fleet with Total, Success rate, Failed, and Cost stat cards and per-agent/status/trigger filters

The fleet execution list lives on the Executions tab of the Operations page (/operations?tab=executions). The legacy /executions route redirects there.

1

Lists all executions across the fleet. Admins see every agent; other users see only agents they own or that are shared with them.

2

Stat cards show Total, Completion, Failed, and Cost for the selected time window. Running and queued counts are always live, regardless of the window.

3

Filter by agent, status, trigger type, time range (1h to 30d, or all time), and free-text search over task messages. The trigger drop-down offers the common triggers (schedule, manual, chat, session, agent, mcp, public, webhook, fan_out, loop); the API accepts the others too.

4

The list loads 50 rows at a time; Load more, the last thing in the list, appends the next page. The list fills the window and scrolls inside its own region, so the header, tabs, stat cards and filters stay in view. A refresh keeps every row you loaded, and changing a filter returns the list to its first row.

5

"N running now" appears in the "N shown" row whenever executions are in flight.

6

A status dot shows Live when WebSocket updates are connected, or Polling (every 30s) as fallback.

7

Click any execution row to open its detail page (/agents/{name}/executions/{id} — this route is unchanged).

Completion Is Not Quality

"Completion" means the run finished cleanly — the process exited without error. It says nothing about whether the work was any good. That is a separate axis, recorded as an evaluation.

Evaluations are written by the platform or by a human admin — never by the agent being graded, which is the entire point of keeping them apart from reports (an agent publishes its own reports). An ungraded run has no quality score at all; that is different from scoring zero.

An agent can read its own evaluations — seeing its own bad score is the feedback loop. Only humans with admin rights can write one.

What a reader sees of who graded depends on who is reading. The agent's owner and admins — signed in, or using their own user-scoped MCP key — see the full grader, for example admin:you@example.com. Agents, other machine keys, and people the agent is only shared with see just the kind of grader: admin, workspace (a Workspace user's rating) or operator(an owner's preview rating), and never the person's name or email. The stored evaluation is not changed; only what each reader is shown.

An instance can additionally enable cross-model validation: after a validated execution, a differentmodel reviews the result. The referee is called directly by Trinity with only the task and the output — it gets no workspace, no tools, and no session, so it cannot be steered by the agent it is judging. It replaces the same-agent audit pass rather than running in addition to it, at the cost of one extra model call (typically 2–10s) billed to the referee's provider.

The Cross-model validation settings card — referee provider, model, optional base URL, and API key with platform-key fallback

Execution Detail Page

1

Displays agent name, status, timestamps, duration, cost, model used, and trigger source.

2

Shows who or what initiated the run, including scheduler-triggered executions. A task sent in by an agent on another Trinity instance over AAuth shows its identity as AAuth Caller (aauth:<agent>@<host>, a2a_caller_identity on the API).

3

Shows the full transcript/log of the execution.

4

Tool calls are recorded as a summary — which tools ran and how often — not as a second copy of the transcript.

5

For running executions, a green pulsing "Live" indicator streams output in real time.

6

Stop button terminates a running execution.

7

Continue as Chat button resumes the execution as an interactive chat session.

Durations are always non-negative, and a run that ends through a recovery path (a timeout, a restart, an expired lease) closes its activity record with a real duration rather than being left open until a sweep guesses one. When the platform loses its connection to an agent mid-turn and later collects the finished result from the agent, the run records the time the agent finished, not the time the result was collected, so its duration matches the transcript.

Tasks Tab (Per-Agent)

Agent Tasks tab showing execution history, success rate, total cost, and average duration
1

Open agent detail and click the Tasks tab.

2

Enter a task message. Optionally select a model. The Timeout options stop at the agent's execution timeout, which the label names; the cap itself is offered, and a remembered longer choice comes back if the cap is raised.

3

Click Send to start the execution.

4

View execution history with status and duration.

5

A green pulsing "Live" badge links directly to the running execution.

6

Use Make Repeatable to create a schedule from any completed task.

Execution Termination

•Stop running executions via the Stop button on the detail page.
•The system sends SIGINT first, then SIGKILL if the process does not exit.
•Queue slots are released and activity is tracked.
•A stopped run records Execution terminated by user as its error, including on an agent that takes work from the durable queue; any reply it had produced is kept as its response.

Work in the Workspace

Platform users see their executions inside the Workspace too, in the vocabulary of the chat rather than the ledger. An external client sees only the live card under their own message, never the Work tab.

The live card. When a message starts a longer job, a card under it shows the status word, how long it has been going, what the agent is doing right now, and — where the agent publishes a pipeline — the steps with the agent holding each one. Its controls are only those the platform can honour: Stop (where a stop would be accepted — your own turn, a job it handed on, or a room turn your message started), Open in Work (the rail, on this tab), and after a job that failed, timed out, was stopped or was lost, Ask about it, which pre-fills the composer with a question naming the job and how it ended and never sends on its own. A card for a finished job survives a reload; a reply that lands replaces it.

Steps show as the stages themselves when the agent publishes them. An agent that publishes none shows no steps line; the card shows what it is doing right now instead. When nobody can tell (a stopped or unreachable agent, or two runs on the same agent), the card says Steps could not be read right now.

The Work tab in the rail has two sections, plus one line — N asks waiting on you · Open in Inbox — while something waits on you (questions are answered in the Inbox, see Approvals):

SectionHolds
NowA live card per job in flight; Nothing running right now. otherwise
EarlierThe last 30 days: N in the last 30 days · latest 3 shown, with Show all N / Show fewer

Each row is labelled by kind — You asked, Handed on (a job the agent delegated), Loop run, Scheduled, Room turn, Background — and by outcome: Waiting for a slot, Working, Done, Failed, Timed out, Stopped by you, Skipped, or No longer tracked for a run that stayed "running" past the agent's own turn bound with nothing watching it. A job the agent handed on to another agent is found through the chat it started from, so it appears here even though it ran on a different agent; an agent outside your roster is named only as another agent. In a room, rows are grouped by participating agent. While anything is live the tab refreshes every 12 seconds; the collapsed rail signals N running.

API Endpoints

EndpointMethodDescription
/api/executionsGETFleet execution list. Filters: status, triggered_by, hours (default 24; 0 = all-time), agent, search; limit (max 200, default 50), offset. An unrecognised status or triggered_by is ignored rather than rejected — the list comes back unfiltered, not empty — and an unrecognised hours falls back to 24
/api/executions/statsGETFleet stat cards: total, success/failed counts, total cost for the hours window; running and queued counts always live
/api/executions/timelineGETBucketed fleet rollups for charts. group_by = hour|day|trigger|agent (default day); hours ∈ {0, 1, 6, 24, 168, 720} (default 168); optional agent. Each bucket carries total, success, failed, cost, and context use. split=trigger (with a time grouping) folds a per-trigger breakdown into each bucket and returns the trigger_order to draw it in
/api/agents/{name}/executionsGETList executions for an agent
/api/agents/{name}/executions/{id}GETGet execution details
/api/agents/{name}/taskPOSTSubmit a new task
/api/agents/{name}/evaluationsGETRead an agent's quality evaluations (access-scoped)
/api/agents/{name}/evaluationsPOSTWrite an evaluation (admin and human-only — an agent can never grade itself)
/api/enterprise/client-portal/work?agents=a,b&chat_id=GETThe Workspace's Work read for a platform session: now, earlier (bounded, with earlier_total and window_days), the open chat's delegated children, and each row's can_stop. Up to 50 agent names; off-roster names are dropped; a Workspace client token gets 404

Access control on the fleet endpoints mirrors the UI: admins see everything; other users see only owned or shared agents.

The success_ratefield name is unchanged in the API — only the UI label moved to "Completion".

MCP Tools

ToolDescription
list_recent_executions(name)List recent executions for an agent
get_execution_result(agent_name, execution_id)Get the result of a specific execution
get_agent_activity_summary(name)Get activity summary including execution stats
search_executions(query, ...)Search execution messages, responses, and errors across the agents you can access. Offered only to user- and system-scoped keys, never to agent keys. It needs a matching entitlement; where the search is not available it answers available: false rather than "no results"

See Also

  • Operations Page — The tabbed view that hosts the Executions tab
  • Workspace — The live card and the rail's Work tab
  • Agent Reports — Structured results an agent publishes about its work
  • Scheduling — Automate recurring executions with cron
  • Agent Chat — Interactive chat sessions with agents
  • Monitoring — Fleet-wide health and activity monitoring