Agent Lifecycle
Every Trinity agent follows a well-defined lifecycle from creation to deletion. This page covers the permission model that controls inter-agent communication, the execution system that manages task runs, and the full lifecycle state machine.
Agent Permissions
Explicit Permission Model
Restrictive by default — no agent can call another without explicit permission
How It Works
Open the agent detail page and click the Permissions tab (located in the agent files/config area).
You will see a list of all agents in the system.
Toggle permissions to allow or deny each agent from calling the current agent.
Permissions are directional: allowing Agent A to call Agent B does not allow Agent B to call Agent A. Each direction must be granted separately.
System agents (e.g., trinity-system) bypass permission checks entirely.
Default Behavior
- •No permissions are auto-granted. All inter-agent communication must be explicitly allowed.
- •The system agent (
trinity-system) can call any agent without requiring permission.
Enforcement
- •When Agent A attempts to call
chat_with_agent("agent-b", ...), the MCP server checks whether Agent A has permission to communicate with Agent B. - •If permission has not been granted, the MCP tool returns an error and the call is blocked.
- •Permissions also gate shared folder access and event subscriptions between agents.
Permissions are managed through the agent files/config endpoints. Agents do not need to handle permissions themselves. All MCP tools respect the permission model automatically. If a tool call targets another agent, the permission check happens before execution. No special handling is required in agent code.

Executions
View, monitor, and manage task executions across all agents. Executions are created by manual tasks, schedules, MCP calls, and chat interactions.
Execution Concepts
Execution — 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.
Execution Status — Every execution moves through a lifecycle: queued → running → success, failed, error, cancelled, or skipped.
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.
Trigger Types
| Trigger | Source |
|---|---|
manual | Tasks tab in agent detail |
schedule | Cron-based schedule |
chat | Chat tab in agent detail |
session | A resumable conversation turn (the Workspace) |
agent | Agent-to-agent call |
mcp | MCP client call |
public | Public chat link |
webhook | Webhook trigger URL |
fan_out | Fan-out to multiple agents |
loop | Sequential agent loop iteration |
reminder | An agent's own deferred self-trigger |
room | A turn inside a shared multi-agent room |
a2a | A task sent in by an external A2A orchestrator |
Fleet Execution List
The fleet execution list lives on the Executions tab of the Operations page at /operations?tab=executions (the legacy /executions route redirects there):
- •Lists all executions across the fleet — admins see every agent; other users see only owned or shared agents
- •Filter by agent, status, trigger type, time range, and free-text search over task messages
- •Click any execution row to open its detail page
See Executions for the full reference.
Execution Detail Page
- •Displays agent name, status, timestamps, duration, cost, model used, and trigger source
- •Shows the full transcript/log of the Claude Code execution
- •For running executions, a green pulsing “Live” indicator streams output in real time
- •Stop button terminates a running execution
- •Continue as Chat button resumes the execution as an interactive chat session
Tasks Tab (Per-Agent)
- •Open agent detail and click the Tasks tab
- •Enter a task message. Optionally select a model.
- •Click Send to start the execution
- •View execution history with status and duration
- •A green pulsing “Live” badge links directly to the running execution
- •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
Execution API and MCP Tools
| Endpoint | Method | Description |
|---|---|---|
/api/agents/{name}/executions | GET | List executions for an agent |
/api/agents/{name}/executions/{id} | GET | Get execution details |
/api/agents/{name}/task | POST | Submit a new task |
| MCP Tool | Description |
|---|---|
list_recent_executions(name) | List recent executions for an agent |
get_execution_result(id) | Get the result of a specific execution |
get_agent_activity_summary(name) | Get activity summary including execution stats |
The Agent Detail Page
Click any agent to open its detail page. The page lands on the Overview tab and organizes everything else into tabs:
| Tab | ?tab= | Purpose |
|---|---|---|
| Overview | overview | Default landing tab — trends, health, recent activity |
| Tasks | tasks | Headless task execution and history |
| Chat | chat | Stateless conversation |
| Dashboard | dashboard | The agent's own dashboard — only when it ships a dashboard.yaml |
| Brain | brain | Knowledge-graph page — only for agents that declare the capability |
| Reports | reports | Structured results the agent published |
| Canvas | canvas | The surface the agent keeps current |
| Schedules | schedules | Cron-based automation |
| Loops | loops | Sequential bounded task runs |
| Skills | skills | The agent's own skills and those shared from the library, each with Run; owners also set approval and assign skills |
| Payments | nevermined | Paid access configuration |
| Channels | channels | External clients and channels (owners only) |
| Permissions | permissions | Which agents may call this one (owners only) |
| A2A | a2a | External-orchestrator interoperability (owners only, where available) |
| Git | git | Git status, pending changes, recent commits, Pull, Push and Refresh — only for GitHub-synced agents |
| Files | files | Workspace file browser |
| Settings | settings | The one configuration home (owners only), pinned last on the strip: a rail of panes — General, Credentials, Guardrails, People, Channels, Integrations, Storage — with the pane in ?section= |
Tabs marked owners only are hidden from users an agent is merely shared with. The system agent shows none of them except Settings, where it gets the General (read-only), Guardrails and Integrations panes. Dashboard, Brain, Git, and A2A appear only when that agent or instance supports them. The Reports tab is described under Agent Reports; Canvas under Agent Canvas; Skills under Skills; Settings under Agent Configuration.
The Info, Credentials, Access and Folders tabs no longer exist. Template details are under Settings › General, credentials under Settings › Credentials, shared folders under Settings › Storage, and the access roster under Settings › People.
Every visible tab is deep-linkable with ?tab= — including the conditional ones. The URL follows the tab you pick, so a reload keeps you on that tab, you can copy the address to link to it, and the browser's Back button steps back through the tabs you visited before it leaves the page. Returning to an agent page through a link that names no tab (from the Dashboard, say) keeps the tab you were on, as long as that agent has it. A ?tab= value naming a tab you cannot see falls back to Overview, and the address is corrected to match.
Inside Settings the pane is in the URL too: ?tab=settings§ion=general|credentials|guardrails|people|channels|integrations|storage. A bare ?tab=settings opens General, a section naming a pane you cannot see lands on the first pane you can, and Back steps between the panes you visited. Legacy links still resolve: ?tab=info opens Settings › General, ?tab=guardrails opens Settings › Guardrails, ?tab=credentials opens Settings › Credentials, ?tab=folders opens Settings › Storage, ?tab=access opens Settings › People, ?tab=playbooks opens Skills, and ?tab=session redirects to that agent's Workspace conversation.
When the window is too narrow to fit every tab, the trailing tabs collapse into a More ▾ menu at the end of the tab strip. Settings sits outside that menu, pinned at the end of the strip, so it is always one click away. If the active tab is inside the menu, the More button carries the active highlight. Deep links via ?tab= work either way.
Overview Tab

