status: active
last_resolved_at: 2026-01-01T00:00:00Z
verification_method_count: 1
agent_card:
  url: https://example/agent-card

disabled: true
status: disabled
_followup_note: Spec-status persistence is a follow-up; revoke trust grants via circle.revoke_peer_trust to fully block traffic.
element_id: 00000000-0000-0000-0000-000000000000

External Agent (external-agent)

Category: agents | Form: | Symbol: Ea

Represents a non-Triform A2A peer (Claude Code, MCP server, OpenAI Assistant — anything that speaks A2A Protocol v1.0)

Configure spec.peer_did (did:web, did:tfid, or did:key — the counterparty AGENT’s DID per Phase 5 D7), spec.agent_card_url (where this peer publishes its A2A AgentCard), and spec.accepted_scopes (subset of the v0 vocabulary). Adding an agents/external-agent element triggers DID resolution + AgentCard fetch + initial trust seeding via peer_trusts. Federation policy on the parent circle (circle.spec.federation) decides whether the first inbound envelope auto-accepts, queues for owner approval, or requires explicit consent.

Guide

Represents a non-Triform A2A peer (Claude Code, MCP server, OpenAI Assistant — anything that speaks A2A Protocol v1.0)

What It Does

An external-agent element records a single remote A2A peer-agent so a Triform circle can federate with it. Each element represents exactly one counterparty agent, addressed by its DID (did:web, did:tfid, or did:key). It is configuration, not a process — there is no local runtime to invoke; the activity type is peer, delivery is synchronous, retries are disabled, and streaming is not supported.

Adding the element triggers DID resolution via the WS-6 resolver chain plus an AgentCard fetch from the peer’s published endpoint, seeding initial trust. Triform’s verifier uses the JWKS from the resolved DID document to verify the signatures on inbound envelopes from this peer. The peer’s accepted scopes are drawn from a fixed v0 OAuth-shape vocabulary, and a per-peer rate limit plus payload-size cap guard the pod against oversized or abusive external traffic.

First contact follows the D-F hybrid first-message UX: scopes listed in auto_accept_scopes are admitted silently and audited, while scopes in pending_queue_scopes generate pending requests the circle owner must approve before delivery. Federation policy on the parent circle (circle.spec.federation) decides whether the first inbound envelope auto-accepts, queues, or requires explicit consent. The element is collaborator-visibility only — exposing it to a wider audience would reveal the circle’s federation topology and A2A trust graph.

Element Definition

Property	Value
Type	external-agent
Category	agents
Form	data
Symbol	Ea / #6366F1
Activity type	peer
Delivery mode	sync
Handler	ExternalAgentHandler

Properties

Field	Type	Default	Description
peer_did	string	—	Agent-level DID identifying the remote A2A peer. Methods: did:web, did:tfid, did:key (pattern ^did:(web|tfid|key):.+).
issuer_did	string	—	DEPRECATED — back-compat alias for peer_did, kept one release.
agent_card_url	string (uri)	—	URL where the peer publishes its A2A AgentCard. Optional; when omitted it is derived from a did:web authority.
accepted_scopes	array	[publish:direct-message, read:profile]	Scopes the peer may use on inbound envelopes (enum below).
auto_accept_scopes	array	[read:profile]	Scopes admitted on first message without owner approval.
pending_queue_scopes	array	[publish:direct-message, publish:broadcast]	Scopes that must be owner-approved before delivery.
rate_limit	object	rate: 60/min, burst: 120	Per-peer rate limit overriding the global external default.
payload_size_cap_bytes	integer	1048576	Max bytes per inbound message (min 1024, max 16777216).
last_resolved_at	string (date-time)	—	Read-only: last successful DID resolution + AgentCard fetch.
last_error	string	—	Read-only: most recent resolution / fetch error (truncated).
status	string	pending_resolution	Read-only lifecycle state: pending_resolution, active, error, disabled.

accepted_scopes vocabulary: publish:direct-message, publish:broadcast, subscribe:inbox, read:profile, request:reply, dlq:read.

