`. |
74 | | created_at | 4 | string | | Creation timestamp of the agent in the RFC3339 format. Specs: https://www.rfc-editor.org/rfc/rfc3339.html |
75 | | annotations | 5 | string, string | Map | Additional metadata associated with this agent. |
76 | | skills | 6 | string | Repeated | List of skills that this agent is capable of performing. Specs: https://schema.oasf.agntcy.org/skills |
77 | | locators | 7 | Locator | Repeated | List of source locators where this agent can be found or used from. |
78 | | extensions | 8 | Extension | Repeated | List of extensions that describe this agent more in depth. |
79 |
80 |
81 |
82 | ### Locator Diagram
83 |
84 | ```mermaid
85 | classDiagram
86 | direction LR
87 |
88 | %% Locators provide actual artifact locators of an agent. For example, this can reference sources such as helm charts, docker images, binaries, etc.
89 |
90 | class Locator {
91 | + string url
92 | + string type
93 | + Map~string, string~ annotations
94 | + Optional~uint64~ size
95 | + Optional~string~ digest
96 | }
97 |
98 | ```
99 | ### Extension Diagram
100 |
101 | ```mermaid
102 | classDiagram
103 | direction LR
104 |
105 | %% Extensions provide dynamic descriptors for an agent. For example, security and categorization features can be described using extensions.
106 |
107 | class Extension {
108 | + string name
109 | + string version
110 | + Map~string, string~ annotations
111 | + bytes specs
112 | }
113 |
114 | ```
115 |
116 | ## Message: Locator
117 | FQN: schema.model.Agent.Locator
118 |
119 |
120 |
121 | | Field | Ordinal | Type | Label | Description |
122 | |-------------|---------|----------------|----------|------------------------------------------------------------------------------------|
123 | | url | 1 | string | | Location URI where this source locator can be found. |
124 | | type | 2 | string | | Type of the source locator, for example: "docker-image", "binary", "source-code". |
125 | | annotations | 3 | string, string | Map | Metadata associated with this source locator. |
126 | | size | 4 | uint64 | Optional | Size in bytes of the source locator pointed by the `url` property. |
127 | | digest | 5 | string | Optional | Digest of the source locator pointed by the `url` property. |
128 |
129 |
130 |
131 |
132 | ## Message: Extension
133 | FQN: schema.model.Agent.Extension
134 |
135 |
136 |
137 | | Field | Ordinal | Type | Label | Description |
138 | |-------------|---------|----------------|-------|-----------------------------------------------------------------------------------------------|
139 | | name | 1 | string | | Name of the extension. |
140 | | version | 2 | string | | Version of the extension. |
141 | | annotations | 3 | string, string | Map | Metadata associated with this extension. |
142 | | specs | 4 | bytes | | Value of the data, it is available directly or can be constructed by fetching from some URL. |
143 |
144 |
145 |
146 |
147 |
148 |
149 |
150 |
151 |
--------------------------------------------------------------------------------
/docs/pages/oasf-taxonomy.md:
--------------------------------------------------------------------------------
1 | # Taxonomy of AI Agent Skills
2 |
3 | | Category | Skill | UID | Description |
4 | |-----------------------------------------------|-----------------------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
5 | | Natural Language Understanding | Natural Language Understanding | 101 | Describes the ability to understand the meaning of a given situation or event. |
6 | | Natural Language Generation | Natural Language Generation | 102 | Describes the ability to generate human-like text from structured data or other inputs. |
7 | | Information Retrieval and Synthesis | Information Retrieval and Synthesis | 103 | Capabilities for retrieving relevant information from various sources and synthesizing it into coherent, contextually appropriate responses. This includes searching, extracting, combining, and presenting information in a meaningful way. |
8 | | Creative Content Generation | Creative Content Generation | 104 | Capabilities for generating various forms of creative content, including narratives, poetry, and other creative writing forms. |
9 | | Language Translation and Multilingual Support | Language Translation and Multilingual Support | 105 | Capabilities for handling multiple languages, including translation and multilingual text processing. |
10 | | Personalisation and Adaptation | Personalisation and Adaptation | 106 | Capabilities for adapting and personalizing content based on user context and preferences. |
11 | | Analytical and Logical Reasoning | Analytical and Logical Reasoning | 107 | Capabilities for performing logical analysis, inference, and problem-solving tasks. |
12 | | Ethical and Safe Interaction | Ethical and Safe Interaction | 108 | Capabilities for ensuring ethical, unbiased, and safe content generation and interaction. |
13 | | Text Classification | Text Classification | 109 | Capabilities for classifying and categorizing text into predefined categories or labels. |
14 | | Feature Extraction | Feature Extraction | 110 | Capabilities for extracting and representing textual features as vectors for downstream tasks. |
15 | | Token Classification | Token Classification | 111 | Capabilities for classifying individual tokens or words within text. |
16 | | Contextual Comprehension | Contextual Comprehension | 10101 | Describes the ability to understand the context of a given situation or event. |
17 | | Semantic Understanding | Semantic Understanding | 10102 | Describes the ability to understand the meaning of a given situation or event. |
18 | | Entity Recognition | Entity Recognition | 10103 | Describes the ability to identify and classify entities in a given situation or event. |
19 | | Text Completion | Text Completion | 10201 | Continuing a given text prompt in a coherent and contextually appropriate manner to generate fluent and contextually relevant content. |
20 | | Text Summarization | Text Summarization | 10202 | Condensing longer texts into concise summaries while preserving essential information and maintaining coherence. |
21 | | Text Paraphrasing | Text Paraphrasing | 10203 | Rewriting text to express the same ideas using different words and structures while maintaining the original meaning. |
22 | | Dialogue Generation | Dialogue Generation | 10204 | Producing conversational responses that are contextually relevant and engaging within a dialogue context. |
23 | | Question Generation | Question Generation | 10205 | Automatically generating relevant and meaningful questions from a given text or context. |
24 | | Text Style Transfer | Text Style Transfer | 10206 | Rewriting text to match the style of a given reference text while preserving the original content. |
25 | | Story Generation | Story Generation | 10207 | Generating a piece of text given a description or a first sentence to complete. |
26 | | Fact Extraction | Fact Extraction | 10301 | Capability to identify and extract factual information from text documents or knowledge bases, including entities, relationships, and key data points. |
27 | | Question Answering | Question Answering | 10302 | System capability to understand questions and provide accurate, relevant answers by analyzing available information sources. |
28 | | Knowledge Synthesis | Knowledge Synthesis | 10303 | Capability to aggregate and combine information from multiple sources, creating comprehensive and coherent responses while maintaining context and relevance. |
29 | | Sentence Similarity | Sentence Similarity | 10304 | Capability to analyze and determine the semantic similarity between sentences, supporting tasks like search, matching, and content comparison. |
30 | | Document and Passage Retrieval | Document and Passage Retrieval | 10305 | Capability to identify and retrieve relevant documents or text passages based on specific criteria or queries from a larger collection of texts. |
31 | | Search | Search | 10306 | Capability to perform efficient and accurate searches within large textual databases based on various criteria, including keywords, semantic meaning, or complex queries. |
32 | | Storytelling | Storytelling | 10401 | Creating narratives, stories, or fictional content with creativity and coherence. |
33 | | Poetry and Creative Writing | Poetry and Creative Writing | 10402 | Composing poems, prose, or other forms of creative literature. |
34 | | Translation | Translation | 10501 | Converting text from one language to another while maintaining meaning and context. |
35 | | Multilingual Understanding | Multilingual Understanding | 10502 | Recognising and processing text in multiple languages. |
36 | | User Adaptation | User Adaptation | 10601 | Tailoring responses based on user preferences, history, or context. |
37 | | Tone and Style Adjustment | Tone and Style Adjustment | 10602 | Modifying the tone or style of generated text to suit specific audiences or purposes. |
38 | | Inference and Deduction | Inference and Deduction | 10701 | Making logical inferences based on provided information. |
39 | | Problem Solving | Problem Solving | 10702 | Assisting with solving problems by generating potential solutions or strategies. |
40 | | Fact and Claim Verification | Fact and Claim Verification | 10703 | Verifying facts and claims given a reference text. |
41 | | Bias Mitigation | Bias Mitigation | 10801 | Reducing or eliminating biased language and ensuring fair and unbiased output. |
42 | | Content Moderation | Content Moderation | 10802 | Avoiding the generation of harmful, inappropriate, or sensitive content. |
43 | | Topic Labelling and Tagging | Topic Labelling and Tagging | 10901 | Classifying a text as belonging to one of several topics, which can be used to tag a text. |
44 | | Sentiment Analysis | Sentiment Analysis | 10902 | Classify the sentiment of a text, e.g., a positive movie review. |
45 | | Natural Language Inference | Natural Language Inference | 10903 | Classifying the relation between two texts, e.g., as a contradiction, entailment, etc. |
46 | | Model Feature Extraction | Model Feature Extraction | 11001 | Representing parts of text with vectors to be used as input to other tasks. |
47 | | Named Entity Recognition | Named Entity Recognition | 11101 | Task to recognise names as entities, e.g., people, locations, buildings, etc. |
48 | | Part-of-Speech Tagging | Part-of-Speech Tagging | 11102 | Tagging each part of a sentence as nouns, adjectives, verbs, etc. |
--------------------------------------------------------------------------------
/docs/pages/oasf-workflow.md:
--------------------------------------------------------------------------------
1 | # OASF Contribution Guide
2 |
3 | This documentation presents guidelines and expected etiquette to successfully
4 | contribute to the development of OASF Schemas and the framework itself.
5 |
6 | * * *
7 |
8 | ## Terminology
9 |
10 | 1. **Field**: A field is a unique identifier name for a piece of data contained in OASF. Each field also designates a corresponding `data_type`.
11 | 2. **Object**: An object is a collection of contextually related fields and other objects. It is also a data_type in OASF.
12 | 3. **Attribute**: An attribute is the more generic name for both fields and objects in OASF. A field is a scalar attribute while an object is a complex attribute.
13 | 4. **Class**: A class is a particular set of attributes (including fields & objects) representing metadata associated to an autonomous agent.
14 | 5. **Category:** A Category organizes classes that represent a particular domain.
15 |
16 | ## How do I add a `class`?
17 |
18 | ### Overview
19 |
20 | 1. Determine all the `attributes` (including fields and objects) you want to add in the `class`.
21 | 2. Check the [dictionary](https://github.com/agntcy/oasf/blob/main/schema/dictionary.json) and the [/objects](https://github.com/agntcy/oasf/tree/main/schema/objects) folder, many of your desired attributes may already be present.
22 | 3. Define the missing attributes → [Adding/Modifying an `attribute`](#adding-modifying-an-attribute)
23 | 4. Determine which category you want to add your class in, note it’s `name`.
24 | 5. Create a new file → `` inside the category specific subdirectory in the [/schema](https://github.com/agntcy/oasf/tree/main/schema) folder. Template available [here](https://github.com/agntcy/oasf/blob/main/schema/templates/class_name.json).
25 | 6. Define the `class` itself → [Adding/Modifying a `class`](#adding-modifying-a-class).
26 | 7. Verify the changes are working as expected in your local [oasf/server](https://github.com/agntcy/oasf/tree/main/server).
27 |
28 | * * *
29 |
30 | ### Adding/Modifying an `attribute`
31 |
32 | 1. All the available `attributes` - `fields` and `objects` in OASF must be defined in the attribute dictionary, the [dictionary.json](https://github.com/agntcy/oasf/blob/main/schema/dictionary.json) file and [/objects](https://github.com/agntcy/oasf/tree/main/schema/objects) folder if defining an object.
33 | 2. Determine if a new attribute is required for your change, it might already be defined in the attribute dictionary and/or the [/objects](https://github.com/agntcy/oasf/tree/main/schema/objects) folder.
34 | 3. Before adding a new attribute, review the following OASF attribute conventions:
35 |
36 | * Attribute names must be a valid UTF-8 sequence.
37 | * Attribute names must be all lower case.
38 | * Combine words using underscore.
39 | * No special characters except underscore.
40 | * Use present tense unless the attribute describes historical information.
41 | * Use singular and plural names properly to reflect the field content.
42 | * When an attribute represents multiple entities, the attribute name should be pluralized and the value type should be an array.
43 | * Avoid word repetition.
44 | * Avoid abbreviations when possible. Some exceptions can be made for well-accepted abbreviation like well known acronyms (for example, LLM or AI).
45 |
46 | #### How to define a `field` in the dictionary?
47 |
48 | To add a new field in OASF, you must define it in the [dictionary.json](https://github.com/agntcy/oasf/blob/main/schema/dictionary.json) file as described below.
49 |
50 | Sample entry in the dictionary:
51 |
52 | ```
53 | "uid":
54 | {
55 | "caption": "Unique ID", // "previously name"
56 | "description": "The unique identifier. See specific usage.",
57 | "type": "string_t"
58 | }
59 | ```
60 |
61 | Choose a **unique** field you want to add, `uid` in the example above and populate it as described below.
62 |
63 | 1. `caption`: A user-friendly name to the field.
64 | 2. `description`: A concise description to define the attributes.
65 | 1. Note that `field` descriptions can be overridden in the `class/object`, therefore if it’s a common field (like name, label, uid) feel free to add a generic description, specific descriptions can be added in the `class/object` definition. For example:
66 | 2. A generic definition of `uid` in the dictionary:
67 | 1. `uid` : `The unique identifier. See specific usage.`
68 | 3. Specific description of `uid` in the `agent` object:
69 | 1. `uid` : `Unique Identifier/s of the reported agent."`
70 | 3. `type`: Review OASF data_types and ensure you utilize appropriate types while defining new fields.
71 | 1. All the available data_types can be accessed [here](https://schema.oasf.agntcy.org/data_types).
72 | 2. They are also accessible in your local instance of the oasf server (http://localhost:8000/data_types).
73 | 4. `is_array`: This a boolean key:value pair that you must add if the field you are defining is an array.
74 | 1. For example: `"is_array": true`
75 |
76 | #### How to define an `object`?
77 |
78 | 1. All the available `objects` must be defined as individual field entries in the dictionary, the [dictionary.json](https://github.com/agntcy/oasf/blob/main/schema/dictionary.json) file and as distinct .json files in the [/objects](https://github.com/agntcy/oasf/tree/main/schema/objects) folder.
79 | 2. Review existing Objects, determine if a modification of the existing object would be sufficient or if there’s a need for a completely new object.
80 | 3. Use the template available [here](https://github.com/agntcy/oasf/blob/main/schema/templates/object_name.json), to get started with .json file definition.
81 |
82 | An example `locator.json` object file:
83 |
84 | ```
85 | {
86 | "caption": "Agent Locator",
87 | "description": "Locators provide actual artifact locators of an agent. For example, this can reference sources such as helm charts, docker images, binaries, etc.",
88 | "extends": "_entity",
89 | "name": "locator",
90 | "attributes": {
91 | "name": {
92 | "description": "The schema extension name. For example: dev.",
93 | "requirement": "required"
94 | },
95 | "annotations": {
96 | "caption": "Annotations",
97 | "description": "Additional metadata associated with the extension.",
98 | "requirement": "optional"
99 | },
100 | "type": {
101 | "caption": "Type",
102 | "description": "Describes the type of the release manifest pointed by its URI, e.g. oci-image, docker-image, py-package, binary. Allowed values MAY be defined for common manifest types.",
103 | "requirement": "required"
104 | },
105 | "url": {
106 | "caption": "URL",
107 | "description": "Specifies an URI from which this object MAY be downloaded. Value MUST conform to RFC 3986. Value SHOULD use the http and https schemes, as defined in RFC 7230.",
108 | "requirement": "required"
109 | },
110 | "size": {
111 | "caption": "Size",
112 | "description": "Specifies the size of the release manifest in bytes.",
113 | "requirement": "optional"
114 | },
115 | "digest": {
116 | "caption": "Digest",
117 | "description": "Specifies the digest of the release manifest contents.",
118 | "requirement": "optional"
119 | }
120 | },
121 | "constraints": {}
122 | }
123 | ```
124 |
125 | 4. `caption`: A user-friendly name to the object.
126 | 5. `description`: A concise description to define the object.
127 | 6. `extends`: Ensure the value is `object` or an existing object, for example `skill` (all objects in OSAF must extend a base definition of `object` or another existing object).
128 | 7. `name`: Add a **unique** name of the object. `name` must match the filename of the actual `.json` file.
129 | 8. `attributes`: Add the attributes that you want to define in the object:
130 | 1. `requirement`: For each attribute ensure you add a requirement value. Valid values are `optional`, `required`, and `recommended`
131 | 2. `$include`: You can include attributes from other places; to do so, specify a virtual attribute called `$include` and give its value as the list of files (relative to the root of the schema repository) that should contribute their attributes to this object. For example:
132 | ```
133 | "attributes": {
134 | "$include": [
135 | "profiles/host.json"
136 | ],
137 | ...
138 | }
139 | ```
140 |
141 | **Note:** If you want to create an object which would act only as a base for other objects, you must prefix the object `name` and the actual `json` filename with an `_`. The resultant object will not be visible in the [OASF Server.](https://schema.oasf.agntcy.org/objects). For example, take a look at the [entity](https://github.com/agntcy/oasf/blob/main/schema/objects/_entity.json) object.
142 |
143 | Sample entry in the `dictionary.json`:
144 |
145 | ```
146 | "skill": {
147 | "caption": "Skill",
148 | "description": "A skill that apply to an agent.",
149 | "type": "class_t",
150 | "class_path": "classes/base_skill",
151 | "class_name": "Skill"
152 | }
153 | ```
154 |
155 | Choose a **unique** object you want to add, `skill` in the example above and populate it as described below.
156 |
157 | 1. `caption`: A user-friendly name to the object.
158 | 2. `description`: A concise description to define the object.
159 | 3. `type`: The type of the object you are defining.
160 | 4. `is_array`: This a boolean key:value pair that you must add if the object you are defining is an array.
161 | 1. for example: `"is_array": true`.
162 |
163 | ```
164 | "skills": {
165 | "caption": "Skills",
166 | "description": "Skills that apply to an agent.",
167 | "type": "class_t",
168 | "class_path": "skills",
169 | "class_name": "Skill",
170 | "is_array": true
171 | }
172 | ```
173 |
174 | * * *
175 |
176 | ### Adding/Modifying a `class`
177 |
178 | 1. All the available Classes are defined as .json files in the [/schema](https://github.com/agntcy/oasf/tree/main/schema) folder.
179 | 2. Review existing Classes, determine if a modification of the existing class would be sufficient or if there’s a need for a completely new class.
180 | 3. To define a new class,
181 | 1. Create a new file → `` inside the category specific subdirectory in the [/schema](https://github.com/agntcy/oasf/tree/main/schema) folder.
182 | 2. Use the template available [here](https://github.com/agntcy/oasf/tree/main/schema/templates/class_name.json) to get started with the .json definition.
183 | 3. `uid`: Select an integer in the range 0 - 99. Ensure the integer is **unique** within the category.
184 | * Note: Without `uid`, a class won’t be visible in the oasf server.
185 | 4. `caption`: Add a user-friendly name to the event_class.
186 | 5. `description`: Add a concise description to define the attributes.
187 | 6. `name`: Add a **unique** name of the class. Ensure it matches the file name to maintain consistency.
188 | 7. `extends`: Ensure the value container the parent class `class`.
189 | 8. `attributes`: Add the attributes that you want to define in the `event_class`:
190 | 1. `group`: For each attribute ensure you add a group value. Valid values are `classification`, `context`, `occurrence`, and `primary`.
191 | 2. `requirement`: For each attribute ensure you add a requirement value. Valid values are `optional`, `required`, and `recommended`
192 | 3. `$include`: As for objects, you can also include attributes from other places. To do so, specify the list of files (relative to the root of the schema repository) that should contribute their attributes to this object. For example:
193 | ```
194 | "attributes": {
195 | "$include": [
196 | "profiles/cloud.json"
197 | ],
198 | ...
199 | }
200 | ```
201 |
202 | 9. `constraints`: For each class you can add constraints on the attribute requirements. Valid constraint types are `at_least_one` and `just_one`. For example:
203 | ```
204 | "constraints": {
205 | "at_least_one": [
206 | "uid",
207 | "name"
208 | ]
209 | }
210 | ```
211 |
212 | _(A Constraint is a documented rule subject to validation that requires at least one of the specified recommended attributes of a class to be populated.)_
213 |
214 | * * *
215 |
216 | ### Deprecating an attribute
217 |
218 | To deprecate an attribute (`field`, `object`) follow the steps below:
219 |
220 | 1. Create a GitHub issue, explaining why an attribute needs to be deprecated and what the alternate solution is.
221 | 2. Utilize the following flag to allow deprecation of attributes. This flag needs to be added a json property of the attribute that is the subject of deprecation.
222 | ```
223 | "@deprecated": {
224 | "message": "Use the ALTERNATE_ATTRIBUTE attribute instead.",
225 | "since": "semver"
226 | }
227 | ```
228 | 3. Example of a deprecated field:
229 | ```
230 | "packages": {
231 | "@deprecated": {
232 | "message": "Use the affected_packages attribute instead.",
233 | "since": "1.0.0"
234 | },
235 | "caption": "Software Packages",
236 | "description": "List of vulnerable packages as identified by the security product",
237 | "is_array": true,
238 | "type": "package"
239 | }
240 | 4. Example of a deprecated object:
241 | ```
242 | {
243 | "caption": "Finding",
244 | "description": "The Finding object describes metadata related to a security finding generated by a security tool or system.",
245 | "extends": "object",
246 | "name": "finding",
247 | "@deprecated": {
248 | "message": "Use the new finding_info object.",
249 | "since": "1.0.0"
250 | },
251 | "attributes": {...}
252 | }
253 | ***
254 |
255 | ### Verifying the changes
256 |
257 | Contributors should verify the changes before they submit the PR, the best
258 | method to test and verify their changes is to run a local instance of the
259 | [oasf/server](https://github.com/agntcy/oasf/tree/main/server).
260 |
261 | If there are any problems with the newly made changes, the server will throw
262 | corresponding errors. Sample error messages:
263 |
264 | ```
265 | [error] dictionary: missing attribute:
266 | ```
267 | Address the errors before submitting the changes, your server run should be completely error free.
268 |
269 | ***
270 |
271 | ### Developer's Certificate of Origin 1.1
272 |
273 | By making a contribution to this project, I certify that:
274 |
275 | (a) The contribution was created in whole or in part by me and I
276 | have the right to submit it under the open source license
277 | indicated in the file; or
278 |
279 | (b) The contribution is based upon previous work that, to the
280 | best of my knowledge, is covered under an appropriate open
281 | source license and I have the right under that license to
282 | submit that work with modifications, whether created in whole
283 | or in part by me, under the same open source license (unless
284 | I am permitted to submit under a different license), as
285 | indicated in the file; or
286 |
287 | (c) The contribution was provided directly to me by some other
288 | person who certified (a), (b) or (c) and I have not modified
289 | it.
290 |
291 | (d) I understand and agree that this project and the contribution
292 | are public and that a record of the contribution (including
293 | all personal information I submit with it, including my
294 | sign-off) is maintained indefinitely and may be redistributed
295 | consistent with this project or the open source license(s)
296 | involved.
297 |
298 | ---
299 | We require that every contribution to this repository is signed with a
300 | Developer Certificate of Origin. Additionally, please use your real name.
301 | We do not accept anonymous contributors nor those utilizing pseudonyms.
302 |
303 | Each commit must include a DCO which looks like this
304 |
305 | Signed-off-by: Jane Smith
306 |
307 | You may type this line on your own when writing your commit messages.
308 | However, if your user.name and user.email are set in your git configs,
309 | you can use -s or --signoff to add the Signed-off-by line to the end of the commit message.
310 |
311 | * * *
312 |
313 | ## OASF Extensions
314 |
315 | The OASF Schema can be extended by adding an extension that defines additional
316 | attributes, objects, profiles, event classes and/or categories.
317 | Extensions allow one to create vendor/customer specific schemas or augment an
318 | existing schema to better suit their custom requirements. Extensions can also
319 | be used to factor out non-essential schema domains keeping the core schema
320 | succinct. Extensions use the framework in the same way as a new schema,
321 | optionally creating categories, profiles or event classes from the dictionary.
322 |
323 | As with categories and classes, extensions have unique IDs within the
324 | framework as well as their own versioning. The following sections provide
325 | guidelines to create extensions within OASF.
326 |
327 | ### Reserve a UID and Name for your extension
328 |
329 | In order to reserve an ID space, and make your extension public, add a unique
330 | identifier & a unique name for your extension in the OASF Extensions Registry
331 | [here](https://github.com/agntcy/oasf/blob/main/schema/extensions.md).
332 | This is done to avoid collisions with core or other extension schemas.
333 | For example, a new sample extension would have a row in the table as follows:
334 |
335 | | **Caption** | **Name** | **UID** | **Notes** |
336 | |---------------|----------|---------|-----------------------------------|
337 | | New Extension | new_ex | 123 | The development schema extensions |
338 |
339 | ### Create your Extension's subdirectory
340 |
341 | To extend the schema, create a new subdirectory in the `extensions` directory,
342 | and add a new `extension.json` file, which defines the extension's `name`
343 | and `uid`. For example:
344 |
345 | ```
346 | {
347 | "caption": "New Extension",
348 | "name": "new_ex",
349 | "uid": 123,
350 | "version": "0.0.0"
351 | }
352 | ```
353 |
354 | The extension's directory structure is the same as the top level schema directory,
355 | and it may contain the following files and subdirectories, depending on what type of extension is desired:
356 |
--------------------------------------------------------------------------------
/docs/pages/oasf.md:
--------------------------------------------------------------------------------
1 | # Open Agentic Schema Framework
2 |
3 | The Open Agentic Schema Framework (OASF) is a standardized schema system for
4 | defining and managing AI agent capabilities, interactions, and metadata. It
5 | provides a structured way to describe agent attributes, capabilities, and
6 | relationships using attribute-based taxonomies. The framework includes
7 | development tools, schema validation, and hot-reload capabilities for rapid
8 | schema development, all managed through a Taskfile-based workflow and
9 | containerized development environment. The OASF serves as the foundation for
10 | interoperable AI agent systems, enabling consistent definition and discovery of
11 | agent capabilities across distributed systems.
12 |
13 | ## Features
14 |
15 | The OASF defines a set of standards for AI agent content representation that aims to:
16 |
17 | - Define common data structure to facilitate content standardisation, validation, and interoperability.
18 | - Ensure unique agent identification to address content discovery and consumption.
19 | - Provide extension capabilities to enable third-party features.
20 |
21 | A core component in OASF is to implement data types and core objects that define the skills of autonomous agents. This component helps in announcing and discovering agents with these skills across various data platforms.
22 |
23 | The current skill set taxonomy is described in [Taxonomy of AI Agent Skills](oasf-taxonomy.md).
24 |
25 | The guidelines to upgrade and maintain OASF are outlined in the [OASF Contribution Guide](oasf-workflow.md).
26 |
27 | ### Open Agentic Schema Framework Server
28 |
29 | The server/directory contains the Open Agents Schema Framework (OASF) Schema Server source code.
30 | The schema server is an HTTP server that provides a convenient way to browse and use the OASF schema.
31 | The server provides also schema validation capabilities to be used during development.
32 |
33 | You can access the OASF schema server, which is running the latest released schema, at [schema.oasf.agntcy.org](https://schema.oasf.agntcy.org).
34 |
35 | The schema server can also be used locally.
36 |
37 | ## Prerequisites
38 |
39 | - [Taskfile](https://taskfile.dev/)
40 | - [Docker](https://www.docker.com/)
41 |
42 | Make sure Docker is installed with Buildx.
43 |
44 | ## Development
45 |
46 | Use `Taskfile` for all related development operations such as testing, validating, deploying, and working with the project.
47 |
48 | ### Clone the repository
49 |
50 | ```shell
51 | git clone https://github.com/agntcy/oasf.git
52 | ```
53 |
54 | ### Build artifacts
55 |
56 | This step fetches all project dependencies and
57 | subsequently build all project artifacts such as
58 | Helm charts and Docker images.
59 |
60 | ```shell
61 | task deps
62 | task build
63 | ```
64 |
65 | ### Deploy locally
66 |
67 | This step creates an ephemeral Kind cluster
68 | and deploy OASF services through Helm chart.
69 | It also sets up port forwarding
70 | so that the services can be accessed locally.
71 |
72 | ```shell
73 | task up
74 | ```
75 |
76 | To access the schema server, open [`localhost:8080`](http://localhost:8080) in your browser.
77 |
78 | **Note**: Any changes made to the schema or server backend itself requires running `task up` again.
79 |
80 | ### Hot reload
81 |
82 | In order to run the server in hot-reload mode, you must first deploy
83 | the services, and run another command to signal that the schema will be actively updated.
84 |
85 | This can be achieved by starting an interactive reload session through:
86 |
87 | ```shell
88 | task reload
89 | ```
90 |
91 | Note that this only performs hot-reload for schema changes.
92 | Reloading backend changes still requires re-running `task build && task up`.
93 |
94 | ### Cleanup
95 |
96 | This step handles cleanup procedure by
97 | removing resources from previous steps,
98 | including ephemeral Kind clusters and Docker containers.
99 |
100 | ```shell
101 | task down
102 | ```
103 |
104 | ## Artifacts distribution
105 |
106 | See https://github.com/orgs/agntcy/packages?repo_name=oasf.
107 |
--------------------------------------------------------------------------------
/docs/pages/semantic_sdk/semantic_router.md:
--------------------------------------------------------------------------------
1 | # Semantic Router Agent (Coming soon)
2 |
3 | When defining a multi-agent application workflow, it is often necessary to make decisions based on the output of invoked agents.
4 |
5 | In a graph-based agentic applications (for example, LangGraph), this corresponds to decideing which node in the graph to execute based on the current state of the graph.
6 |
7 | There is a large set of common decisions that are based on semantic similarity, even if some of these decisions can be trivially implemented by a simple `if` condition and others can be so complex that they require a dedicated agent to be processed.
8 |
9 | This is where the Semantic Router Agent comes in. The Semantic Router Agent is a component, modelled as a node in the graph, that takes an input in the form of natural language and decides where to go next. Here next means following an edge in the graph that is associated to the semantically closest reference natural language text. In other words: the Semantic Router Agent chooses the next node based on a semantic routing table.
10 |
11 | **Example**:
12 |
13 | > An assistant agent receives a prompt from a user during a conversation and based on the content, it needs to perform different actions:
14 | > - If the user is posting a new request, start the request handling flow.
15 | > - If the user is satisfied with the conversation, terminate it and direct the flow to the auditing agent.
16 | > - If the user is not satisfied, involve a human.
17 | >
18 | > The above can be implemented with a semantic router agent with three possible routes, with each route associated with a text describing what is the expected content of the user prompt.
19 |
--------------------------------------------------------------------------------
/docs/pages/syntactic_sdk/agntcy_acp_sdk.md:
--------------------------------------------------------------------------------
1 | # Agntcy ACP Client
2 |
3 | ## Introduction
4 |
5 | The Agent Connect Protocol SDK is an open-source library designed to
6 | facilitate the adoption of the Agent Connect Protocol. It offers tools
7 | for client implementations, enabling seamless integration, and communication
8 | between multi-agent systems.
9 |
10 | The SDK is current available in [Python](https://pypi.org/project/agntcy-acp/) [](https://pypi.org/project/agntcy-acp/).
11 |
12 | ## Getting Started with the client
13 |
14 | To use the package, follow the steps below.
15 |
16 | ### Requirements
17 |
18 | Python 3.9+
19 |
20 | ### Installation
21 |
22 | Install the latest version from PyPi:
23 | ```shell
24 | pip install agntcy-acp
25 | ```
26 |
27 | ### Usage
28 |
29 | ```{code-block} python
30 | from agntcy_acp import AsyncACPClient, AsyncApiClient, ApiException
31 | from agntcy_acp.models import RunCreate
32 |
33 | # Defining the host is optional and defaults to http://localhost
34 | config = ApiClientConfiguration(
35 | host="https://localhost:8081/",
36 | api_key={"x-api-key": os.environ["API_KEY"]},
37 | retries=3
38 | )
39 |
40 | # Enter a context with an instance of the API client
41 | async with AsyncApiClient(config) as api_client:
42 | agent_id = 'agent_id_example' # str | The ID of the agent.
43 | client = AsyncACPClient(api_client)
44 |
45 | try:
46 | api_response = client.create_run(RunCreate(agent_id="my-agent-id"))
47 | print(f"Run {api_response.run_id} is currently {api_response.status}")
48 | except ApiException as e:
49 | print("Exception when calling create_run: %s\n" % e)
50 | ```
51 |
52 | ### Documentation for API Endpoints
53 |
54 | The complete documentation for all of the API Endpoints are
55 | available in the reference documentation for the API clients:
56 |
57 | * [ACPClient](https://agntcy.github.io/acp-sdk/html/agntcy_acp.html#agntcy_acp.ACPClient)
58 | * [AsyncACPClient](https://agntcy.github.io/acp-sdk/html/agntcy_acp.html#agntcy_acp.AsyncACPClient)
59 |
60 | ## Using ACP with LangGraph
61 |
62 | The SDK provides integration with LangGraph with the {py:obj}`agntcy_acp.langgraph.ACPNode` class
63 | that can be used as a graph node:
64 |
65 | ```python
66 | from enum import Enum
67 | from typing import List, Optional
68 |
69 | from langgraph.graph import END, START, StateGraph
70 | from pydantic import BaseModel, Field
71 |
72 | from agntcy_acp import ApiClientConfiguration
73 | from agntcy_acp.langgraph.acp_node import ACPNode
74 |
75 |
76 | class Type(Enum):
77 | human = 'human'
78 | assistant = 'assistant'
79 | ai = 'ai'
80 |
81 | class Message(BaseModel):
82 | type: Type = Field(
83 | ...,
84 | description='indicates the originator of the message, a human or an assistant',
85 | )
86 | content: str = Field(..., description='the content of the message', title='Content')
87 |
88 | class InputSchema(BaseModel):
89 | messages: Optional[List[Message]] = Field(None, title='Messages')
90 | is_completed: Optional[bool] = Field(None, title='Is Completed')
91 |
92 | class OutputSchema(BaseModel):
93 | messages: Optional[List[Message]] = Field(None, title='Messages')
94 | is_completed: Optional[bool] = Field(None, title='Is Completed')
95 | final_email: Optional[str] = Field(
96 | None,
97 | description='Final email produced by the mail composer',
98 | title='Final Email',
99 | )
100 |
101 | class StateMeasures(BaseModel):
102 | input: InputSchema
103 | output: OutputSchema
104 |
105 | def main():
106 | # Instantiate the local ACP node for the remote agent
107 | acp_node = ACPNode(
108 | name="mailcomposer",
109 | agent_id='50272dfd-4c77-4529-abbb-419bb1724230',
110 | client_config=ApiClientConfiguration.fromEnvPrefix("COMPOSER_"),
111 | input_path="input",
112 | input_type=InputSchema,
113 | output_path="output",
114 | output_type=OutputSchema,
115 | )
116 |
117 | # Create the state graph
118 | sg = StateGraph(StateMeasures)
119 |
120 | # Add edges
121 | sg.add_edge(START, acp_node.get_name())
122 | sg.add_edge(acp_node.get_name(), END)
123 |
124 | graph = sg.compile()
125 | output_state = graph.invoke({
126 | "input": InputSchema(content=input),
127 | "output": OutputSchema(content="bad-output"),
128 | })
129 | ```
130 |
131 | ## Using the CLI to generate Agent-specific bindings
132 |
133 | The Client SDK includes a CLI tool to generate models or OpenAPI specs
134 | specific to an agent using the manifest descriptor. With these models
135 | the agent-specific data sent to ACP can be validated. By default,
136 | only the ACP parameters are validated by the SDK client.
137 |
138 | The CLI also provides validators for the ACP descriptor and manifest
139 | files.
140 |
141 | You can use the CLI easily:
142 | * using [poetry](https://python-poetry.org/): `poetry run acp --help`
143 | * with the package installed: `python3 -m agntcy_acp --help`
144 |
145 | Usage: `acp [OPTIONS] COMMAND [ARGS]...`
146 |
147 | Options:
148 |
149 | * `--help` Show this message and exit.
150 |
151 | Commands:
152 |
153 | * `generate-agent-models [OPTIONS] AGENT_DESCRIPTOR_PATH`
154 |
155 | Generate pydantic models from agent manifest or descriptor.
156 |
157 | Options:
158 |
159 | * `--output-dir TEXT`
160 |
161 | Pydantic models for specific agent based on provided
162 | agent descriptor or agent manifest [required]
163 |
164 | * `--model-file-name TEXT`
165 |
166 | Filename containing the pydantic model of the agent
167 | schemas
168 |
169 | * `generate-agent-oapi [OPTIONS] AGENT_DESCRIPTOR_PATH`
170 |
171 | Generate OpenAPI Spec from agent manifest or descriptor
172 |
173 | Options:
174 |
175 | * `--output TEXT`
176 |
177 | OpenAPI output file
178 |
179 | * `validate-acp-descriptor [OPTIONS] AGENT_DESCRIPTOR_PATH`
180 |
181 | Validate the Agent Descriptor contained in the file AGENT_DESCRIPTOR_PATH
182 | against the ACP specification
183 |
184 | * `validate-acp-manifest [OPTIONS] AGENT_MANIFEST_PATH`
185 |
186 | Validate the Agent Manifest contained in the file AGENT_MANIFEST_PATH
187 | against the Manifest specification
188 |
189 |
190 | ## Testing
191 |
192 | To run the various unit tests in the package, run `make test`.
193 |
194 | ## Roadmap
195 |
196 | See the [open issues](https://github.com/agntcy/acp-sdk/issues) for a list of proposed features and known issues.
197 |
198 | ## Client Reference API
199 |
200 | For a detailed description of the classes and functions in the SDK, please see the
201 | [agntcy-acp Package Documentation](https://agntcy.github.io/acp-sdk/index.html)
--------------------------------------------------------------------------------
/docs/pages/syntactic_sdk/hil.md:
--------------------------------------------------------------------------------
1 | # Human in the Loop Agent (Coming soon)
2 |
3 | In many cases, agentic applications require human input.
4 |
5 | Involving the human requires two things:
6 |
7 | * Interrupting a multi-application flow to wait for human input. This is provided by the different frameworks in different ways, but corresponds to pausing the application and resuming it when input is available.
8 | * Engaging with the human to collect the input. This can happen in many ways and each application will have its own preferences.
9 |
10 | The Human in the Loop (HIL) Agent is an agent that implements most common methods to engage with humans.
11 |
12 | Few examples below:
13 |
14 | * Webhook: the agent calls a provided webhook to request for input and receive it through OpenAPI or REST.
15 | * Email engagement: the agent sends an email and offers a web interface to provide input.
16 | * Webex, Slack, or other engagement: the agent uses a messaging paltform to request input.
17 |
--------------------------------------------------------------------------------
/docs/pages/syntactic_sdk/sample_acp_descriptors/mailcomposer.json:
--------------------------------------------------------------------------------
1 | {
2 | "metadata": {
3 | "ref": {
4 | "name": "org.agntcy.mailcomposer",
5 | "version": "0.0.1",
6 | "url": "https://github.com/agntcy/acp-spec/blob/main/docs/sample_acp_descriptors/mailcomposer.json"
7 | },
8 | "description": "This agent is able to collect user intent through a chat interface and compose wonderful emails based on that."
9 | },
10 | "specs": {
11 | "capabilities": {
12 | "threads": true,
13 | "interrupts": true,
14 | "callbacks": true
15 | },
16 | "input": {
17 | "type": "object",
18 | "description": "Agent Input",
19 | "properties": {
20 | "message": {
21 | "type": "string",
22 | "description": "Last message of the chat from the user"
23 | }
24 | }
25 | },
26 | "thread_state": {
27 | "type": "object",
28 | "description": "The state of the agent",
29 | "properties": {
30 | "messages": {
31 | "type": "array",
32 | "description": "Full chat history",
33 | "items": {
34 | "type": "string",
35 | "description": "A message in the chat"
36 | }
37 | }
38 | }
39 | },
40 | "output": {
41 | "type": "object",
42 | "description": "Agent Input",
43 | "properties": {
44 | "message": {
45 | "type": "string",
46 | "description": "Last message of the chat from the user"
47 | }
48 | }
49 | },
50 | "config": {
51 | "type": "object",
52 | "description": "The configuration of the agent",
53 | "properties": {
54 | "style": {
55 | "type": "string",
56 | "enum": ["formal", "friendly"]
57 | }
58 | }
59 | },
60 | "interrupts": [
61 | {
62 | "interrupt_type": "mail_send_approval",
63 | "interrupt_payload": {
64 | "type": "object",
65 | "title": "Mail Approval Payload",
66 | "description": "Description of the email",
67 | "properties": {
68 | "subject": {
69 | "title": "Mail Subject",
70 | "description": "Subject of the email that is about to be sent",
71 | "type": "string"
72 | },
73 | "body": {
74 | "title": "Mail Body",
75 | "description": "Body of the email that is about to be sent",
76 | "type": "string"
77 | },
78 | "recipients": {
79 | "title": "Mail recipients",
80 | "description": "List of recipients of the email",
81 | "type": "array",
82 | "items": {
83 | "type": "string",
84 | "format": "email"
85 | }
86 | }
87 | },
88 | "required": [
89 | "subject",
90 | "body",
91 | "recipients"
92 | ]
93 | },
94 | "resume_payload": {
95 | "type": "object",
96 | "title": "Email Approval Input",
97 | "description": "User Approval for this email",
98 | "properties": {
99 | "reason": {
100 | "title": "Approval Reason",
101 | "description": "Reason to approve or decline",
102 | "type": "string"
103 | },
104 | "approved": {
105 | "title": "Approval Decision",
106 | "description": "True if approved, False if declined",
107 | "type": "boolean"
108 | }
109 | },
110 | "required": [
111 | "approved"
112 | ]
113 | }
114 | }
115 | ]
116 | }
117 | }
118 |
--------------------------------------------------------------------------------
/docs/requirements.txt:
--------------------------------------------------------------------------------
1 | pip-tools==7.4.1 # BSD
2 | sphinx==8.2.3 # BSD
3 | sphinx-rtd-theme==3.0.2 # MIT
4 | sphinx-markdown-tables==0.0.17 # GPLv3
5 | sphinxcontrib.mermaid==1.0.0 # Apache 2.0
6 | recommonmark==0.7.1 # MIT
7 | myst-parser==4.0.1 # MIT
8 | sphinx-inline-tabs==2023.4.21 # MIT
9 | sphinxemoji==0.2.0 # BSD-3-Clause
10 | sphinx-copybutton==0.5.2 # MIT
11 |
--------------------------------------------------------------------------------
/schema/oasf-data-model.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package schema.model;
4 |
5 | // The data model defines a schema for AI agent content representation.
6 | // The schema provides a way to describe agent's features, constraints, artifact
7 | // locators, versioning, ownership, or relevant details.
8 | message Agent {
9 | // Name of the agent.
10 | string name = 1;
11 |
12 | // Version of the agent.
13 | string version = 2;
14 |
15 | // List of agent’s authors in the form of `author-name `.
16 | repeated string authors = 3;
17 |
18 | // Creation timestamp of the agent in the RFC3339 format.
19 | // Specs: https://www.rfc-editor.org/rfc/rfc3339.html
20 | string created_at = 4;
21 |
22 | // Additional metadata associated with this agent.
23 | map annotations = 5;
24 |
25 | // List of skills that this agent is capable of performing.
26 | // Specs: https://schema.oasf.agntcy.org/skills
27 | repeated string skills = 6;
28 |
29 | // Locators provide actual artifact locators of an agent. For example,
30 | // this can reference sources such as helm charts, docker images, binaries, etc.
31 | message Locator {
32 | // Location URI where this source locator can be found.
33 | string url = 1;
34 |
35 | // Type of the source locator, for example: "docker-image", "binary", "source-code".
36 | string type = 2;
37 |
38 | // Metadata associated with this source locator.
39 | map annotations = 3;
40 |
41 | // Size in bytes of the source locator pointed by the `url` property.
42 | optional uint64 size = 4;
43 |
44 | // Digest of the source locator pointed by the `url` property.
45 | optional string digest = 5;
46 | }
47 | // List of source locators where this agent can be found or used from.
48 | repeated Locator locators = 7;
49 |
50 | // Extensions provide dynamic descriptors for an agent. For example,
51 | // security and categorization features can be described using extensions.
52 | message Extension {
53 | // Name of the extension.
54 | string name = 1;
55 |
56 | // Version of the extension.
57 | string version = 2;
58 |
59 | // Metadata associated with this extension.
60 | map annotations = 3;
61 |
62 | // Value of the data, it is available directly
63 | // or can be constructed by fetching from some URL.
64 | bytes specs = 4;
65 | }
66 | // List of extensions that describe this agent more in depth.
67 | repeated Extension extensions = 8;
68 | }
69 |
--------------------------------------------------------------------------------