ai-agent-proposal

[ElyasRashno]

This issue is for the AIAgent class under the AI profile. This version is a combination of the previous issue and community discussions.
#1257

[ElyasRashno]

@gongli0929, this issue is for discussing newly proposed fields for AI Agent class in AI profile, which we have been continuously reviewing in the AI and Dataset Profile Working Group. I will link the correspond PR to this issue.

[ElyasRashno]

SPDX-License-Identifier: Community-Spec-1.0

add-ai-agent-v2 Branch

New Class: AI/AIAgent

Subclass of: /Core/SoftwareAgent

Represents an AI agent, a software entity that uses artificial intelligence techniques to perceive its environment, reason about its state, and take actions to achieve specified goals. It typically implements a perception-action cycle employing AI models, heuristics, or planning algorithms to guide autonomous or semi-autonomous behavior.

AI agents may be characterized by the modalities through which they perceive input and produce output, the capabilities they provide, the external tools or services they invoke, the memory mechanisms they employ to retain information across interactions, and their degree of automation relative to human oversight.

Properties on AIAgent

Field Name	Type	Required/Optional	Description
/Core/isoAutomationLevel	/Core/IsoAutomationLevel	Optional (0..1)	ISO level of automation relative to human oversight
agentCapability	/Core/DictionaryEntry	Optional (0..*)	Describes a specific domain task or goal the agent is designed to perform
agentExternalTool	/Core/DictionaryEntry	Optional (0..*)	Identifies an external tool or service that the AI agent can invoke to extend its capabilities
agentMemoryMode	AgentMemoryMode	Optional (0..*)	Indicates the memory category or storage mechanism used by the AI agent
agentCommunicationProtocol	/Core/DictionaryEntry	Optional (0..*)	Identifies a standardized communication protocol implemented by the AI agent for interacting with external tools, data sources, or other agents
agentTrustLevel	AgentTrustLevel	Optional (0..1)	Indicates the degree of external verification applied to the AI agent's identity, behavioral claims, and declared capabilities
agentType	AgentType	Optional (0..*)	Classifies the communication and interaction role of the AI agent within a multi-agent system or agentic workflow
agentPermissionScope	xsd:string	Optional (0..*)	Captures the permissions granted to the AI agent and their delegation source
limitation	xsd:string	Optional (0..1)	Limitation of the AI software
/Software/inputModality	/Core/Modality	Optional (0..*)	Fundamental data or sensory type accepted as input by a software artifact or agent
/Software/outputModality	/Core/Modality	Optional (0..*)	Fundamental data or sensory type produced as output by a software artifact or agent
safetyRiskAssessment	SafetyRiskAssessmentType	Optional (0..1)	Results of general safety risk assessment of the AI system

Relationship types used with AIAgent

Relationship	Direction	Description
hasPersistentMemory	AIAgent → Element	The AIAgent uses the target Element as a persistent or long-term memory store (e.g., a database, vector store, or file system that retains information across sessions or reasoning steps)
invokedBy	Element → Agent	The Element was invoked by the target Agent (e.g., a Package is invokedBy an AIAgent; an AIAgent is invokedBy a Person)
usesTool	AIAgent → Element	The AIAgent uses the target Element as a tool to extend its capabilities
usesModel	AIAgent → /AI/AIPackage	The AIAgent uses the target AIPackage as its underlying AI model, enabling BOM consumers to trace from an agent to its associated model weights, training data, and safety assessments

---

Properties

/Core/isoAutomationLevel

• Nature: ObjectProperty
• Range: /Core/IsoAutomationLevel
• Cardinality: 0..1

Summary: ISO level of automation.

The level of automation describes a spectrum of system capability, defining
the degree of control and decision-making authority a system possesses
relative to an external control.

This classification helps to define the roles and responsibilities of both the
human operator and the automated system. It is a critical component for risk
assessment, regulatory compliance, and user interface design.

---

agentCapability

• Nature: ObjectProperty
• Range: /Core/DictionaryEntry
• Cardinality: 0..*