Capabilities

external.resolve · external.refresh · external.disable · external.list_pending

Accepts Modifiers

rate-limit (A2A identity is an intrinsic agent property block, not a separately-attached modifier).

Error Codes

Code	Meaning
DID_PARSE_FAILED	The DID could not be parsed.
DID_RESOLVE_FAILED	DID resolution via the WS-6 chain failed.
AGENT_CARD_FETCH_FAILED	The AgentCard could not be fetched.
AGENT_CARD_INVALID	The fetched AgentCard was malformed.
SIGNATURE_VERIFY_FAILED	Inbound envelope / AgentCard JWS signature verification failed.
PEER_DISABLED	The peer is disabled; inbound traffic is rejected.

Operations

refresh

POST refresh — auth: owner

Re-resolves the peer DID via the WS-6 resolver chain and refetches the AgentCard, updating last_resolved_at and verifying the signed AgentCard JWS if the peer publishes one. On success transitions to status=active; on failure sets status=error and last_error. Idempotent — called at element-create time, on schedule for active peers, and on demand. Returns status, last_resolved_at, agent_card, and verification_method_count.

disable

POST disable — auth: owner

Marks the peer disabled; all subsequent inbound envelopes from its DID are rejected even if they hold otherwise-valid trust grants. The element and grants are preserved for audit. Requires confirm: true; accepts an optional reason for the audit trail. Returns disabled and status: disabled.

pending_requests

GET pending — auth: read

Lists inbound requests awaiting owner approval. Scopes in pending_queue_scopes generate pending requests on first sight; auto-accept scopes never appear here. Returns a pending array of { ts, scope, payload_sha256, jti } plus a total count. The owner approves a scope going forward via approve_peer_trust on the circle element, or denies it via revoke_peer_trust.

Quick Start

Create via API

POST /api/{circle}/
Content-Type: application/json

{
  "element_type": "external-agent",
  "slug": "acme-scheduler",
  "name": "Acme Scheduler",
  "spec": {
    "peer_did": "did:web:acme.com:api:scheduler-circle:scheduler",
    "accepted_scopes": ["publish:direct-message", "read:profile"]
  }
}

Resolve the DID and fetch the AgentCard

POST /api/{circle}/acme-scheduler/ops/refresh

List requests pending owner approval

GET /api/{circle}/acme-scheduler/ops/pending

Common Mistakes

Omitting the peer DID. issuer_did is required by validation and must start with did:web, did:tfid, or did:key. New specs should populate peer_did (the bridge falls back to issuer_did).

Using an HTTP AgentCard URL. agent_card_url must use HTTPS when explicitly set — HTTP is rejected for external A2A.

Granting publish:broadcast to an external peer. Flagged as high-risk; review the trust grants regularly.

Setting a 0/min rate limit to block a peer. Zero rate blocks all inbound traffic but is unclear — use the disable operation instead.

Setting payload_size_cap_bytes out of range. Must be between 1024 (1 KiB) and 16777216 (16 MiB); larger values open the pod to oversized-payload abuse.

Relationships

• Attaches to: rate-limit

Properties

