Agents

Setup steps and authentication are in the Overview. This page focuses on the agent resource itself.

An agent is the AI voice assistant under test. It links to a provider (Vapi, Retell, ElevenLabs, LiveKit, Pipecat, or a custom integration), a system prompt, mock tools, a knowledge base, and a set of personalities. Most evaluation workflows start by creating or selecting an agent.

Create

# Interactive — prompts for name, provider, credentials, and telephony
cekura agents create --project-id 742

For provider/telephony config, write a JSON file and pass it:

cekura agents create --from-file agent.json

from cekura import Cekura

client = Cekura()

agent = client.agents.create(
    project=742,
    agent_name="Support Bot",
    description="Inbound customer support agent",
    inbound=True,
    assistant_provider="vapi",
    assistant_id="asst_abc123",
    vapi_api_key="...",
)

List, get, update

# List agents in a project
cekura agents list --project-id 742

# Inspect one
cekura agents get 123

# Patch fields inline
cekura agents update 123 --json '{"description": "v2 prompt rolled out"}'

# Or from a file
cekura agents update 123 --from-file patch.json

# List
agents = client.agents.list(project_id=742)

# Fetch one
detail = client.agents.get(agent_id=123)

# Partial update
client.agents.update(
    agent_id=123,
    description="v2 prompt rolled out",
)

replace() performs a full PUT instead of a PATCH — use it when you want to overwrite the entire agent definition.

Mock tools

Mock tools let evaluations run without hitting your real backend.

# List existing tools
cekura agents tools-list 123

# Add a tool
cekura agents tool-create 123 --from-file booking_tool.json

# Update / remove
cekura agents tool-update 123 book_appointment --from-file new.json
cekura agents tool-destroy 123 book_appointment

# List
tools = client.agents.tools_list(123)

# Create
client.agents.tools_create(
    agent_id=123,
    name="book_appointment",
    description="Books an appointment for the caller",
    parameters={"date": "string", "time": "string"},
    mock_response={"confirmation_id": "ABC123"},
)

# Update by tool name
client.agents.tool_update(
    123, tool_name="book_appointment", mock_response={...},
)

# Remove
client.agents.tool_destroy(123, tool_name="book_appointment")

Knowledge base

cekura agents upload-knowledge-base 123 --file ./policies.pdf
cekura agents get-knowledge-base 123

with open("policies.pdf", "rb") as f:
    client.agents.upload_knowledge_base(123, file=f)

kb = client.agents.get_knowledge_base(123)

Personalities

Personalities apply across an agent’s evaluation runs (e.g. “interruptive”, “soft-spoken”).

cekura personalities enable-for-project 742 --personalities 3,29
cekura personalities disable-for-project 742 --personalities 3

client.agents.enable_personalities(123, personalities=[3, 29])
client.agents.disable_personalities(123, personalities=[3])

Duplicate

Quickly fork an agent for A/B testing or a new prompt variant:

cekura agents duplicate 123

client.agents.duplicate(agent_id=123)

Dynamic variables

Dynamic variables let you inject runtime values into an agent’s description using {{ variable_name }} syntax. You define the variables on the agent and supply their values when sending call data to the observability endpoint.

List

GET /test_framework/v1/aiagents/{agent_id}/dynamic-variables/

Returns all variable definitions for the agent, ordered by name. Response

[
  { "id": 1, "name": "prompt", "description": "Full system prompt for this call", "created_at": "...", "updated_at": "..." },
  { "id": 2, "name": "agent_type", "description": "Role of the agent (sales, support, ...)", "created_at": "...", "updated_at": "..." }
]

Create / update

POST /test_framework/v1/aiagents/{agent_id}/dynamic-variables/

Accepts a list of { name, description } objects. Each entry is upserted by name — existing variables are updated, new ones are created. Returns the full list of definitions after the operation.

[
  { "name": "prompt", "description": "Full system prompt override" },
  { "name": "agent_type", "description": "Agent role for this session" }
]

Update one

PATCH /test_framework/v1/aiagents/{agent_id}/dynamic-variable/{id}/

Updates a single variable definition (partial update).

{ "description": "Updated description" }

Delete

DELETE /test_framework/v1/aiagents/{agent_id}/dynamic-variable/{id}/

Returns 204 No Content.

See Dynamic Agent Description for how to use these variables at call time.

Evaluators

Scenarios, test profiles, personalities — the test inputs that run against an agent.

Runs & Results

Trigger an evaluation against the agent and inspect the outcome.

Agents API

Full field reference for agent payloads.

Agent setup guide

Concepts, provider integrations, and best practices.

CLI & SDK

Create

List, get, update

Mock tools

Knowledge base

Personalities

Duplicate

Dynamic variables

List

Create / update

Update one

Delete

See also

Evaluators

Runs & Results

Agents API

Agent setup guide

​Create

​List, get, update

​Mock tools

​Knowledge base

​Personalities

​Duplicate

​Dynamic variables

​List

​Create / update

​Update one

​Delete

​See also

Evaluators

Runs & Results

Agents API

Agent setup guide

Create

List, get, update

Mock tools

Knowledge base

Personalities

Duplicate

Dynamic variables

List

Create / update

Update one

Delete

See also