Summary: Describes a specific domain task or goal the agent is designed to perform.

A free-form string that identifies a user-facing task ability of the AI agent:
what it can accomplish for a system.

Examples:

web-search: search across web and retrieve information

document-summarization: condenses retrieved documents into structured outputs

code-execution: runs Python snippets in a sandboxed environment

multi-step-reasoning: decomposes complex queries into sub-tasks and plans execution order

multi-agent-coordination: delegates sub-tasks to specialized agents and aggregates results

---

agentExternalTool

• Nature: ObjectProperty
• Range: /Core/DictionaryEntry
• Cardinality: 0..*

Summary: Identifies an external tool or service that the AI agent can invoke to extend its capabilities.

Identifies an external tool, API, or service that the AI agent can invoke to
perform actions beyond its built-in model. Each entry maps a short,
human-readable tool identifier (the key) to a URI, package URL, or other
reference that locates the tool's definition or specification (the value).

Examples:

web-search: https://serpapi.com/

code-interpreter: pkg:pypi/jupyter-kernel-gateway@2.0.0

pubmed-query: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

---

agentMemoryMode

• Nature: ObjectProperty
• Range: AgentMemoryMode
• Cardinality: 0..*

Summary: Indicates the memory category or storage mechanism used by the AI agent.

Classifies how an AI agent retains and recalls information across interactions
or reasoning steps. Multiple values may be declared when an agent employs more
than one memory mechanism.

Values: see AI/AgentMemoryMode vocabulary.

---

agentCommunicationProtocol

• Nature: ObjectProperty
• Range: /Core/DictionaryEntry
• Cardinality: 0..*

Summary: Identifies a standardized communication protocol implemented by the AI agent for interacting with external tools, data sources, or other agents.

Specifies the standardized communication protocol(s) that the AI agent
implements, enabling consumers, integrators, and automated tooling to determine
how the agent can be invoked, composed, or connected within a larger system.

Each agentCommunicationProtocol entry is a DictionaryEntry where the key is
a human-readable protocol identifier and the value is the protocol version or a
URI pointing to the protocol specification.

Examples:

Model Context Protocol (MCP): 1.2

Agent2Agent (A2A): https://github.com/google/A2A

Agent Network Protocol (ANP): https://www.agent-network-protocol.com/

Agent Connect Protocol (AConP): https://spec.acp.agntcy.org/

---

agentTrustLevel

• Nature: ObjectProperty
• Range: AgentTrustLevel
• Cardinality: 0..1

Summary: Indicates the degree of external verification applied to the AI agent's identity, behavioral claims, and declared capabilities.

Specifies the trust level assigned to an AI agent, reflecting how rigorously
its identity and behavior have been verified by external parties. Trust level
informs consumers, orchestrators, and access-control systems about the
confidence they can place in the agent's declared properties and the scope of
resources or operations the agent may be permitted to access.

The four levels progress from unverified (no assessment performed) through
selfDeclared (developer or operator claims only) and thirdPartyReviewed
(independent audit) to certified (formal certification by a recognized
standards body).

An agent declares at most one trust level. When no value is present, consumers
should treat the agent as unverified.

Values: see AI/AgentTrustLevel vocabulary.

---

agentType

• Nature: ObjectProperty
• Range: AgentType
• Cardinality: 0..*

Summary: Classifies the communication and interaction role of the AI agent within a multi-agent system or agentic workflow.

A controlled classification that describes the structural role an AI agent
assumes in terms of how it communicates and interacts with other agents and
orchestration systems.

An agent may declare multiple values when it simultaneously holds more than one
role (e.g., a worker toward an upstream orchestrator that itself orchestrates
a sub-group of specialist agents).

Values: see AI/AgentType vocabulary.

---

agentPermissionScope

• Nature: DataProperty
• Range: xsd:string
• Cardinality: 0..*

Summary: Captures the permissions granted to the AI agent and their delegation source.

A free-form string that identifies a permission granted to the agents in the system.

Examples:

read:files

execute:code-interpreter

