Skip to content

Commit 353b85e

Browse files
aduminucjubarbot-cisco
aduminuc
and
jubarbot-cisco
authored
Aduminuc docs (#56)
* docs: fixes in intro and agent manifest * docs: fixes * Update docs/pages/agws/manifest.md Co-authored-by: Julien Barbot <[email protected]> --------- Co-authored-by: Julien Barbot <[email protected]>
1 parent fbb70ec commit 353b85e

File tree

2 files changed

+199
-52
lines changed

2 files changed

+199
-52
lines changed

‎docs/pages/agws/manifest.md

+196-49
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@ An Agent Manifest is a document that describes in detail the following:
1010

1111
The manifest is designed to be used by [Agent Connect Protocol](connect.md) and the Workflow Server and stored in the Agent Directory with the corresponding OASF extensions.
1212

13-
This document describes the principles of the Agent Manifest definition.
13+
This document describes the principles of the Agent Manifest definition. Manifest definition can be found [here](https://github.com/agntcy/workflow-srv-mgr/blob/main/wfsm/spec/manifest.yaml)
14+
15+
Sample manifests can be found [here](https://github.com/agntcy/workflow-srv-mgr/tree/main/wfsm/spec/examples).
1416

1517
## Agent Manifest Structure
1618

@@ -29,6 +31,29 @@ Agent Manifest must include a natural language description that describes what t
2931

3032
Agent Manifest can include metadata that provides additional information about the agent, such as ownership, timestamps, tags, and so on.
3133

34+
35+
<details>
36+
<summary>Sample descriptor metadata section for the mailcomposer agent</summary>
37+
38+
```json
39+
{
40+
"metadata": {
41+
"ref": {
42+
"name": "org.agntcy.mailcomposer",
43+
"version": "0.0.1",
44+
"url": "https://github.com/agntcy/acp-spec/blob/main/docs/sample_acp_descriptors/mailcomposer.json"
45+
},
46+
"description": "This agent is able to collect user intent through a chat interface and compose wonderful emails based on that."
47+
}
48+
...
49+
}
50+
```
51+
52+
Metadata for a mail composer agent named `org.agntcy.mailcomposer` version `0.0.1`.
53+
54+
</details>
55+
56+
3257
<a id="agent-interface-data-structure-specification"></a>
3358
### Agent Interface Data Structure Specification
3459
Agents willing to interoperate with other agents expose an interface that allow for invocation and configuration.
@@ -37,34 +62,192 @@ Agent Connect Protocol specifies a standard for this interface. However, it spec
3762

3863
The specification of these data structures is included in what we call the Agent ACP descriptor, which can be provided by ACP itself, but it is also defined as part of the Agent Manifest.
3964

40-
Agent ACP descriptor must include an interface data structure specification section that provides schema definitions for the following data structures:
41-
* **Configuration**: The data structure used to provide agent configuration.
42-
* **Input**: The data structures used to provide agent input.
43-
* **Output**: The data structure used to retrieve agent output.
65+
Agent `specs` section includes ACP invocation capabilities, e.g. `streaming`, `callbacks`, `interrupts` etc., and the JSON schema definitions for ACP interactions:
66+
* Agent Configuration.
67+
* Run Input.
68+
* Run Output.
69+
* Interrupt and Resume Payloads.
70+
* Thread State.
71+
72+
<details>
73+
<summary>Sample specs section for the mailcomposer agent</summary>
74+
75+
```json
76+
{
77+
...
78+
"specs": {
79+
"capabilities": {
80+
"threads": true,
81+
"interrupts": true,
82+
"callbacks": true
83+
},
84+
"input": {
85+
"type": "object",
86+
"description": "Agent Input",
87+
"properties": {
88+
"message": {
89+
"type": "string",
90+
"description": "Last message of the chat from the user"
91+
}
92+
}
93+
},
94+
"thread_state": {
95+
"type": "object",
96+
"description": "The state of the agent",
97+
"properties": {
98+
"messages": {
99+
"type": "array",
100+
"description": "Full chat history",
101+
"items": {
102+
"type": "string",
103+
"description": "A message in the chat"
104+
}
105+
}
106+
}
107+
},
108+
"output": {
109+
"type": "object",
110+
"description": "Agent Input",
111+
"properties": {
112+
"message": {
113+
"type": "string",
114+
"description": "Last message of the chat from the user"
115+
}
116+
}
117+
},
118+
"config": {
119+
"type": "object",
120+
"description": "The configuration of the agent",
121+
"properties": {
122+
"style": {
123+
"type": "string",
124+
"enum": ["formal", "friendly"]
125+
}
126+
}
127+
},
128+
"interrupts": [
129+
{
130+
"interrupt_type": "mail_send_approval",
131+
"interrupt_payload": {
132+
"type": "object",
133+
"title": "Mail Approval Payload",
134+
"description": "Description of the email",
135+
"properties": {
136+
"subject": {
137+
"title": "Mail Subject",
138+
"description": "Subject of the email that is about to be sent",
139+
"type": "string"
140+
},
141+
"body": {
142+
"title": "Mail Body",
143+
"description": "Body of the email that is about to be sent",
144+
"type": "string"
145+
},
146+
"recipients": {
147+
"title": "Mail recipients",
148+
"description": "List of recipients of the email",
149+
"type": "array",
150+
"items": {
151+
"type": "string",
152+
"format": "email"
153+
}
154+
}
155+
},
156+
"required": [
157+
"subject",
158+
"body",
159+
"recipients"
160+
]
161+
},
162+
"resume_payload": {
163+
"type": "object",
164+
"title": "Email Approval Input",
165+
"description": "User Approval for this email",
166+
"properties": {
167+
"reason": {
168+
"title": "Approval Reason",
169+
"description": "Reason to approve or decline",
170+
"type": "string"
171+
},
172+
"approved": {
173+
"title": "Approval Decision",
174+
"description": "True if approved, False if declined",
175+
"type": "boolean"
176+
}
177+
},
178+
"required": [
179+
"approved"
180+
]
181+
}
182+
}
183+
]
184+
}
185+
...
186+
}
187+
```
188+
The agent supports threads, interrupts, and callback.
189+
190+
It declares schemas for input, output, and config:
191+
* As input, it expects the next message of the chat from the user.
192+
* As output, it produces the next message of the chat from the agent.
193+
* As config it expects the style of the email to be written.
44194

45-
If an agent supports interrupts, meaning its execution can be interrupted to request additional input and then resumed, the Agent Manifest needs to define the types of interrupts that can possibly occur.
195+
It supports one kind of interrupt, which is used to ask user for approval before sending the email. It provides subject, body, and recipients of the email as interrupt payload and expects approval as input to resume.
46196

47-
For each of the interrupts it must define the following:
48-
* **Interrupt Output**: The format of the output provided by the specific interrupt.
49-
* **Resume Input**: The input expected by the agent to resume its execution when this specific interrupt occurs.
197+
It supports a thread state which holds the chat history.
50198

51-
All schema definitions must include natural language description of the data structure, natural language description of each data structure element, and valid examples of correctly populated data structures.
199+
</details>
52200

53201
<a id="agent-deployment-and-consumption"></a>
54202
### Agent Deployment and Consumption
55203

56-
Agents can be provided in two different forms, which we call deployment modes:
204+
Agents can be provided in two different forms, which we call deployment options:
57205

58206
* **As a service**: a network endpoint that exposes an interface to the agent (for example, Agent Connect Protocol).
59207
* **As a deployable artifact**, for example:
60208
* A docker image, which once deployed exposes an interface to the agent (for example, Agent Connect Protocol).
61209
* A source code bundle, which can be executed within the specific runtime and framework it is built on.
62210

63-
The same agent can support one or more deployment modes.
211+
The same agent can support one or more deployment options.
212+
213+
Agent Manifest currently supports three deployment otions:
214+
* Source Code Deployment: In this case the agent can be deployed starting from its code. For this deployment mode, the manifest provides:
215+
* The location where the code is available
216+
* The framework used for this agent
217+
* The framework specific configuration needed to run the agent.
218+
* Remote Service Deployment: In this case, the agent does not come as a deployable artefact, but it's already deployed and available as a service. For this deployment mode, the manifest provides:
219+
* The network endpoint where the agent is available through the ACP
220+
* The authentication used by ACP for this agent
221+
* Docker Deployment: In this case the agent can be deployed starting from a docker image. It is assumed that once running the docker container expose the agent through ACP. For this deployment mode, the manifest provides:
222+
* The agent container image
223+
* The authentication used by ACP for this agent
64224

65-
The Agent Manifest must include a list of all the possible deployment modes supported by the agent. For each mode, it needs to provide all the information needed to consume the agent service or to deploy and then consume it, including authentication details when applicable.
225+
<details>
226+
<summary>Sample manifest dependency section for the mailcomposer agent</summary>
227+
228+
```json
229+
{
230+
...
231+
"deployments": [
232+
{
233+
"type": "source_code",
234+
"name": "src",
235+
"url": "[email protected]:agntcy/mailcomposer.git",
236+
"framework_config": {
237+
"framework_type": "langgraph",
238+
"graph": "mailcomposer"
239+
}
240+
}
241+
]
242+
...
243+
}
244+
```
245+
246+
Mailcomposer agent in the example above comes as code written for LangGraph and available on Github.
66247

67248
<a id="agent-dependencies"></a>
249+
</details>
250+
68251
### Agent Dependencies
69252

70253
An agent may depend on other agents, which means that at some point of its execution it needs to invoke them to accomplish its tasks. We refer to these other agents as **sub-agents**. A user who wants to use the agent, needs to know this information and check that the dependencies are satisfied, that is, make sure that the sub-agents are available.
@@ -99,41 +282,5 @@ Mailcomposer agent in the example above depends on `sample-agent-2` and `sample-
99282
</details>
100283

101284
<a id="agent-deployments"></a>
102-
### Agent Deployments
103-
Agent Deployments section lists all the possible ways the agent can be consumed, which we call deployment modes.
104285

105-
Agent Manifest currently supports three deployment modes:
106-
* Source Code Deployment: In this case the agent can be deployed starting from its code. For this deployment mode, the manifest provides:
107-
* The location where the code is available
108-
* The framework used for this agent
109-
* The framework specific configuration needed to run the agent.
110-
* Remote Service Deployment: In this case, the agent does not come as a deployable artefact, but it's already deployed and available as a service. For this deployment mode, the manifest provides:
111-
* The network endpoint where the agent is available through the ACP
112-
* The authentication used by ACP for this agent
113-
* Docker Deployment: In this case the agent can be deployed starting from a docker image. It is assumed that once running the docker container expose the agent through ACP. For this deployment mode, the manifest provides:
114-
* The agent container image
115-
* The authentication used by ACP for this agent
116-
117-
<details>
118-
<summary>Sample manifest dependency section for the mailcomposer agent</summary>
119-
120-
```json
121-
{
122-
...
123-
"deployments": [
124-
{
125-
"type": "source_code",
126-
"name": "src",
127-
"url": "[email protected]:agntcy/mailcomposer.git",
128-
"framework_config": {
129-
"framework_type": "langgraph",
130-
"graph": "mailcomposer"
131-
}
132-
}
133-
]
134-
...
135-
}
136-
```
137-
138-
Mailcomposer agent in the example above comes as code written for LangGraph and available on Github.
139286

‎docs/pages/introduction.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Based on advanced protocols, frameworks, and components, the goal of IoA softwar
2929

3030
### Core Components
3131

32-
The initial set of IoA components and architecture is outlined below. As a very first step, we are sharing two important specifications: OASF and ACP. In a few weeks the collective will release code and documentation for most of the components. This is a starting point - as new members join and bring their contributions, the collective will continue to evolve and expand the IoA architecture, components, and interfaces.
32+
The initial set of IoA components and architecture is outlined below. This is a starting point - as new members join and bring their contributions, the collective will continue to evolve and expand the IoA architecture, components, and interfaces.
3333

3434
```{image} ../_static/ioa_stack.png
3535
:alt: Simplified Internet of Agent Stack
@@ -43,11 +43,11 @@ The initial set of IoA components and architecture is outlined below. As a very
4343
1. **Agent Manifest**: A standard format to describes agents, their capabilities, their dependencies, and how to deploy or consume them. The manifest is designed to be used by ACP and the Workflow Server and stored in the Agent Directory with the corresponding OASF extensions.
4444
1. **Semantic SDK**:
4545
* **I/O Mapper Agent**: Handles semantic data adaptations between agents that need to communicate with each other.
46-
* **Semantic Router**: Directs workflows via semantic matches.
46+
* **Semantic Router**: Directs workflows via semantic matches. (coming soon)
4747
1. **Syntactic SDK**:
4848
* **Agent Connect Protocol (ACP)**: A standard interface to invoke agents (or agentic applications), provide input, retrieve output, retrieve supported schemas, graph topology and other useful information. Current ACP spec can be found [here](https://spec.acp.agntcy.org/).
4949
* **API-bridge Agent** to connect an Agent with any API end-point (tools or data sources)
50-
* **Human in the Loop Agent** to interface with human input/output seamlessly.
50+
* **Human in the Loop Agent** to interface with human input/output seamlessly. (coming soon)
5151
1. **Messaging SDK**:
5252
* **Agent Gateway Protocol (AGP)**: A protocol that defines the standards and guidelines for secure and efficient network-level communication between AI agents. AGP ensures interoperability and seamless data exchange by specifying message formats, transport mechanisms, and interaction patterns.
5353
* **Agent Gateway**: Offers handy secure (MLS and quantum safe) network-level communication services to a group of agents (typically those of a given multi-agent application) through SDK/Libraries. It extends gRPC to support  pub/sub interactions in addition to request/reply, streaming, fire & forget and more.

0 commit comments

Comments
 (0)