The Overview tab is a glanceable, database-backed summary. It renders even when the agent is stopped:
- •About — display name, tagline, and description, with a “New task” shortcut
- •Needs attention — a combined count of pending notifications, operator-queue items, and sync failures, linking to the Operations page. Hidden when the count is zero.
- •Activity trends — executions per day (stacked by trigger type), success rate, duration (avg and p95), and context consumption over a selectable 7/14/30-day window
- •Health & reliability — current health badge, reachability, restart count, plus uptime and latency trend lines. Health history covers at most the last 7 days.
- •Recent activity — the last five executions; click one to open it in the Tasks tab
- •Footprint — schedule, skill, and share counts, plus git sync status
The agent header's second and third rows show the present: for a running agent, CPU and memory against their limits (with sparklines); for a stopped one, when it was created and the CPU and memory allocated to it. Once the agent has run anything, a second line shows spend — today, a 7-day sparkline and trend, and lifetime cost and run count (API-price equivalents for a subscription-funded agent). Nothing in the strip is a control; the limits and funding are set under Settings › General.
The persistent header above the tabs holds the agent's identity (avatar, name, id, description), its running state and badges, the Autonomy chip and the Start/Stop switch. As an owner you can edit the identity right there: the pencil beside the name edits the display name in place (Enter saves, Esc cancels, leave it empty to show the id), and hovering the avatar offers Generate an avatar when there is none, or Change avatar prompt and Next emotion when there is one. The same rows live under Settings › General › Identity, which is also the only place to rename the agent's id. Among the badges, the funding badge names what pays for the agent (a subscription or the API key); as an owner, click it to switch. The second row holds the Autonomy and Read-only switches, the tags, and the live CPU and memory sparklines. Below those the header shows:
- •Repository — when the agent is bound to a GitHub repository and running, the repo (a link to GitHub), the current branch, and how many changes are waiting to be pushed or pulled. Pull and Push are on the Git tab.
- •Tags — the first two tags, with a “+N” count for the rest. Owners click the pencil (or Add tag) to add and remove tags; the same editor is in Settings › General.
- •Context — for a running agent, a small ring showing how full its context window is. It reads “—” until there is a reading.
To work with the agent in the Workspace or start a voice call, open the Workspace from the navigation bar — see Voice Chat.
API: GET /api/agents/{name}/analytics?window=7d|14d|30d
Display Label, Rename, and Resource Allocation
Display Label — The friendly name shown across the UI: the header, agent pickers, search, sort, and the activity timeline. Editing it is the everyday “rename”: it changes what people read without moving the immutable slug (name), so it never breaks URLs, MCP tool names, schedules, or webhooks. Edit it from the pencil beside the name in the agent header, or from Settings › General › Identity › Display name. Owner-only; the label is non-unique (the slug guarantees uniqueness) and clears back to the slug when left blank. There is no MCP tool for the display label — it is a UI/API-only, presentation-only change. (GET/PUT /api/agents/{name}/label with body {"label": "My Agent"}; send {"label": null} or an empty string to clear)
Rename — Moves the immutable slug itself — the heavier operation. Because the slug is what URLs, MCP tool names, schedules, and webhooks resolve to, prefer the display label above when you only need to change the friendly name. Open Settings › General › Identity › Agent id and click Rename…. The editor warns that the rename stops and restarts the agent, re-keys its URLs and MCP keys, and leaves its data volumes under the old id; Rename id confirms. (To change only the name people see, edit the Display name row above it.) Renaming is atomic: it updates the database, renames the Docker container, and broadcasts the change via WebSocket. System agents cannot be renamed; only owners and admins have permission. (PUT /api/agents/{name}/rename, MCP rename_agent(name, new_name) — the MCP tool moves the slug, not the label)
Resource Allocation — Configure per-agent memory and CPU limits under Settings › General › Execution › Memory and CPU. Limits are enforced at the container level; a change is saved at once and applied on the next restart, which the bar at the top of Settings offers. A CPU limit above the host's CPU count is capped to that count.
Execution Timeout — Configurable per agent under Settings › General › Execution › Execution timeout, in whole minutes from 1 to 120 (default 60); the API takes seconds (range: 60–7200, default: 3600). The agent's timeout is the ceiling for any of its schedules — setting it below an active schedule's timeout_seconds is rejected with 400 error=agent_timeout_below_active_schedules. (GET/PUT /api/agents/{name}/timeout)
Lifecycle States