write:external-api delegated-by:orchestrator

---

limitation

• Nature: DataProperty
• Range: xsd:string
• Cardinality: 0..1

Summary: Limitation of the AI software.

A free-form text that captures a limitation of the AI package
(or of the AI models present in the AI package).

Note that this is not guaranteed to be exhaustive.

For instance, a limitation can be that the AI package is having poor accuracy
for a certain demography.

Examples:

Poor accuracy for non-English languages

Context window limited to 128k tokens; long documents may be truncated

---

/Software/inputModality

• Nature: ObjectProperty
• Range: /Core/Modality
• Cardinality: 0..*

Summary: Fundamental data or sensory type accepted as input by a software artifact or agent.

Specifies the fundamental type of data that a software artifact or agent accepts
and processes as input. This includes the sensory or representational form of
data, such as natural language text, images, audio, or structured records.

Multiple inputModality values may be declared when a software artifact or
agent processes more than one type of input.

---

/Software/outputModality

• Nature: ObjectProperty
• Range: /Core/Modality
• Cardinality: 0..*

Summary: Fundamental data or sensory type produced as output by a software artifact or agent.

Specifies the fundamental type of data that a software artifact or agent
produces or emits as output. This includes the sensory or representational form
of data, such as natural language text, images, audio, or structured records.

Multiple outputModality values may be declared when a software artifact or
agent produces more than one type of output.

---

safetyRiskAssessment

• Nature: ObjectProperty
• Range: SafetyRiskAssessmentType
• Cardinality: 0..1

Summary: Results of general safety risk assessment of the AI system.

Results of general safety risk assessment of the AI system.

Using categorization according to the
EU general risk assessment methodology.
The methodology implements Article 20 of Regulation (EC) No 765/2008 and is
intended to assist authorities when they assess general product safety
compliance.

It is important to note that this categorization differs from the one proposed
in the EU AI Act's provisional agreement.

Values: see AI/SafetyRiskAssessmentType vocabulary.

---

New Vocabulary: AI/AgentType

Summary: Classifies the communication and interaction role of an AI agent within a multi-agent system or agentic workflow.

AgentType is an enumeration that categorizes the structural role an AI agent
assumes in terms of how it communicates and interacts with other agents and
orchestration systems.

Entry	Description
orchestrator	The agent initiates and decomposes high-level goals into sub-tasks, delegates those sub-tasks to other agents, and aggregates their results into a final outcome
worker	The agent receives a delegated task from an orchestrator or controller, executes it using its own capabilities and tools, and returns the result
peer	The agent participates in symmetric, decentralized multi-agent collaboration without a fixed coordinator or worker hierarchy

---

New Vocabulary: AI/AgentTrustLevel

Summary: How much the agent's identity and behavior have been independently verified.

Indicates how rigorously an AI agent has been checked by external parties.
The four levels progress from no verification at all to formal certification,
and can be used by orchestrators or access-control systems to decide what the
agent is allowed to do.

Entry	Description
unverified	No review has been performed. The agent's identity, capabilities, and behavior are entirely unconfirmed. Treat with maximum caution and restrict access accordingly
selfDeclared	The agent's developer or operator has described its behavior, but no one else has checked those claims. Suitable for internal or sandboxed use where the declaring party is trusted
thirdPartyReviewed	An independent party has audited the agent, but it has not been formally certified. Offers more confidence than self-declaration; suitable for controlled production use
certified	A recognized standards or certification body has formally verified the agent against defined criteria. Appropriate for high-stakes or regulated deployments

---

New Vocabulary: AI/AgentMemoryMode

Summary: The type of memory store or storage mechanism used by the AI agent.

Classifies how an AI agent retains and recalls information across interactions
or reasoning steps. Multiple values may be declared when an agent employs more
than one memory mechanism.

