Skip to content

Commit 410eb67

Browse files
FannonFannon
committed
Merge with main
2 parents 1e318d2 + 8d7efa0 commit 410eb67

File tree

17 files changed

+1619
-54
lines changed

17 files changed

+1619
-54
lines changed

‎CHANGELOG.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,13 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA
1212

1313
### Added
1414

15+
- Added `Agent` as a new top-level entity type in ORD
16+
- Agents provide high-level descriptions of systems that can perform tasks, make decisions, and interact with users or other systems to achieve specific business goals. This may be an AI agent or a rule-based agent.
17+
- Agents have `exposedApiResources` to describe their API interface, e.g. using the A2A protocol.
18+
- Agents have `integrationDependencies` to describe which external resources like APIs, MCP Servers etc. they depend on.
19+
- Added example document [document-agents.json](examples/documents/document-agents.json) demonstrating agent usage with A2A protocol
20+
- Added example A2A agent card definition [DisputeResolutionAgentcard.json](examples/definitions/DisputeResolutionAgentcard.json)
21+
- Added [AI Agents and Protocols](docs/spec-v1/concepts/ai-agents-and-protocols.md) concept documentation
1522
- Introduced `abstract` property for API, Event and Data Product Resources to indicate interface-only resources.
1623

1724
### Fixed
@@ -441,4 +448,3 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA
441448
- In both cases, they share the same interface and predefined types
442449
- The internal interface name changed from `APIResourceLink` to `APIEventResourceLink`
443450
- This doesn't have any effect on the interface contract, but may need to be considered for internal refactoring / renaming.
444-

