Resources

The client exposes four resources: agents, workflows, conversations, and calls. Every method returns a typed result, and the list methods return a Page you can both iterate directly and walk page-by-page (see Pagination).

Agents

agents = client.agents.list(page=2, limit=50, search="support", sort="-created_at")
agent = client.agents.create(name="Support bot", description="Tier 1 support", idempotency_key="op-1")
detail = client.agents.retrieve(agent.id)
client.agents.update(agent.id, description="Now tier 2 as well")

list returns a Page[Agent]. create and update take the agent fields as keyword arguments (name, description, system_prompt, language, persona, agent_workflow_id, rules, timezone, logo, the business_* fields, and escalation_email); only name is required on create, and every field is optional on update. create and update return an Agent, while retrieve returns an AgentDetail, which is an Agent plus the agent's integrations, channels, conversation flows, actions, and knowledge bases inlined.

Read-only sub-resources

The read-only sub-resources each return a plain list.

client.agents.integrations.list(agent_id)
client.agents.channels.list(agent_id)
client.agents.conversation_flows.list(agent_id)
client.agents.actions.list(agent_id)

Knowledge bases

Knowledge bases support full CRUD. The create body is a text source or a URL source, distinguished by its type, and is passed as a single dict so the union stays well typed.

client.agents.knowledge_bases.list(agent_id)
client.agents.knowledge_bases.create(agent_id, {"type": "text", "name": "FAQ", "content": "..."})
client.agents.knowledge_bases.create(agent_id, {"type": "url", "name": "Docs", "url": "https://..."})
client.agents.knowledge_bases.update(agent_id, kb_id, description="Updated")
client.agents.knowledge_bases.delete(agent_id, kb_id)

Workflows

workflows = client.workflows.list(scope="public", search="triage", sort="-created_at")
workflow = client.workflows.create(name="Triage", idempotency_key="op-2")
client.workflows.retrieve(workflow.id)
client.workflows.update(workflow.id, tags=["v2"])
client.workflows.delete(workflow.id)

scope is either owned or public. list returns a Page[WorkflowSummary]; retrieve, create, and update return a Workflow, which is the summary plus system_prompt, rules, flows, tags, and prompt_config. As with agents, create and update take the fields as keyword arguments and only name is required on create.

Conversations and messages

conversations = client.conversations.list(agent_id, channel="whatsapp", search="invoice")
conversation = client.conversations.retrieve(agent_id, conversation_id)

messages = client.conversations.messages.list(agent_id, conversation_id)
sent = client.conversations.messages.send(agent_id, conversation_id, message="Hello")

channel accepts whatsapp, messenger, instagram, webchat, and the test_* variants of each. conversations.list returns a Page[Conversation] and messages.list returns a Page[Message]. send takes message and optional attachments (each {"type": ..., "url": ...}) and returns the created Message.

Calls

calls.list() is wired up, but the API answers with 501 today, so it raises APINotImplementedError. The call site will keep working and start returning data once the endpoint ships, without an SDK change.

from bimpeai import APINotImplementedError

try:
    client.calls.list()
except APINotImplementedError:
    ...  # not available yet