Property	Type	Default	Description
peer_did	string	—	Agent-level DID identifying the remote A2A peer (per Phase 5 D7 — each external-agent element = one peer-agent, not a peer-circle). Supported methods: did:web (HTTPS), did:tfid (alchemy chain), did:key (self-contained).
issuer_did	string	—	DEPRECATED Phase 5 WS-2: use peer_did instead. Kept for one release as a back-compat alias so existing specs continue to validate. The bridge falls back to issuer_did when peer_did is not set; new code should write peer_did.
agent_card_url	string	—	URL where this peer publishes its A2A AgentCard. Optional — when omitted, derived from the DID (did:web → /well-known/agent-card.json on the same authority). Explicit URL needed for did:tfid / did:key peers that publish AgentCards on a separate URL.
accepted_scopes	array	["publish:direct-message","read:profile"]	Scopes this peer is allowed to use on inbound envelopes. Subset of the v0 OAuth-shape vocabulary. Owner can narrow per-grant via the consent-flow ops on the circle element.
auto_accept_scopes	array	["read:profile"]	Scopes the peer’s first message is allowed to use without circle owner approval. D-F hybrid policy: low-risk read scopes auto-accept (informational lookups, monitoring), high-risk write scopes are queued.
pending_queue_scopes	array	["publish:direct-message","publish:broadcast"]	Scopes that must be approved by the circle owner before delivery. Pending requests show up in the trust-list dashboard.
rate_limit	object	—	Per-peer rate limit (overrides the global external default)
payload_size_cap_bytes	integer	1048576	Maximum bytes per inbound message. Default 1 MiB matches the brief’s external-traffic guard. Larger values open the pod to oversized-payload abuse.
last_resolved_at	string	—	Last successful DID resolution + AgentCard fetch
last_error	string	—	Most recent resolution / AgentCard fetch error (truncated)
status	string	"pending_resolution"	Lifecycle state. Transitions: pending_resolution → active on first successful DID + AgentCard resolution. error if either fails (set last_error and exponential-backoff retry). disabled when owner revokes all scope grants — element preserved for audit but no traffic is admitted.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Read

Attach this actor to a target element

Call this ON the modifier/resource element, passing target_id of the actor. The target’s contract.yaml must declare the modifier kind in attaches: or uses:. Priority controls evaluation order for modifiers (lower = first).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this actor from a target element

disable

Post /ops/disable | Auth: Owner

Disable inbound traffic from this peer (preserves audit)

Marks the peer as disabled. All subsequent inbound envelopes from spec.issuer_did are rejected even if they hold otherwise-valid trust grants. Element + grants are preserved for audit; use revoke_peer_trust on the circle element to prune the underlying grants if needed.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached | Auth: Read

Get elements that are attached to this actor

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Invoke the actor with input

Always include data:{} even for no-input actors. Use ?stream=true for streaming output (agents support this). Use ?async=true to get a run_id immediately and poll via run_get. Input must match the actor’s port schema (check via schema operation). Creates a run record in execution history.

list_attachments

Get /ops/targets | Auth: Read

List all elements this agent is attached to

Returns all target elements where this agent is currently attached. Shows target_id, target_type, priority, and cascade_policy.

logs

Get /ops/logs | Auth: Read

Get execution logs

pending_requests

Get /ops/pending | Auth: Read

List inbound requests from this peer awaiting owner approval

D-F hybrid first-message UX: scopes in pending_queue_scopes generate pending requests on first sight. This op returns the list (timestamp, scope, payload_sha256). Owner approves via approve_peer_trust on the circle (admits the scope going forward) or revoke_peer_trust (denies + records the denial). Auto-accept scopes never appear here — they’re admitted silently and recorded in the cross_circle_message_audit.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

refresh

Post /ops/refresh | Auth: Owner

Resolve the peer DID and fetch their AgentCard

Re-resolves spec.issuer_did via the WS-6 DID resolver chain and refetches the AgentCard. Updates last_resolved_at + verifies the signed AgentCard JWS if the peer publishes one. On success transitions to status=active; on failure status=error + last_error captures the reason. Idempotent — called at element-create time, on schedule for active peers, and on demand.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

run_cancel

Post /ops/runs/{run_id}/cancel | Auth: Execute

Cancel a running execution

Only works on runs with status pending or running. Already-completed or failed runs cannot be cancelled. The run transitions to cancelled state and triggers run.cancelled event.

run_get

Get /ops/runs/{run_id} | Auth: Read

Get details of a specific run

runs

Get /ops/runs | Auth: Read

List execution runs

Filter with ?status=completed|failed|running, paginate with ?limit=N&offset=N. Default limit is 50. Returns total count for pagination.

schema

Get /ops/schema | Auth: Read

Get input/output port schemas (MCP tools/list compatible)

Call this before invoking an actor to discover its expected input/output format. Returns MCP-compatible tool definitions — useful for building dynamic tool UIs or A2A integration.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.