Entry	Description
episodic	Records of past events, interactions, or task executions that provide experiential context for future reasoning
semantic	Factual or conceptual knowledge stored for retrieval and inference (e.g., vector embeddings, knowledge graphs)
procedural	Encoded skills, plans, or behavioral patterns that guide the agent's execution strategy
working	Short-lived, context-scoped information used within a single reasoning session or conversation turn
inContext	Information retained within the active context window of the underlying language model
inWeights	Knowledge encoded in model parameters through pretraining or fine-tuning; not updated at runtime
inCache	Precomputed key-value attention caches enabling efficient reuse of prior computations
external	Information persisted in an external store (database, file system, vector store) and retrieved on demand

---

New Vocabulary: AI/SafetyRiskAssessmentType

Summary: Safety risk level.

Lists the different general safety risk levels that can be used to describe the
general safety risk of an AI system.

Using categorization according to the
EU general risk assessment methodology.
The methodology implements Article 20 of Regulation (EC) No 765/2008 and is
intended to assist authorities when they assess general product safety
compliance.

Entry	Description
serious	The highest level of risk posed by an AI system
high	The second-highest level of risk posed by an AI system
medium	The third-highest level of risk posed by an AI system
low	Low/no risk is posed by an AI system

---

New Vocabulary: Core/Modality

Summary: Fundamental data or sensory type of content accepted or produced by software artifacts and agents.

A controlled vocabulary classifying the fundamental data or sensory type of
content accepted or produced by software artifacts and agents.

Entry	Description
text	Natural language text, structured text, or source code
image	Raster or vector image data (e.g., photographs, diagrams, screenshots)
audio	Sound recordings, speech, or music
video	Temporally sequenced visual data, with or without associated audio
tabular	Structured data organized in rows and columns (e.g., CSV, relational tables)
timeSeries	Sequences of values indexed by time (e.g., sensor readings, financial data)
graph	Data represented as nodes and edges (e.g., knowledge graphs, molecular structures)
pointCloud	Three-dimensional spatial data represented as sets of points (e.g., LiDAR, 3D scans)
multimodal	Combinations of two or more distinct modalities processed jointly
other	A modality not covered by the categories above

---

Changes to Existing Vocabularies

Core/RelationshipType

Added entries:

Entry	Description
hasPersistentMemory	The from Element uses each to Element as a persistent or long-term memory store (e.g., a database, vector store, or file system that retains information across sessions or reasoning steps)
usesModel	The from Element (typically an AIAgent) uses each to /AI/AIPackage as its underlying AI model, enabling BOM consumers to trace from an agent to its associated model weights, training data, and safety assessments

[bennetkl]

This is great, thanks Elyas for getting this defined.

A couple of suggestions to consider

