Retrieve Skills and record use

An agent retrieves Skills before a task and puts the applicable Skill text in its prompt. Your application then records which Skill the agent used and the result. This feedback controls the trust value and the search rank of each Skill.

Use the Zep SDKs to search, read, and report outcomes from your application code. To connect an MCP-compatible agent without changes to the agent code, see Use Skills through MCP.

Search for Skills

Search returns only the admitted Skills of one Agent. Candidates, retired Skills, and the Skills of other Agents are not in the results.

results = client.agent.skill.search(
    agent_uuid=agent_uuid,
    query="customer reports a duplicate charge",
    task_family="billing.support",
    limit=3,
)
search_id = results.response.search_id
skills = results.items

Each result has these fields, in addition to the Skill identity, version, and text:

Search ranks results by match to the query, by maturity, and by feedback.

Put a Skill in the prompt

Put the markdown of each applicable Skill in the system prompt or in a tool result. Tell the agent to follow the procedure only when the use_when conditions are true and the do_not_use_when conditions are false. The agent decides if a Skill applies. Zep does not decide.

Record Skill use

A search alone does not record a Skill use. When the agent makes a decision about a search result, record the decision with the search_id of that search and the Trajectory of the current task.

The search_id must come from a search that returned the same Skill version. Otherwise, the API returns 409 Conflict. Each Skill use write needs an Idempotency-Key header with a UUIDv4 value.

use = client.agent.skill.use.create(
    agent_uuid=agent_uuid,
    skill_uuid=skill.uuid_,
    search_id=search_id,
    trajectory_uuid=trajectory_uuid,
    usage="used",
    idempotency_key=str(uuid.uuid4()),
)

Record the outcome

After the task ends, close its Trajectory with an outcome and a verification strength. Then add the outcome to the Skill use. The outcome value is succeeded, failed, partial, abandoned, or unknown. You can also send the outcome in the Skill use request when the result is known at that time.

client.agent.skill.use.add_outcome(
    agent_uuid=agent_uuid,
    skill_uuid=skill.uuid_,
    use_uuid=use.uuid_,
    outcome="succeeded",
    idempotency_key=str(uuid.uuid4()),
)

Zep takes the verification strength of the feedback from the Trajectory of the Skill use. Only outcomes with strong verification change trust and verified_applications. Record failures too. Verified failures decrease the trust value.

Get Agent context

The Agent context endpoint assembles the applicable admitted Skills into one text block for a prompt. Send an objective, or send the trajectory_uuid of the current task. Do not send both. You can also filter by task_family, kind, models, tools, and environments, and limit the size with max_characters (from 1 to 50,000).

context = client.agent.get_context(
    agent_uuid=agent_uuid,
    objective="Resolve a duplicate charge question for invoice 2077",
    task_family="billing.support",
)
prompt_context = context.context

The response contains the context text and a snapshot of the Skill versions in the text. The truncated field is true when max_characters removed content. The context response has no search_id. To record a Skill use, use search.

Use Skills through MCP

The Context MCP Server can give an MCP client the Skills of one Agent. An administrator enables this on the MCP connection of the project:

1. In the Zep Dashboard, open the project’s Settings ▸ MCP page.
2. In Agent Skills, select the Agent.
3. Turn on Allow Agent Skills.
4. To let clients send feedback, turn on Allow Skill outcome feedback.

The connection binds to one Agent. To change the Agent, delete the connection and create it again. Graph scopes do not give access to Skills.

The MCP server has these tools:

Zep checks the access of the user at each call. Results are not cached.