Docker Status Mapping:
Docker "created" → "stopped"
Docker "exited" → "stopped"
Docker "dead" → "stopped"
Docker "running" → "running"
Docker "paused" → "paused"
Docker "restarting"→ "restarting"Trinity normalizes Docker's container statuses into a simpler model. An agent is either running (accepting chat and executing tasks) or stopped (container exists but is not active). All container metadata is stored in Docker labels with the trinity.* prefix.
1. Creation
POST /api/agents
Agent creation starts with an AgentConfig payload specifying the agent name, type, base image, resources, tools, and optional template or GitHub repository.

The runtime field supports claude-code (default) or gemini-cli for multi-runtime agents. A model override can be specified (e.g., sonnet-4.5, gemini-2.5-pro).
2. Configuration
Skills, credentials, MCP servers, and instructions
After creation, agents can be configured through multiple channels:
Skills— Attach skill definitions from the Skills Library. Skills are markdown documents that inject domain knowledge and behavioral patterns into the agent's context.
Credentials — Inject API keys, .env files, and .mcp.json configurations. Credentials are encrypted in Redis and injected into the container on start.
MCP Servers — Configure external MCP servers the agent can access. The .mcp.json.template file is resolved with credentials at start time.
CLAUDE.md— Edit the agent's instruction file directly through the file management API. This is the primary lever for controlling agent behavior.
Permissions — Grant other agents access for collaboration. Supports explicit grants and system-level permission presets.
Agent Config — Set autonomy mode, read-only mode, resource limits, parallel capacity, execution timeout, and full-capabilities flag.
3. Starting
POST /api/agents/{name}/start