‎docs/spec-v1/concepts/ai-agents-and-protocols.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
sidebar_position: 5
3+
description: AI Agents and related protocols in ORD.
4+
title: AI Agents and Protocols
5+
---
6+
7+
# AI Agents and Protocols
8+
9+
> 🚧 Please note that the [Agents](../interfaces/Document#agent) concept is still in development.
10+
11+
## Agents
12+
13+
ORD defines a generic **Agent** resource type that can model any autonomous software entity capable of task execution. While this resource type is designed to be flexible enough to describe various types of agents, it primarily aims to model **AI Agents** - intelligent agents distinguished by their integration with Large Language Models (LLMs).
14+
15+
AI agents can interpret natural language, reason about complex scenarios, and operate in conversational mode for human interaction or be system-triggered for automated workflows. They represent the most common and significant use case for the Agent resource type in ORD.
16+
17+
## Relevant API Protocols
18+
19+
### A2A (Agent-to-Agent) Protocol
20+
21+
The [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/latest/) is an open standard that enables seamless communication and collaboration between AI agents. Originally developed by Google and donated to the Linux Foundation, A2A provides a common language for agent interoperability through standardized agent card definitions and interfaces.
22+
23+
### MCP (Model Context Protocol)
24+
25+
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open-source standard for connecting AI applications to external systems. MCP enables AI applications to connect to data sources, tools, and workflows, allowing them to access information and perform tasks beyond their core capabilities.
26+
27+
## Architecture Overview
28+
29+
### Model
30+
31+
![AI Agent Overview](/img/ord-ai-agent.drawio.svg "AI Agent Overview")
32+
33+
Agents are implemented as a dedicated ORD resource type that can model various autonomous software entities. When used for AI agents, they uniquely combine intelligent capabilities with system integration, exposing functionality through conversational interfaces while maintaining optional relationships to traditional API Resources. A key principle is the separation between agent existence as a resource and API exposure, allowing agents to be described and discovered even when they don't expose external APIs directly.
34+
35+
### Key Relationships
36+
37+
**Agent → API Resources:**
38+
- `exposedApiResources` property links to A2A protocol APIs or other agent interfaces
39+
- Optional relationship (agents can exist without external APIs)
40+
41+
**Agent → Integration Dependencies:**
42+
- `integrationDependencies` property for external system requirements
43+
- Models dependencies on LOB APIs, MCP Servers, and tools
44+
45+
**Agent → Entity Types:**
46+
- `relatedEntityTypes` for business object relationships
47+
48+
## Current Status
49+
50+
The AI Agents concept in ORD is currently in **Beta status** and may undergo refinements based on community feedback. Example implementations are available in the ORD specification repository (see `examples/documents/document-agents.json` and `examples/definitions/DisputeResolutionAgentcard.json`).

‎docs/spec-v1/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -820,6 +820,7 @@ It MUST be constructed as defined here:
820820
- Use `entityType` for `EntityType`
821821
- Use `integrationDependency` for `IntegrationDependency`
822822
- Use `dataProduct` for `DataProduct`
823+
- Use `agent` for `Agent`
823824

824825
- **`<resourceName>`** := the technical resource name.
825826
- MUST only contain ASCII letters (`a-z`, `A-Z`), digits (`0-9`) and the special characters `-`, `_` and `.`.
@@ -848,7 +849,7 @@ It MUST be constructed as defined here:
848849
An ORD ID MUST match the following [regular expression](https://en.wikipedia.org/wiki/Regular_expression):
849850

850851
```regex
851-
^([a-z0-9]+(?:[.][a-z0-9]+)*):(package|consumptionBundle|product|vendor|apiResource|eventResource|capability|entityType|integrationDependency|dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)$
852+
^([a-z0-9]+(?:[.][a-z0-9]+)*):(package|consumptionBundle|product|vendor|apiResource|eventResource|capability|entityType|integrationDependency|dataProduct|agent):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)$
852853
```
853854

854855
Examples:

‎examples/definitions/DisputeResolutionAgentcard.json‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
{
2+
"name": "FI-CA Dispute Resolution Agent",
3+
"description": "AI agent specialized in financial dispute case resolution with focus on reconciling invoiced amounts against contract terms. Automatically retrieves dispute cases, recalculates invoice amounts based on contractual terms, identifies valid discrepancies, and processes credit memos through established workflows.",
4+
"url": "https://api.sap.foo.com/fica-dispute-agent/v1",
5+
"preferredTransport": "HTTP+JSON",
6+
"additionalInterfaces": [
7+
{
8+
"url": "https://api.sap.foo.com/fica-dispute-agent/v1",
9+
"transport": "HTTP+JSON"
10+
}
11+
],
12+
"provider": {
13+
"organization": "SAP",
14+
"url": "https://www.sap.com"
15+
},
16+
"version": "1.0.5",
17+
"protocolVersion": "0.3.0",
18+
"documentationUrl": "https://help.sap.foo.com/docs/fica-dispute-agent",
19+
"capabilities": {
20+
"streaming": false,
21+
"pushNotifications": false,
22+
"stateTransitionHistory": false
23+
},
24+
"securitySchemes": {
25+
"oidc": {
26+
"type": "openIdConnect",
27+
"description": "OpenID Connect authentication for SAP systems",
28+
"openIdConnectUrl": "https://accounts.sap.foo.com/.well-known/openid_configuration"
29+
}
30+
},
31+
"security": [
32+
{
33+
"oidc": []
34+
}
35+
],
36+
"defaultInputModes": ["text/plain", "application/json"],
37+
"defaultOutputModes": ["text/plain", "application/json"],
38+
"skills": [
39+
{
40+
"id": "dispute-case-resolution",
41+
"name": "Automated Dispute Case Resolution",
42+
"description": "Processes FI-CA dispute cases of type 'A001 (Incorrect Invoice)' by retrieving case data, recalculating invoice amounts based on contract terms, identifying discrepancies, and automatically creating credit memos when valid discrepancies are found.",
43+
"tags": ["finance", "billing", "dispute-resolution", "invoicing", "credit-memo", "contract-analysis"],
44+
"examples": [
45+
"Resolve dispute case 24240",
46+
"Process the incorrect invoice dispute for case ID 12345",
47+
"Analyze and resolve dispute case with contract recalculation"
48+
],
49+
"inputModes": ["text/plain", "application/json"],
50+
"outputModes": ["text/plain", "application/json"],
51+
"security": [
52+
{
53+
"oidc": []
54+
}
55+
]
56+
},
57+
{
58+
"id": "dispute-case-verification",
59+
"name": "Dispute Case Data Verification",
60+
"description": "Retrieves and verifies dispute case information including disputed amounts, invoice line items, contract attachments, and dispute notes. Validates data completeness and currency consistency before processing.",
61+
"tags": ["verification", "data-validation", "dispute-analysis", "contract-review"],
62+
"examples": [
63+
"Verify dispute case data for case 24240",
64+
"Check if dispute case has complete information for processing",
65+
"Validate contract attachment and invoice details"
66+
],
67+
"inputModes": ["text/plain", "application/json"],
68+
"outputModes": ["text/plain", "application/json"],
69+
"security": [
70+
{
71+
"oidc": []
72+
}
73+
]
74+
},
75+
{
76+
"id": "invoice-recalculation",
77+
"name": "Contract-Based Invoice Recalculation",
78+
"description": "Recalculates invoice amounts based on contract terms including base fees, adjustment rates, and time-based adjustments. Handles complex calculations with tax inclusion/exclusion and period-based adjustments.",
79+
"tags": ["calculation", "contract-analysis", "invoice-verification", "financial-analysis"],
80+
"examples": [
81+
"Recalculate invoice amount based on contract terms",
82+
"Apply contract adjustments for the invoice due date",
83+
"Calculate correct billing amount with time-based rate adjustments"
84+
],
85+
"inputModes": ["application/json"],
86+
"outputModes": ["application/json"],
87+
"security": [
88+
{
89+
"oidc": []
90+
}
91+
]
92+
},
93+
{
94+
"id": "credit-memo-processing",
95+
"name": "Credit Memo Creation and Processing",
96+
"description": "Creates credit memos for valid dispute amounts, sets billing request status to 'ForChecking', updates dispute case status to 'Being Processed', and handles the complete credit memo lifecycle including release and dispute case closure.",
97+
"tags": ["credit-memo", "billing", "financial-processing", "workflow-automation"],
98+
"examples": [
99+
"Create credit memo for dispute amount €150.00",
100+
"Process and release credit memo for resolved dispute",
101+
"Generate credit memo and close dispute case"
102+
],
103+
"inputModes": ["application/json"],
104+
"outputModes": ["application/json"],
105+
"security": [
106+
{
107+
"oidc": []
108+
}
109+
]
110+
}
111+
],
112+
"supportsAuthenticatedExtendedCard": false
113+
}

‎examples/documents/document-agents.json‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
{
2+
"$schema": "https://open-resource-discovery.github.io/specification/spec-v1/interfaces/Document.schema.json",
3+
"openResourceDiscovery": "1.13",
4+
"description": "Example based on ORD Reference App",
5+
"policyLevels": ["sap:core:v1", "sap:ai-agent:v1"],
6+
"describedSystemVersion": {
7+
"version": "1.0.0"
8+
},
9+
"describedSystemInstance": {
10+
"baseUrl": "https://tenant1.example-sap-system.com"
11+
},
12+
"apiResources": [
13+
{
14+
"ordId": "sap.foo:apiResource:DisputeResolutionAgent:v1",
15+
"title": "Dispute Resolution Agent",
16+
"shortDescription": "This is an Agent short description...",
17+
"description": "A longer description of this Agent with **markdown** \n## headers\n etc...",
18+
"version": "1.0.3",
19+
"lastUpdate": "2022-12-19T15:47:04+00:00",
20+
"visibility": "public",
21+
"releaseStatus": "active",
22+
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
23+
"apiProtocol": "a2a",
24+
"resourceDefinitions": [
25+
{
26+
"type": "a2a-agent-card",
27+
"mediaType": "application/json",
28+
"url": "/definitions/DisputeResolutionAgentcard.json",
29+
"accessStrategies": [{ "type": "open" }]
30+
}
31+
],
32+
"partOfConsumptionBundles": [
33+
{
34+
"ordId": "sap.joule:consumptionBundle:mTLS:v1"
35+
}
36+
],
37+
"exposedEntityTypes": [
38+
{
39+
"ordId": "sap.foo:entityType:DisputeCase:v1"
40+
},
41+
{
42+
"ordId": "sap.foo:entityType:DisputeResolution:v1"
43+
},
44+
{
45+
"ordId": "sap.odm:entityType:Dispute:v1"
46+
}
47+
],
48+
"partOfGroups": ["sap.eab:process:sap.foo:DisputeResolutionProcess"],
49+
"apiResourceLinks": [
50+
{
51+
"type": "api-documentation",
52+
"url": "https://help.sap.com/some/agent-documentation"
53+
}
54+
],
55+
"extensible": {
56+
"supported": "no"
57+
}
58+
}
59+
],
60+
"agents": [
61+
{
62+
"ordId": "sap.foo:agent:disputeAgent:v1",
63+
"title": "Dispute Resolution Agent",
64+
"shortDescription": "AI agent specialized in financial dispute case resolution",
65+
"description": "A longer description of this Agent with **markdown** \n## headers\n etc...",
66+
"version": "1.0.3",
67+
"lastUpdate": "2022-12-19T15:47:04+00:00",
68+
"visibility": "public",
69+
"releaseStatus": "active",
70+
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
71+
"partOfGroups": ["sap.aicore:llmModel:sap.aicore:anthropic--claude-3.7-sonnet"],
72+
"partOfProducts": ["sap:product:S4HANA_OD:"],
73+
"responsible": "sap:ach:FIN-DR-AG",
74+
"industry": ["Financial Services"],
75+
"lineOfBusiness": ["Finance"],
76+
"countries": ["DE", "US"],
77+
"minSystemVersion": "1.0.0",
78+
"deprecationDate": "2025-12-08T15:47:04+00:00",
79+
"sunsetDate": "2027-12-08T15:47:04+00:00",
80+
"changelogEntries": [
81+
{
82+
"date": "2024-04-29",
83+
"description": "## Changelog\n\nInitial release of the Dispute Resolution Agent with core capabilities.",
84+
"releaseStatus": "active",
85+
"version": "1.0.3",
86+
"url": "https://www.sap.com/foo/bar"
87+
}
88+
],
89+
"relatedEntityTypes": [
90+
"sap.foo:entityType:DisputeCase:v1",
91+
"sap.foo:entityType:DisputeResolution:v1",
92+
"sap.odm:entityType:Dispute:v1"
93+
],
94+
"exposedApiResources": [{"ordId": "sap.foo:apiResource:DisputeResolutionAgent:v1"}],
95+
"integrationDependencies": ["sap.foo:integrationDependency:DisputeCaseManagement:v1"],
96+
"labels": {
97+
"llmModels": ["gpt-4", "claude-3.7-sonnet"],
98+
"interactionMode": ["conversational", "system-triggered"]
99+
},
100+
"tags": ["finance", "billing", "dispute-resolution", "invoicing", "ai-agent"],
101+
"links": [
102+
{
103+
"title": "Agent Documentation",
104+
"url": "https://help.sap.com/some/agent-documentation",
105+
"description": "Comprehensive documentation for the Dispute Resolution Agent"
106+
}
107+
]
108+
}
109+
],
110+
"integrationDependencies": [
111+
{
112+
"ordId": "sap.foo:integrationDependency:DisputeCaseManagement:v1",
113+
"title": "Dispute Case Management Integration",
114+
"shortDescription": "Integration dependency for dispute case management system",
115+
"description": "This integration dependency is required to access external dispute case management capabilities.",
116+
"version": "1.0.0",
117+
"releaseStatus": "active",
118+
"visibility": "public",
119+
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
120+
"mandatory": true,
121+
"aspects": [
122+
{
123+
"title": "Case Management API Access",
124+
"description": "Access to dispute case management APIs",
125+
"mandatory": true,
126+
"apiResources": [
127+
{
128+
"ordId": "sap.bar:apiResource:DisputeResolutionAPI:v1"
129+
}
130+
]
131+
}
132+
]
133+
}
134+
],
135+
"packages": [
136+
{
137+
"ordId": "sap.foo:package:ord-reference-app:v1",
138+
"title": "ORD Reference Application Package",
139+
"shortDescription": "Package containing reference application resources",
140+
"description": "This package contains all resources related to the ORD reference application including agents and APIs.",
141+
"version": "1.0.0",
142+
"vendor": "sap:vendor:SAP:"
143+
}
144+
]
145+
}

0 commit comments

Comments
 (0)