AI Agents

Overview#

Artifi includes a suite of autonomous AI agents that handle repetitive financial tasks without manual intervention. Agents are event-driven processors that respond to triggers like incoming emails, scheduled jobs, or other agent requests. They run independently, communicate via structured requests, and produce a full audit trail.

Core Capabilities#

• View and configure agent definitions
• Monitor running agent instances in real time
• Manage the event queue (trigger, retry, ignore failed events)
• Handle inter-agent communication and requests
• Manage agent API keys and scheduled jobs
• Orchestrate multi-step processes with sagas
• Configure downstream event routing rules
• Store and recall persistent agent memory

---

Built-in Agents#

Artifi ships with 10 purpose-built agents covering the most common financial automation needs:

Execution Modes#

• Hybrid: Combines code execution with LLM reasoning. Used for complex tasks like bill extraction, classification, and fuzzy matching.
• Fast: Code-only execution. Used for deterministic tasks like master data lookups and configuration changes.

---

Agent Definitions#

Agent definitions describe what an agent does, how it is triggered, and what tools and workflows it can access.

Configuration Properties#

Common Operations#

• List all agents to see their status and configuration
• Enable or disable an agent to control whether it processes events
• Update configuration such as confidence thresholds
• Regenerate API keys for agent authentication
• Deploy from templates for quick agent setup

---

Agent Instances#

Agent instances represent individual runs. Each time an agent processes an event, a new instance is created with its own logs, status, and execution history.

Instance Lifecycle#

Instances transition through states: starting, running, completed, or failed. You can:

• View all running agents with a summary dashboard
• List recent runs filtered by agent type or status
• Get detailed instance information including execution logs
• Manually trigger a new agent run
• Cancel a stuck or misbehaving instance

Concurrency Control#

Each agent has a max_concurrent_runs limit. For example, the reconciliation agent is limited to 1 concurrent run to prevent double-matching of transactions.

---

Event Processing#

Events are triggers that start agent runs. They flow through a queue and are processed in order, providing reliable delivery with retry support and a full audit trail.

Event Types#

Event Lifecycle#

pending → processing → completed
                    → failed → (retry) → pending
                             → (ignore) → ignored

Failed events can be retried after fixing the underlying issue, or ignored if they are duplicates or no longer relevant.

---

Inter-Agent Communication#

Agents communicate via structured requests. One agent creates a request, another processes it, and the result is returned via callback. This enables loose coupling between agents while maintaining a full audit trail.

Request Flow Example#

Bill Processor                      Master Data Agent
     │                                    │
     │── Creates request: ───────────────>│
     │   "Create vendor Acme Corp"        │
     │                                    │── Searches for duplicates
     │                                    │── Creates vendor via workflow
     │<── Returns response: ─────────────│
     │   vendor_id: 42                    │
     │                                    │
     │── Continues posting bill           │

This pattern allows agents to delegate specialized tasks (like vendor creation with duplicate checking) to the agent best suited for that work.

---

Scheduled Jobs#

Configure recurring agent runs using cron expressions. Common use cases:

• Daily reconciliation at 6 AM: Automatically match bank transactions to invoices
• Weekly payment proposals on Fridays at 10 AM: Generate payment batches for review
• Monthly reports: Trigger financial close activities

Jobs can be enabled, disabled, or manually triggered at any time.

---

Saga Orchestration#

Sagas coordinate multi-step workflows that span multiple agents. Each saga has phases that execute in sequence, with automatic advancement and failure handling.

Example: Processing an Incoming Bill#

Phase 1: Bill processor extracts data from the email attachment
Phase 2: Master data agent creates the vendor (if new)
Phase 3: Configuration agent creates a posting profile (if needed)
Phase 4: Bill processor posts the transaction

If any phase fails, the saga can be investigated, fixed, and resumed -- or cancelled with a reason.

---

Downstream Event Rules#

Downstream rules automatically create events when specific triggers fire, enabling event chaining between agents. For example:

• When a bill is posted, automatically trigger reconciliation
• When a bank statement is imported, trigger transaction processing
• When a vendor is created, trigger master data enrichment

Rules can be enabled, disabled, or configured with conditions to filter which events trigger downstream processing.

---

Agent Memory#

Agents can store and recall persistent key-value mappings that survive across runs. This allows agents to learn from previous processing and improve over time.

Use Cases#

• Vendor name mappings: "Amazon Web Services" maps to vendor #42
• Account classification rules: "SaaS subscription" maps to account 6200
• Customer reference numbers: "PO-12345" maps to customer #15

Memory entries can be stored, searched, and deleted as needed.

---

Entity Email Routing#

Configure email addresses associated with legal entities for agent email routing. The bill processor, for example, monitors AP inbox addresses and automatically processes incoming vendor invoices.

• Associate email addresses with specific legal entities
• Configure email types (AP inbox, AR inbox, general)
• Look up which entity an incoming email should route to
• Verify email addresses for delivery confirmation

---

Context Helpers#

Pre-built tools load everything an agent needs in a single call, reducing round-trips and improving performance:

• Bill context: Loads legal entity details, workflow schemas, vendors, accounts, tax codes, payment terms, dimensions, and posting profiles -- everything needed to process a vendor bill.
• Financial context: Loads trial balance, income statement, balance sheet, AR/AP aging, recent transactions, bank balances, and budget vs. actual -- a complete financial snapshot for analysis.

---

Common Scenarios#

1. Deploy a New Agent#

1. List available agent templates
2. Seed the agent definition from a template
3. Configure behavior settings (confidence thresholds, etc.)
4. Enable the agent
5. Create an API key for authentication

2. Monitor Agent Health#

1. Check the running summary for all active agents
2. Review event queue statistics for backlogs
3. List any failed events or instances
4. Retry or investigate failures as needed

3. Debug a Failed Agent Run#

1. Get the failed instance details and execution logs
2. Check the triggering event for context
3. Review any pending inter-agent requests
4. Fix the underlying issue and retry the event

4. Set Up Automated Scheduling#

1. Create a scheduled job with a cron expression
2. Link it to the appropriate agent type
3. Verify the schedule by listing all jobs
4. Manually trigger a test run to confirm it works

5. Configure Event Chaining#

1. Create a downstream rule linking a source event to a target agent
2. Add conditions to filter which events trigger the chain
3. Verify the rule by listing all active rules
4. Monitor the event queue to confirm chaining works