Agent

Documentation Index

Fetch the complete documentation index at: https://docs.phrony.com/llms.txt

Use this file to discover all available pages before exploring further.

​

What an agent is

An agent is the top-level entity in Phrony. It represents a configured autonomous system that can be invoked, reason about its environment, and act on the world through tools. In your workspace, that identity is a long-lived record: a named actor with a fixed execution mode and a chosen LLM provider. It does not hold the full prompt and tool setup by itself. That lives in version snapshots (often just called versions).

​

Agent fields

An agent holds one or more agent versions—each a version snapshot with a distinct, versioned configuration. You edit a Testing snapshot freely, then Deploy it so new work uses that line. The Deployed snapshot is what production-style runs target; older snapshots stay in history for comparison or rollback.

​

Execution mode

Execution mode is set on the agent (not per version) and defines, among other things, who can invoke the agent and whether human input is permitted during a run. It also changes product behavior (sessions, triggers, delegation) in broad ways, which is why it is not a per-version field. Require approval on tools: Integration and operation flags such as Require approval or Always require approval only pause a run and open an approval in the Phrony dashboard when the session root agent is in HITL mode. If the root agent is Request mode, those tools do not run and do not queue an approval—the model gets an error back instead. Use HITL on the agent when operations on the critical path must wait for a person. See Human in the loop (HITL). (L1 pause rules are separate from operation approvals: they create anomaly_review user tasks, but only when the agent is not in Request mode—see L1 rules — execution mode.) For how HITL pauses, user tasks, and triggers work together in the product, see Human in the loop (HITL). Changing mode later can strand or relax integrations with other product areas; treat it as a structural choice, not a cosmetic label.

​

Agent versions

An agent version is a versioned configuration of an agent. When an agent is updated, a new version is created. Runs are always executed against a specific agent version, ensuring reproducibility.

​

Agents list (dashboard)

​

Agent detail page (high level)

​

Triggers

A trigger is a named record on an agent that defines how new work is allowed to enter the system: which kind of entry point you use (schedule, HTTP API, or an integration event), and what limits and policies apply. Triggers do not store model instructions, tool allowlists, or input/output schemas—that lives in version snapshots on the agent. When a trigger starts a run, Phrony resolves the agent’s deployed snapshot and executes against that line (not a Testing line). Sessions and runs record which trigger and version were used for auditing. Sub-agent mode agents cannot have triggers: they are only invoked by a parent agent. The Triggers tab appears for Request and HITL agents only.

​

Types

Trigger names are unique per agent. Each trigger has a stable id (UUID) used in API key scopes and in the Access tab for API triggers. Active / inactive: Inactive scheduled triggers do not fire. For API triggers, inactivity is part of how you stop new run starts from that entry point. Event triggers are tied to a provider registration; change them carefully if you need a different integration or event type (often by removing and recreating the trigger so the product can re-register the subscription). lastFiredAt on a trigger is an operational signal for when a run was last started through that trigger.

​

API keys and trigger scope

API keys (prefix phk_…) are created in Settings in the Phrony dashboard, separate from the Secret manager used for LLM and integration credentials. Each key lists trigger scopes as (agentId, triggerId) pairs. Starting a run with POST /v1/agents/{agentId}/runs requires a key whose scope includes that agent and the API trigger you intend, so the platform can apply the right rate limits and identity. The example flow is documented under Embedded agents. For Event and API triggers, the trigger detail view includes an Ingress tab: a paginated log of recent external attempts, redacted payload inspection, and optional retries of failed starts when a full stored payload exists.

​

Version snapshots

Sub-tabs under Version Configuration are documented below. Multi-agent appears only when your workspace plan includes it.

​

Model & Prompt

Controls how the model thinks and speaks for this snapshot. Deployed snapshots: these fields are view-only until you branch or promote another Testing line.

​

Input & Output

Defines JSON Schema for the run payload the agent accepts and the structured result you want back. You can maintain schemas in a simple table (flat object: property name, JSON type, required flag, short description per field) or paste full JSON Schema for nested objects and advanced keywords. The simple editor only covers one object level; anything deeper belongs in JSON. Switching modes may require valid JSON so the product can round-trip your definition.

​

Operations

This is the tool allowlist for the snapshot: which integration operations the model is permitted to call as tools. Only checked operations are even visible to the model as callable tools—everything else is hidden, which is how you enforce least privilege. If nothing is checked, the agent can still reason but cannot call your HTTP or built-in operations until you allow them. The list is grouped by integration so you can enable whole products or fine-grained actions. Rules under Limits & Safety that depend on a specific operation only consider operations you have already allowed here.

​

Limits & Safety

Caps how much work one run may do and optionally adds governance on tool use. Anomaly control (L1) is a version-level switch: when on, you attach rules evaluated whenever the agent attempts a tool call (only for tools on this version’s Operations allowlist). Rules can allow, block, pause for human review, or terminate the session, with strict precedence when several rules match (terminate_session wins over block, then pause, then allow). Conditions can use argument patterns (for example “transfers over $10k”), per-run call counts, per-session counts (including sub-agent runs), and sliding-window frequency—the last is primarily meaningful for async / Guard-side follow-up, not the inline moment of every attempt. Pause rules require HITL or Sub-agent execution mode on the agent; Request mode may still use block, allow, or terminate_session. In multi-agent sessions, inherited rules from parent agents are merged with this version’s rules. See Guard overview and L1 rules and evaluation for incidents, principles, and rule behavior. If you enable anomaly control but add no rules, only the flag is in effect—useful when another integration reads it alone.

​

Multi-agent

Only on plans that support it. For sessions, the run tree, AITL, and runtime guidance, see the Multi-agent systems guide. Here, the version form configures whether this parent version may delegate to other agents that are themselves configured as Sub-agent mode. If your plan defines a maximum delegation depth, runs that would exceed that depth fail at dispatch so you cannot build accidental infinite recursion.

---

​

How to create, edit, and delete

Create an agent
In the dashboard, open Agents, choose Add Agent, or use Quick Create → New Agent. Set name, execution mode, and LLM provider, then create. You land on the agent page to add a first snapshot and deploy when ready. Edit or delete an agent
Use the row menu on Agents or Agent options on the detail page. Edit changes name, mode, or provider. You cannot delete an agent while any snapshot is still deployed; delete removes the agent and its Testing snapshots. Work with versions
On Version Configuration, use the version control to pick a snapshot, Create new version / Create first version when you need a new line, edit Testing fields, then Save changes to this version. Promote with Deploy (or move live back with Rollback when viewing an older line). Delete uses the trash control on Testing only. Test run
Runs the currently selected snapshot against the runtime with the JSON input you supply; if an input schema exists, the runtime validates against it. Sessions and triggers
Use Sessions to inspect runs for this agent. Triggers appears for agents that are not Sub-agent mode, because scheduling automation against a sub-agent is a different product path.

​

Notes

• The agent row answers “who” and “how runs are categorized”; versions answer “what exactly runs this week.”
• Multi-agent and sub-agent caps are plan-gated.

​

Warnings

• Pointing the agent at a different LLM provider without retesting every model id on your versions will break runs.
• Deleting agents or deployed lines affects integrations, triggers, and API clients that still reference them.