added adversarial agents documentation - #55
Conversation
eloycoto
left a comment
eloycoto
left a comment
There was a problem hiding this comment.
I have the feeling that the doc cover under the hood, and not what it's going to be useful for someone looking at Adversarial agetnt.
The initial part is good, but at the same time, I might add an example adversarial agent, and the output, as a reference on how to use it instead of see what it's under need.
YES, rules is in similar shape as this, I need to add some examples too.
TBH: I would wear the Ansible administrator member here, and trying to understand what a adversarial agent is, and what is the good practice here.
|
|
||
| # Adversarial Agents | ||
|
|
||
| Adversarial agents are read-only AI reviewers that inspect x2a migration artifacts - analysis plans and generated Ansible - before the output reaches production. They act as an automated peer review layer, catching security gaps, functional mistakes, and correctness problems that the primary migration agents may have missed. |
There was a problem hiding this comment.
I would add read-only as bold.
|
|
||
| Adversarial agents are read-only AI reviewers that inspect x2a migration artifacts - analysis plans and generated Ansible - before the output reaches production. They act as an automated peer review layer, catching security gaps, functional mistakes, and correctness problems that the primary migration agents may have missed. | ||
|
|
||
| Agents are defined in the web platform. Each agent has a name, a prompt describing what to look for, the phases it applies to, and the severity of its findings. |
There was a problem hiding this comment.
Adversarial Agents can be defined by system administrator in the web platform.
|
|
||
| ## How adversarial agents work | ||
|
|
||
| When you trigger an adversarial review from the module page, x2a: |
|
|
||
| When you trigger an adversarial review from the module page, x2a: | ||
|
|
||
| 1. Passes the relevant artifacts from the completed phase to the x2a-convertor `adversarial-run` command. |
There was a problem hiding this comment.
As a system administrator, this first step do not add too much value IMHO
|
|
||
| 1. Passes the relevant artifacts from the completed phase to the x2a-convertor `adversarial-run` command. | ||
| 2. Runs each selected agent sequentially using read-only tools - agents cannot modify any files. | ||
| 3. Produces a markdown report and a structured JSON summary committed back to the target repository. |
There was a problem hiding this comment.
maybe adding a simple path here?
|
|
||
| Agents can also be managed directly through the REST API: | ||
|
|
||
| ### REST API |
There was a problem hiding this comment.
I would not documment the API here, I would link that adversarial agents can be created using the API, and link to the https://x2ansible.github.io/platform/api-reference.html
|
|
||
| **Conflict behavior:** if an adversarial job is already running for the same module and phase, the request returns a `409 Conflict` and the existing job continues uninterrupted. | ||
|
|
||
| ### Adversarial run endpoint |
There was a problem hiding this comment.
not real value for a system-administrator, that it's the guy reading this.
|
|
||
| --- | ||
|
|
||
| ## x2a-convertor CLI |
There was a problem hiding this comment.
Let's delete this, this is part, it's already covered in the x2a-convertor
2 participants
No description provided.