Python SDK — agents

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

Method	HTTP	Summary
`list`	`GET /api/agents`	List agents
`get`	`GET /api/agents/{agent_id}`	Get an agent
`create`	`POST /api/agents`	Create an agent
`update`	`PATCH /api/agents/{agent_id}`	Update an agent
`delete`	`DELETE /api/agents/{agent_id}`	Delete an agent
`list_tools`	`GET /api/agents/{agent_id}/tools`	List tools attached to an agent
`upsert_tool`	`POST /api/agents/{agent_id}/tools`	Attach or update a tool on an agent
`attach_playbook`	`POST /api/agents/{agent_id}/playbooks`	Attach a playbook to an agent
`detach_playbook`	`DELETE /api/agents/{agent_id}/playbooks/{playbook_id}`	Detach a playbook from an agent
`attach_faq`	`POST /api/agents/{agent_id}/faqs`	Attach an FAQ to an agent
`detach_faq`	`DELETE /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]:

Get started

Resource reference

Python SDK — agents

Methods at a glance

Reference

`client.agents.list(...)`

`client.agents.get(...)`

`client.agents.create(...)`

`client.agents.update(...)`

`client.agents.delete(...)`

`client.agents.list_tools(...)`

`client.agents.upsert_tool(...)`

`client.agents.attach_playbook(...)`

`client.agents.detach_playbook(...)`

`client.agents.attach_faq(...)`

`client.agents.detach_faq(...)`

​Methods at a glance

​Reference

​client.agents.list(...)

​client.agents.get(...)

​client.agents.create(...)

​client.agents.update(...)

​client.agents.delete(...)

​client.agents.list_tools(...)

​client.agents.upsert_tool(...)

​client.agents.attach_playbook(...)

​client.agents.detach_playbook(...)

​client.agents.attach_faq(...)

​client.agents.detach_faq(...)

Methods at a glance

Reference

`client.agents.list(...)`

`client.agents.get(...)`

`client.agents.create(...)`

`client.agents.update(...)`

`client.agents.delete(...)`

`client.agents.list_tools(...)`

`client.agents.upsert_tool(...)`

`client.agents.attach_playbook(...)`

`client.agents.detach_playbook(...)`

`client.agents.attach_faq(...)`

`client.agents.detach_faq(...)`