1. AIAgent is not just software; it is software plus one or more AI models. The current proposal only provides usesTool, which might be too generic.You might want to consider a relationship such as usesModel which pointing to /AI/AIPackage, so that BOM consumers can trace from an agent to its underlying weights, training data, and safety assessments without guessing which usesTool entry is the model. This will be a common task that BOM consumers will want to do.
2. Maybe consider agentCapability as a DictionaryEntry so it matces the pattern already used for agentExternalTool and agentProtocol,
   3.Consider mapping AutomationLevel to specific software agents behavior (e.g., level 0 = human writes every prompt, level 3 = human approves tool calls, level 5 = agent runs unattended with circuit-breakers, level 6 = self-directed goal modification or something like that.
3. You have listed hree roles (orchestrator, worker, peer) but in the real-world systems also use controllers, supervisors, critics, evaluators, and specialized sub-agents. are being talked about. Rather than trying to enumerate them all, I would keep the three canonical types for interoperability but add an other entry and recommend that producers use agentProtocol to disclose the exact role taxonomy of the protocol they follow (e.g., A2A's "client" vs. "remote"). But your call
4. The AI Profile already has safetyRiskAssessment But b+ecause agents combine models, tools, and autonomy, their risk surface is a superset of a static model. We might want to consider AIAgent to carry its own safetyRiskAssessment (not just inherit via the underlying model) ie. agentRiskLevel property that explicitly addresses agent-specific harms (tool misuse, goal drift, multi-agent cascade failures).
5. Consider adding modelVersionPolicy Agents often update their underlying model or swap tools dynamically. The current proposal is pretty static. I would add a property indicating whether the agent pins model versions, allows automatic updates, or uses A/B testing, so that consumers know if the BOM is still valid after a model refresh. Maybe this field is n the Software Engineering profile
6. I think the cardinality of suppliedBy needs to change. Currently it's suppliedBy as Optional (0..), which is consistent with the UML. However, for regulatory traceability (e.g., EU AI Act), knowing who supplied the agent is as important as knowing who supplied the model. I would make suppliedBy Required (1..) for AIAgent, similar to what we did with originatedBy is required for DatasetPackage in the Dataset Profile.

Looking forward to getting agents into the SPDX 3.1 release.

[AlexanderDenkBMW]

I think the cardinality of suppliedBy needs to change. Currently it's suppliedBy as Optional (0..), which is consistent with the UML. However, for regulatory traceability (e.g., EU AI Act), knowing who supplied the agent is as important as knowing who supplied the model. I would make suppliedBy Required (1..) for AIAgent, similar to what we did with originatedBy is required for DatasetPackage in the Dataset Profile.

In general I'd assume that a well described AI-model requires a supplied-by (profile conformance).

• However from the pure vocabulary I'd see it as fine to have an AI model with an unknown supplier.
  This may imply legal issue to use the model, but for describing model I'd see this as potential way.
  The other (preferred) option would be to require suppliedBy and allow explicit documentation of the known unknown NOASSERTION). To my knowledge this is currently not possible.

• A second use case is that it may be testified for the model in the wrapping context that the supplier is known and documented, but details are not disclosed (e.g. anti-trust issues). Using the supplier of the wrapping context as supplier of the model may cause invalid assumptions. Also in this case an explicite unknown would be nice.

[ElyasRashno]

@bennetkl , thanks for your comments,

1. I have added the usesModel relationship to the Agent class and updated the relationshipType in the core profile.
2. I believe agentCapability is intended to be free-form text describing the agent’s capabilities, but we can discuss this further with the community.
3. Good idea, I have updated the level definitions for automation levels.
4. Let’s raise agentRiskLevel with the community for further discussion.
5. I added two external properties, releaseTime and packageVersion, to capture model versioning and release timing.
6. The suppliedBy cardinality has been changed to 1.

[bact]

Apart from the useTools and invokedBy relationship types,
we also have existing delegatedTo which may also relevant.

delegatedTo is a relationship over a relationship (of type invokedBy).

[rgopikrishnan91]

@ElyasRashno I am not sure if agentProtocol is the right name. MCP are things an Agent can use, but it can also use a mix of things. I don't think we should say it as agent protocol and might need to says, tools available? and tool type can be MCP.. ? Similarly for the otherones, we need to define it a bit further based on what is being enabled

[bennetkl]

Agree with Gopi, MCP isn't just an "agent protocol" these days ; it's a protocol that can describe what the agent offers or what it consumes, depending on context. The only thing though in support of the chose of Agentprotocol as the field name is if you had more clarification in the description ie. agentProtocol : The protocol(s) the agent exposes for external interaction (MCP, A2A, etc.) and added.
toolsAvailable : The tools, APIs, or capabilities the agent consumes or invokes internally, with toolType (MCP, API, plugin, etc.) and toolScope (what capability is enabled). Just a thought.

[ElyasRashno]

@ElyasRashno I am not sure if agentProtocol is the right name. MCP are things an Agent can use, but it can also use a mix of things. I don't think we should say it as agent protocol and might need to says, tools available? and tool type can be MCP.. ? Similarly for the otherones, we need to define it a bit further based on what is being enabled

@rgopikrishnan91 , thanks for comment. Any suggestions on splitting this into two fields: toolIntegrationProtocol, which covers MCP and OpenAPI, and a second field, agentCommunicationProtocol, which covers A2A, ANP, and other similar types? Does this make sense?

[stevenc-stb]

what is the scope of AIAgent?