Tutorial 6: Incorporating AI Agents in Enterprise Architecture

In Tutorial 5, you modeled NeoBank's value streams and customer data lifecycles.

Modern enterprises are rapidly deploying AI agents, copilots, and autonomous pipelines into production. Architecture models must represent foundation models, human-in-the-loop oversight, autonomy ratings, and API/event telemetry.

Scapius is one of the first architecture modeling languages to treat AI Agents (agent) as first-class architectural citizens alongside traditional applications and services.

In this tutorial, you will learn how to:

1. Model conversational copilots and autonomous agents using the agent keyword.
2. Specify AI metadata: model, autonomy_level, human_in_loop, and operational risk.
3. Integrate agents with apps, event streams, and human compliance specialists.
4. Bind agents to AI Governance & Ethics policies.
5. Project an Integration Landscape View (integration).

---

1. Expanding the NeoBank Workspace Layout

We will add a dedicated AI agents definition to our application layer:

neobank/
├── main.ea
├── strategy/
│   └── goals_kpis.ea
├── business/
│   ├── actors_processes.ea
│   ├── capabilities.ea
│   └── value_streams.ea
├── application/
│   ├── customer_onboarding.ea
│   └── ai_agents.ea                      # [NEW] AI agent fleet & streaming integrations
├── technology/
│   └── environments.ea
├── security/
│   └── security_architecture.ea
└── governance/
    └── policies.ea

---

2. Define AI Agents & Integrations (application/ai_agents.ea)

Create application/ai_agents.ea. NeoBank deploys two primary agents:

1. NeoHelp Bot (agent_support_bot): A customer-facing onboarding assistant helping users complete KYC forms.
2. Fraud Investigator (agent_fraud_detective): An autonomous agent analyzing suspicious transaction sequences and escalating anomalies to human compliance officers.

neobank/application/ai_agents.ea

layer "Application Architecture" {

    group "AI Agent Fleet" {

        agent agent_support_bot "NeoHelp Onboarding Chatbot" {
            description "Conversational LLM assistant helping customers troubleshoot onboarding and verification questions"
            model "claude-3-5-sonnet"
            autonomy_level "Supervised"
            human_in_loop false
            risk "Low"
            status "Active"

            relationships {
                this serves customer "Assists applicant with signup questions"
                this realizes cap_customer_support "Provides 24/7 self-service triage"
                this triggers proc_onboarding "Initiates onboarding registration on user command"
            }
        }

        agent agent_fraud_detective "AI Fraud Investigation Detective" {
            description "Autonomous agent that ingests suspicious payment alerts, cross-references geolocation patterns, and drafts SAR filings"
            model "gpt-4o"
            autonomy_level "Supervised"
            human_in_loop true
            risk "Medium"
            status "Active"

            relationships {
                this reads data_ledger_tx "Consumes transaction event stream"
                this serves compliance_officer "Drafts suspicious activity dossiers for human signoff"
                this notifies app_aml_monitor "Reports flagged anomalies back to the AML engine"
            }
        }
    }

    actor compliance_officer "AML Compliance Officer" {
        description "Internal investigator reviewing high-risk payment escalations"
        role "Compliance Officer"
        is_external false
    }

    // Channel-to-Agent Integrations
    app_mobile_banking flows_to agent_support_bot "Support chat integration" {
        tags ["gRPC"]
        description "Routes in-app customer support queries to the AI chatbot over bidirectional gRPC"
    }

    app_aml_monitor flows_to agent_fraud_detective "Fraud alert stream" {
        tags ["Kafka", "Event-Driven"]
        description "Streams real-time suspicious transaction triggers via Kafka topic 'fraud.alerts.v1'"
    }
}

---

3. Bind Agents to AI Ethics Policy (governance/policies.ea)

Enterprise governance requires AI agents to adhere to strict guardrails. Update governance/policies.ea to add an AI Governance policy:

neobank/governance/policies.ea (excerpt)

    policy policy_ai_governance "Responsible AI & Automated Decisioning Policy" {
        description "Mandates human-in-the-loop oversight for high-impact credit, fraud, and account termination decisions"
        policy_type "AI Governance"
        enforcement "Mandatory"
        priority "Critical"

        relationships {
            this governs agent_support_bot "Restricts financial advice without human licensing"
            this governs agent_fraud_detective "Requires human sign-off before closing accounts"
        }
    }

---

4. Add the Integration Landscape View (main.ea)

In main.ea, add the integration view to project the API, gRPC, and event stream topology:

neobank/main.ea (excerpt)

    views {
        // ... previous views ...

        integration integration_view "System & Agent Integration Landscape" {
            description "API, gRPC, and Kafka event stream integration topology connecting digital channels, instant payment rails, and autonomous AI agents."
            tags ["Integration", "APIs", "Event Streams", "AI Agents"]

            include app_mobile_banking
            include app_instant_pay
            include system_core_banking
            include app_aml_monitor
            include agent_support_bot
            include agent_fraud_detective
            include compliance_officer

            exclude component

            auto_layout LeftToRight
        }
    }

---

5. Visual Projection: integration_view

System and AI Agent integration landscape showing gRPC and Kafka streaming topologies

Key Features Promoted in this View:

• Integration Topology (integration): Focuses on cross-boundary communication protocols (REST, gRPC, Kafka).
• First-Class AI Agents: Renders agent nodes with distinct styling, indicating model version, autonomy level, and human-in-the-loop guardrails.
• Component Filtering (exclude component): Keeps macro integration diagrams clear and focused by abstracting internal microservice components.

---

6. Validate the Model

Validate the workspace:

scapius validate ./neobank

Validation Successful! Workspace 'Neo Bank Enterprise Architecture' is valid.

---

Next Steps

Now that you have modeled the full estate including AI agents, proceed to Tutorial 7: Styling, Governance & Dashboards to add global themes, conditional styling rules, and an executive operations dashboard.