Plan an Agent split

POST

https://api.getzep.com/api/v4/agents/:agent_uuid/split-plan

POST

/api/v4/agents/:agent_uuid/split-plan

from zep_cloud import Zep, AgentSplitPlanDestinationRequest, CreateAgentRequest, AgentSplitPlanSkillSelectionRequest
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.agent.split.plan(
    agent_uuid="agent_uuid",
    destinations=[
        AgentSplitPlanDestinationRequest(
            agent=CreateAgentRequest(
                agent_id="payments-agent",
                name="Refund a duplicate charge",
                security_domain="customer:support",
            ),
            skills=[
                AgentSplitPlanSkillSelectionRequest(
                    skill_uuid="6a906e70-50ca-4e43-a874-5fcae02a71fa",
                    skill_version_uuid="6a906e70-50ca-4e43-a874-5fcae02a71fa",
                    version=1,
                )
            ],
        )
    ],
    expected_revision=1,
    rationale="Keep payment refunds separate from charge disputes.",
    review_acknowledged=True,
)

{
  "authorizes_agent_creation": false,
  "authorizes_publication": false,
  "creates_resources": false,
  "destinations": [
    {
      "agent": {
        "agent_id": "payments-agent",
        "name": "Refund a duplicate charge",
        "security_domain": "customer:support",
        "deployment_id": "production",
        "description": "Refund a duplicate charge after you confirm the duplicate payment.",
        "memory_settings": {
          "admission_evaluation_requirements": [
            {
              "requirements": [
                {
                  "evaluated_by": "customer",
                  "evaluator_version": "v1.0.0",
                  "result": "succeeded",
                  "controlled": false,
                  "environment": "production"
                }
              ],
              "task_family": "support/refund"
            }
          ],
          "approval": "auto",
          "approval_minimum_attempt_families": 1,
          "approval_required_tools": [
            "refund_order"
          ],
          "auto_approval_task_families": [
            "support/refund"
          ],
          "compilation_mode": "scheduled",
          "provisional_expiry_days": 1,
          "provisional_skill_limit": 1,
          "retention_days": 30
        },
        "metadata": {},
        "version": "2026.09.01"
      },
      "skills": [
        {
          "package_name": "payments",
          "skill_id": "refund-duplicate-charge",
          "skill_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
          "skill_version_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
          "status": "active",
          "version": 1
        }
      ]
    }
  ],
  "rationale": "Keep payment refunds separate from charge disputes.",
  "review_acknowledged": true,
  "source": {
    "agent_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "revision": 1
  }
}

Plan an Agent split. 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

Source Agent UUID

Request

Reviewed split proposal

destinationslist of objectsRequired

The developer lists 1 to 100 destination Agents.

expected_revisionintegerRequired>=1

The developer supplies the current revision used for optimistic concurrency. At least 1.

rationalestringRequired<=2000 characters

The developer explains the requested change. The limit is 2,000 characters.

review_acknowledgedbooleanRequired

The developer sets this to true to confirm that the review is complete.

Response

authorizes_agent_creationbooleanOptional

The service reports whether the plan authorizes Agent creation.

authorizes_publicationbooleanOptional

The service reports whether the plan authorizes Skill publication.

creates_resourcesbooleanOptional

A split plan is not human approval and grants no authority for later commands.

destinationslist of objectsOptional

The service returns UUIDs of the destination Agents.

rationalestringOptional

The service returns the reason for the requested split.

review_acknowledgedbooleanOptional

The service reports whether the developer confirmed the review.

sourceobjectOptional

The service returns the source Agent and the revision used for this plan.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error