Compare Agent Skill Versions

POST

https://api.getzep.com/api/v4/agents/:agent_uuid/skills/:skill_uuid/versions/compare

POST

/api/v4/agents/:agent_uuid/skills/:skill_uuid/versions/compare

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.agent.skill.version.compare(
    agent_uuid="agent_uuid",
    skill_uuid="skill_uuid",
    from_version=1,
    to_version=1,
)

{
  "changed_fields": [
    "name"
  ],
  "from": {
    "contract": {
      "aliases": [
        "duplicate-refund"
      ],
      "applicability": {
        "agent_versions": [
          "2026.09.01"
        ],
        "citations": [
          "event-001"
        ],
        "models": [
          {
            "name": "support-agent-prod",
            "version_constraint": "^1.0.0"
          }
        ]
      },
      "citations": [
        "event-001"
      ],
      "confidence": 0.5,
      "contraindications": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "customer_sections": [
        {
          "heading": "Verify the duplicate charge",
          "markdown": "Confirm the duplicate charge before issuing a refund.",
          "schema_version": "v1",
          "section_id": "refund_workflow"
        }
      ],
      "dependencies": [
        {
          "package_name": "payments",
          "version_constraint": "^1.0.0"
        }
      ],
      "description": "Refund a duplicate charge after you confirm the duplicate payment.",
      "environments": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "citations": [
            "event-001"
          ],
          "name": "refund_payment",
          "version_constraint": "^1.0.0"
        }
      ],
      "evidence": [
        {
          "attempt_family_id": "c58dd7b4-bd8a-41ed-a8be-e32dc6a7c0e3",
          "id": "evidence-1",
          "polarity": "supporting",
          "source_id": "fe2f7bc1-0a8f-4834-98a2-715c8d2b56bc",
          "source_kind": "trace",
          "trace_id": "6a906e70-50ca-4e43-a874-5fcae02a71fa"
        }
      ],
      "failures": [
        {
          "condition": {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          },
          "recovery": [
            {
              "citations": [
                "event-001"
              ],
              "text": "The duplicate charge was refunded."
            }
          ]
        }
      ],
      "invocation": {
        "conditions": [
          {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          }
        ],
        "summary": {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      },
      "kind": "principle",
      "name": "refund_payment",
      "origin": "evidence_derived",
      "outputs": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "package_name": "payments",
      "preconditions": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "procedure": [
        {
          "decision": {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          },
          "expected_observations": [
            {
              "citations": [
                "event-001"
              ],
              "text": "The duplicate charge was refunded."
            }
          ],
          "instruction": {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          }
        }
      ],
      "relations": [
        {
          "citations": [
            "event-001"
          ],
          "kind": "composes",
          "target_package_name": "refund-guidance",
          "version_constraint": "^1.0.0"
        }
      ],
      "schema_version": "v1",
      "success_criteria": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "task_family": "support/refund",
      "termination_conditions": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "tools": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "citations": [
            "event-001"
          ],
          "name": "refund_payment",
          "version_constraint": "^1.0.0"
        }
      ]
    },
    "created_at": "2026-01-01T00:00:00Z",
    "definition": {
      "agent_versions": [
        "2026.09.01"
      ],
      "aliases": [
        "duplicate-refund"
      ],
      "description": "Refund a duplicate charge after you confirm the duplicate payment.",
      "do_not_use_when": [
        "The payment has not settled."
      ],
      "done_when": [
        "support/refund"
      ],
      "environments": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "name": "Refund a duplicate charge",
          "version": "2026.09.01"
        }
      ],
      "failures": [
        {
          "recover": [
            "Retry the refund after the payment service recovers."
          ],
          "when": "A duplicate charge is confirmed."
        }
      ],
      "kind": "principle",
      "name": "Refund a duplicate charge",
      "outputs": [
        "support/refund"
      ],
      "package_name": "payments",
      "preconditions": [
        "support/refund"
      ],
      "procedure": [
        {
          "decision": "If the payment is settled.",
          "expect": [
            "A refund is confirmed."
          ],
          "instruction": "Confirm that the payment was processed twice."
        }
      ],
      "related_skills": [
        {
          "relation": "depends_on",
          "skill": "refund-duplicate-charge",
          "version": "2026.09.01"
        }
      ],
      "sections": [
        {
          "heading": "Verify the duplicate charge",
          "id": "refund-workflow",
          "markdown": "Confirm the duplicate charge before issuing a refund."
        }
      ],
      "stop_when": [
        "Stop if the duplicate charge cannot be confirmed."
      ],
      "task_family": "support/refund",
      "tools": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "name": "Refund a duplicate charge",
          "version": "2026.09.01"
        }
      ],
      "use_when": [
        "A customer reports a duplicate charge."
      ]
    },
    "markdown": "Confirm the duplicate charge before issuing a refund.",
    "self_contained": false,
    "version": 1
  },
  "to": {
    "contract": {
      "aliases": [
        "duplicate-refund"
      ],
      "applicability": {
        "agent_versions": [
          "2026.09.01"
        ],
        "citations": [
          "event-001"
        ],
        "models": [
          {
            "name": "support-agent-prod",
            "version_constraint": "^1.0.0"
          }
        ]
      },
      "citations": [
        "event-001"
      ],
      "confidence": 0.5,
      "contraindications": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "customer_sections": [
        {
          "heading": "Verify the duplicate charge",
          "markdown": "Confirm the duplicate charge before issuing a refund.",
          "schema_version": "v1",
          "section_id": "refund_workflow"
        }
      ],
      "dependencies": [
        {
          "package_name": "payments",
          "version_constraint": "^1.0.0"
        }
      ],
      "description": "Refund a duplicate charge after you confirm the duplicate payment.",
      "environments": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "citations": [
            "event-001"
          ],
          "name": "refund_payment",
          "version_constraint": "^1.0.0"
        }
      ],
      "evidence": [
        {
          "attempt_family_id": "c58dd7b4-bd8a-41ed-a8be-e32dc6a7c0e3",
          "id": "evidence-1",
          "polarity": "supporting",
          "source_id": "fe2f7bc1-0a8f-4834-98a2-715c8d2b56bc",
          "source_kind": "trace",
          "trace_id": "6a906e70-50ca-4e43-a874-5fcae02a71fa"
        }
      ],
      "failures": [
        {
          "condition": {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          },
          "recovery": [
            {
              "citations": [
                "event-001"
              ],
              "text": "The duplicate charge was refunded."
            }
          ]
        }
      ],
      "invocation": {
        "conditions": [
          {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          }
        ],
        "summary": {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      },
      "kind": "principle",
      "name": "refund_payment",
      "origin": "evidence_derived",
      "outputs": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "package_name": "payments",
      "preconditions": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "procedure": [
        {
          "decision": {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          },
          "expected_observations": [
            {
              "citations": [
                "event-001"
              ],
              "text": "The duplicate charge was refunded."
            }
          ],
          "instruction": {
            "citations": [
              "event-001"
            ],
            "text": "The duplicate charge was refunded."
          }
        }
      ],
      "relations": [
        {
          "citations": [
            "event-001"
          ],
          "kind": "composes",
          "target_package_name": "refund-guidance",
          "version_constraint": "^1.0.0"
        }
      ],
      "schema_version": "v1",
      "success_criteria": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "task_family": "support/refund",
      "termination_conditions": [
        {
          "citations": [
            "event-001"
          ],
          "text": "The duplicate charge was refunded."
        }
      ],
      "tools": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "citations": [
            "event-001"
          ],
          "name": "refund_payment",
          "version_constraint": "^1.0.0"
        }
      ]
    },
    "created_at": "2026-01-01T00:00:00Z",
    "definition": {
      "agent_versions": [
        "2026.09.01"
      ],
      "aliases": [
        "duplicate-refund"
      ],
      "description": "Refund a duplicate charge after you confirm the duplicate payment.",
      "do_not_use_when": [
        "The payment has not settled."
      ],
      "done_when": [
        "support/refund"
      ],
      "environments": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "name": "Refund a duplicate charge",
          "version": "2026.09.01"
        }
      ],
      "failures": [
        {
          "recover": [
            "Retry the refund after the payment service recovers."
          ],
          "when": "A duplicate charge is confirmed."
        }
      ],
      "kind": "principle",
      "name": "Refund a duplicate charge",
      "outputs": [
        "support/refund"
      ],
      "package_name": "payments",
      "preconditions": [
        "support/refund"
      ],
      "procedure": [
        {
          "decision": "If the payment is settled.",
          "expect": [
            "A refund is confirmed."
          ],
          "instruction": "Confirm that the payment was processed twice."
        }
      ],
      "related_skills": [
        {
          "relation": "depends_on",
          "skill": "refund-duplicate-charge",
          "version": "2026.09.01"
        }
      ],
      "sections": [
        {
          "heading": "Verify the duplicate charge",
          "id": "refund-workflow",
          "markdown": "Confirm the duplicate charge before issuing a refund."
        }
      ],
      "stop_when": [
        "Stop if the duplicate charge cannot be confirmed."
      ],
      "task_family": "support/refund",
      "tools": [
        {
          "aliases": [
            "duplicate-refund"
          ],
          "name": "Refund a duplicate charge",
          "version": "2026.09.01"
        }
      ],
      "use_when": [
        "A customer reports a duplicate charge."
      ]
    },
    "markdown": "Confirm the duplicate charge before issuing a refund.",
    "self_contained": false,
    "version": 1
  }
}

Compare Agent Skill Versions. Agent Skills is in closed release. Zep enables Agent Skills only for select accounts. A request from an account without access returns 403 permission_denied. To get access, contact support@getzep.com.

Authentication

AuthorizationApi-Key

Type “Api-Key” followed by a space and the project API key.

Path parameters

agent_uuidstringRequired

Agent UUID

skill_uuidstringRequired

Skill UUID, or the 8-character short_id

Request

Versions to compare

from_versionintegerRequired>=1

The developer supplies the source version to compare. It must be at least 1.

to_versionintegerRequired>=1

The developer supplies the destination version to compare. It must be at least 1.

Response

changed_fieldslist of stringsOptional

The service lists fields that changed between these Skill versions.

fromobjectOptional

The service returns the Skill version before the comparison.

toobjectOptional

The service returns the Skill version after the comparison.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

503

Service Unavailable Error