Building a custom agent

Specification - implementation in progress. The system_prompt and tools fields in the agent YAML are specified but not yet enforced by the runtime in sandbox environments. The standard task/skill model is fully operational.

This guide builds a reconciliation alert agent from scratch - an agent that compares two data sources, identifies discrepancies, and creates a structured exception record.

1. Define the use case

Before writing any YAML, answer three questions:

1. What triggers this agent? - A PlexiFact event when a fund’s position data is updated.
2. What does it do? - Fetches positions from two sources, compares them, and creates an exception record for any discrepancy above a threshold.
3. What does success look like? - Zero undetected position discrepancies above the threshold in daily operations.

2. Identify required skills

You need:

• A skill to fetch positions from source A (the internal system)
• A skill to fetch positions from source B (the custodian)
• A skill to compare two position sets and identify discrepancies
• A skill to create an exception record
• A skill to notify the operations team

Check the skill library first:

flexor skills list --tag "reconciliation"

If core.reconcile.compare_positions exists in the library, use it. Write a custom skill only if the library does not cover your case.

3. Write the agent YAML

name: daily-position-recon
version: "1.0"
description: "Compare internal and custodian positions. Create exception records for discrepancies above threshold."
owner: "ops-team"

trigger:
  type: event
  source: plexifact
  event: "fund.positions.updated"
  filter:
    fund_id: "{{ env.MONITORED_FUND_IDS }}"

environment: production

retry:
  max_attempts: 3
  backoff_seconds: 120
  on_final_failure: notify_ops

tasks:
  - skill: plexifact.positions.get_internal
    args:
      fund_id: "{{ event.fund_id }}"
      as_of: "{{ event.as_of_date }}"
    capture: internal_positions

  - skill: plexifact.positions.get_custodian
    args:
      fund_id: "{{ event.fund_id }}"
      as_of: "{{ event.as_of_date }}"
    capture: custodian_positions

  - skill: core.reconcile.compare_positions
    args:
      source_a: "{{ internal_positions }}"
      source_b: "{{ custodian_positions }}"
      threshold_pct: 0.01   # 1% discrepancy threshold
    capture: recon_result

  - condition: "{{ recon_result.discrepancies | length > 0 }}"

  - skill: core.exceptions.create_record
    args:
      type: "position_recon_break"
      fund_id: "{{ event.fund_id }}"
      as_of: "{{ event.as_of_date }}"
      details: "{{ recon_result.discrepancies }}"
      severity: "{{ recon_result.max_discrepancy_pct > 0.05 ? 'high' : 'medium' }}"
    capture: exception_record

  - skill: core.notify.slack
    args:
      channel: "#recon-breaks"
      message: |
        Recon break: {{ recon_result.discrepancies | length }} position(s) for {{ event.fund_id }} on {{ event.as_of_date }}.
        Exception record: {{ exception_record.id }}
        Max discrepancy: {{ (recon_result.max_discrepancy_pct * 100) | round(2) }}%

  - end_condition

  - skill: core.audit.log
    args:
      event: "position_recon_completed"
      fund_id: "{{ event.fund_id }}"
      as_of: "{{ event.as_of_date }}"
      discrepancy_count: "{{ recon_result.discrepancies | length }}"

4. Validate the configuration

flexor validate --agent daily-position-recon

Expected output:

✓ Agent definition valid
✓ All referenced skills found in library
✓ Event source plexifact reachable (sandbox)
✓ Notification channel #recon-breaks accessible

5. Deploy to sandbox and test

flexor deploy --agent daily-position-recon --env sandbox

Trigger a manual run with a test event payload:

flexor run daily-position-recon --event '{"fund_id": "TEST-001", "as_of_date": "2026-04-30"}' --env sandbox

Inspect the run log:

flexor logs --agent daily-position-recon --run last

6. Promote to production

After two weeks of clean runs in sandbox:

flexor deploy --agent daily-position-recon --env production

Update the agent YAML to environment: production and sync the vault.

Adding a system prompt (preview)

For agents that use the knowledge base to make decisions, you can add a system prompt:

system_prompt: |
  You are a fund operations reconciliation agent. When comparing positions, apply the
  SLA thresholds defined in the vault knowledge document "sla-thresholds.md".
  Always create an exception record before sending a notification.
  Never suppress a discrepancy above 1% without an exception record.

This field is not yet enforced by the runtime in all environments. Contact your PLEXI technical contact for current availability.