Create Agent Skill Use

POST

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

POST

/api/v4/agents/:agent_uuid/skills/:skill_uuid/uses

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.agent.skill.use.create(
    agent_uuid="agent_uuid",
    skill_uuid="skill_uuid",
    search_id="eyJ2IjoxLCJyZXF1ZXN0X2lkIjoiNmE5MDZlNzAtNTBjYS00ZTQzLWE4NzQtNWZjYWUwMmE3MWZhIn0.signature",
    trace_uuid="6a906e70-50ca-4e43-a874-5fcae02a71fa",
    usage="selected",
)

{
  "agent_version": "2026.09.01",
  "created_at": "2026-01-01T00:00:00Z",
  "outcome": {
    "assertion_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "created_at": "2026-01-01T00:00:00Z",
    "outcome": "succeeded",
    "trace_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "use_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "verification": "customer"
  },
  "reason_code": "evidence_insufficient",
  "skill_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
  "skill_version": 1,
  "trace_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
  "usage": "Used this Skill to refund a duplicate charge.",
  "uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa"
}

Create Agent Skill Use. 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

Skill use

search_idstringRequired

The developer supplies the signed search token returned by Skill search.

trace_uuidstringRequired

The developer supplies the UUID of the source Trace.

usageenumRequired

The developer supplies how the Skill was used. Valid values are selected, used, partially_used, ignored, inapplicable.

Allowed values:

outcomeobjectOptional

The developer records the outcome of the attempt. Valid values are succeeded, failed, partial, abandoned, and unknown.

reason_codestringOptional<=255 characters

The developer supplies a reason code for this outcome. It can contain up to 255 characters.

Response

Created

agent_versionstringOptional

The service returns the Agent version that used this Skill.

created_atstringOptional

The service returns when Zep created this resource.

outcomeobjectOptional

The service returns the task outcome.

reason_codestringOptional

The service returns the code that explains this result.

skill_uuidstringOptional

The service returns the UUID of the Skill.

skill_versionintegerOptional

The service returns the version number of the Skill.

trace_uuidstringOptional

The service returns the UUID of the source Trace.

usagestringOptional

The service returns how the Skill was used.

uuidstringOptional

The service returns the UUID that identifies this resource.

Errors

409

Conflict Error