The start process is idempotent — starting an already-running agent is a no-op. If the agent's configuration has changed since the last run (e.g., resource limits, shared folder mounts), the container is recreated with the new settings while preserving the workspace volume.
Skills delivery. A start also delivers the agent's assigned skills, and the start response says how that went. skills_injection is the overall status, and skills_result lists each skill's status plus any name conflicts, with errors reduced to a code. A start that did nothing reports skipped with a reason; a missing result reads unknown. A conflict does not fail the start, so check conflicts to tell it apart from a clean one. The MCP start_agent tool adds a line for each skill that did not land.
After a host reboot. Agent containers are created with Docker's unless-stopped restart policy, so when the host reboots or the Docker daemon restarts, every agent that was running comes back on its own — schedules resume without anyone starting agents by hand. An agent you deliberately stopped stays stopped: the policy honours Docker's manual-stop flag, so a quarantined agent is never resurrected by a reboot. While Docker is bringing agents back they may briefly show as stopped. The policy is set when the container is created; agents created before this behaviour shipped adopt it on their next recreate (a resource, runtime, or base-image change), not on a plain restart — an upgrading install can sweep its existing fleet once using the AGENT_RESTART_POLICY_2026-09.md migration note.
4. Running
Chat, task execution, and scheduled operations
A running agent accepts work through multiple entry points:

Interactive Chat— Users send messages through the web UI or MCP. Each message is queued (one active execution per agent) and proxied to the agent's internal web server where Claude Code or Gemini CLI processes it.
Parallel Tasks — Stateless task execution for agent-to-agent delegation. Supports tool restrictions, system prompt overrides, timeout controls, and async (fire-and-forget) mode.
Scheduled Tasks — The scheduler dispatches cron tasks to agents via the backend internal API. Each execution acquires a Redis distributed lock and records results in the database.
Process Executions — Multi-step workflows with approval gates, parallel branches, and retry logic orchestrated by the process engine.
All execution sources feed into the activity stream, which tracks every chat, tool call, schedule run, and collaboration event with full timing and status information.
5. Stopping
POST /api/agents/{name}/stop
Stopping an agent sends a graceful shutdown signal to the Docker container. All state is preserved on the persistent workspace volume:
- •Working files, code, and agent-created artifacts persist on the volume
- •CLAUDE.md and CLAUDE.local.md remain unchanged
- •Git repository state (branch, commits, unstaged changes) is preserved
- •Credentials in Redis remain encrypted and ready for re-injection on next start
- •Schedules remain in the database (the scheduler skips stopped agents)
An agent_stopped event is broadcast to all WebSocket clients and filtered listeners.
6. Deletion
DELETE /api/agents/{name}
Deletion is a soft delete. The container is stopped and removed at once, and the agent's schedules stop firing. Its workspace volumes, schedules, chat history, sharing records, permissions and credentials are kept until a retention sweep purges them. System agents cannot be deleted — they can only be re-initialized.
To delete an agent, open Settings › General › Danger zone and click Delete…. A confirmation dialog is required. The row appears only for agents you may delete; there is no delete button in the header.
Permission check
owner or admin only
System agent check
blocked for system agents
Stop and remove Docker container
schedules stop firing
Retain data
workspace volumes, schedules, chat history, sharing records, permissions, credentials — kept until the retention sweep
Reserve the name
the slug stays reserved until the record is purged
Broadcast agent_deleted event
WebSocket notification to all clients
Retention and recovery. The retention sweep purges a soft-deleted agent after agent_soft_delete_retention_days (default 180 days). Until then an admin can list soft-deleted agents with GET /api/admin/soft-deleted/agents and recover one with POST /api/admin/soft-deleted/agents/{name}/recover. Recovery restores the record but not the container, so start the agent afterwards. If the agent had a GitHub sync configured, the remote repository is unaffected.
Volume clean-up stays inside this installation.Each agent volume carries the installation's id, so when two Trinity stacks share one Docker daemon, neither the purge nor the sweep for orphaned agent volumes touches the other stack's volumes. The orphan sweep never reclaims a volume created before that label existed; unattached ones of those are named in a warning in the backend log for a person to review.
Activity Tracking
Throughout its lifecycle, every agent action is tracked in the activity stream. Activities have a type, state, and optional parent for hierarchical nesting:
Activity Types
chat_start / chat_endUser or MCP chat session
schedule_start / schedule_endScheduled task execution
tool_callIndividual tool invocations
agent_collaborationAgent-to-agent via MCP
execution_cancelledManual cancellation
States
startedTask is in progress
completedFinished successfully
failedEncountered an error
Sources
userHuman via UI or MCP
scheduleCron-triggered
agentAgent-to-agent via MCP