Skip to main content
AgentsClient is reachable on every Kataven client as client.agents. Each method maps to one HTTP endpoint on the Hub API; links to the underlying spec entry are inline below. Manage AI voice/chat agents from Python. Every method on client.agents maps to one HTTP endpoint on the Hub API.

​
Methods at a glance

MethodHTTPSummary
listGET /api/agentsList agents
getGET /api/agents/{agent_id}Get an agent
createPOST /api/agentsCreate an agent
updatePATCH /api/agents/{agent_id}Update an agent
deleteDELETE /api/agents/{agent_id}Delete an agent
list_toolsGET /api/agents/{agent_id}/toolsList tools attached to an agent
upsert_toolPOST /api/agents/{agent_id}/toolsAttach or update a tool on an agent
attach_playbookPOST /api/agents/{agent_id}/playbooksAttach a playbook to an agent
detach_playbookDELETE /api/agents/{agent_id}/playbooks/{playbook_id}Detach a playbook from an agent
attach_faqPOST /api/agents/{agent_id}/faqsAttach an FAQ to an agent
detach_faqDELETE /api/agents/{agent_id}/faqs/{faq_id}Detach an FAQ from an agent

​
Reference

​
client.agents.list(...)

List agents HTTP — GET /api/agents · API reference → 
    def list(self) -> List[Dict[str, Any]]:
Returns every agent in the caller’s account, with attached playbooks and FAQs joined in. Ordered by created_at descending. There is no pagination today — every account has at most a few dozen agents in practice; if that changes we’ll add limit/offset like /api/tools and /api/playbooks.

​
client.agents.get(...)

Get an agent HTTP — GET /api/agents/{id} · API reference → 
    def get(self, agent_id: str) -> Dict[str, Any]:
Returns the agent row plus its attached playbooks and FAQs.

​
client.agents.create(...)

Create an agent HTTP — POST /api/agents · API reference → 
    def create(self, name: str, **kwargs) -> Dict[str, Any]:
Persists a new agent in the caller’s account. Required body fields: name. Most other fields default sensibly: category=custom, status=draft, llm_model=gpt-4o, voice_provider=cartesia, auth_mode=authenticated, greeting_mode=interruptible. Returns the inserted row, including server-set id, created_at, and updated_at. Attach playbooks and FAQs separately via POST /api/agents/{id}/playbooks and POST /api/agents/{id}/faqs.

​
client.agents.update(...)

Update an agent HTTP — PATCH /api/agents/{id} · API reference → 
    def update(self, agent_id: str, **kwargs) -> None:

​
client.agents.delete(...)

Delete an agent HTTP — DELETE /api/agents/{id} · API reference → 
    def delete(self, agent_id: str) -> None:

​
client.agents.list_tools(...)

List tools attached to an agent HTTP — GET /api/agents/{id}/tools · API reference → 
    def list_tools(self, agent_id: str) -> List[Dict[str, Any]]:

​
client.agents.upsert_tool(...)

Attach or update a tool on an agent HTTP — POST /api/agents/{id}/tools · API reference → 
    def upsert_tool(
        self,
        agent_id: str,
        tool_name: str,
        config: Optional[Dict[str, Any]] = None,
        enabled: bool = True,
    ) -> None:
Idempotent insert-or-update of one (agent_id, tool_name) row. Both POST and PUT are accepted.

​
client.agents.attach_playbook(...)

Attach a playbook to an agent HTTP — POST /api/agents/{id}/playbooks · API reference → 
    def attach_playbook(self, agent_id: str, playbook_id: str) -> Dict[str, Any]:

​
client.agents.detach_playbook(...)

Detach a playbook from an agent HTTP — DELETE /api/agents/{id}/playbooks/{playbookId} · API reference → 
    def detach_playbook(self, agent_id: str, playbook_id: str) -> Dict[str, Any]:

​
client.agents.attach_faq(...)

Attach an FAQ to an agent HTTP — POST /api/agents/{id}/faqs · API reference → 
    def attach_faq(self, agent_id: str, faq_id: str) -> Dict[str, Any]:

​
client.agents.detach_faq(...)

Detach an FAQ from an agent HTTP — DELETE /api/agents/{id}/faqs/{faqId} · API reference → 
    def detach_faq(self, agent_id: str, faq_id: str) -> Dict[str, Any]: