Documentation Index
Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Agents module is your gateway to agents stored on the platform. Use it to discover what agents exist, load a specific one, and from there create tasks, invoke tools, attach knowledge bases, and inspect sessions.
from xpander_sdk import Agents
agents = Agents()
all_agents = await agents.alist()
agent = await agents.aget("agent-123")
task = await agent.acreate_task(prompt="Hello!")
Constructor
Agents(configuration: Optional[Configuration] = None)
| Parameter | Type | Default | Description |
|---|
configuration | Configuration | None | SDK configuration. Falls back to env vars. |
Module methods
| Method | Returns | What it does |
|---|
alist / list | list[AgentsListItem] | Summary list of every agent your org can access. |
aget / get | Agent | Load one agent fully (config + graph + tools). |
Agent instance methods
Once you’ve loaded an Agent, use its instance methods for the actual work:
| Method | What it does |
|---|
acreate_task / create_task | Create a new task and run it. |
ainvoke_tool / invoke_tool | Invoke a single tool bound to this agent. |
aget_knowledge_bases / get_knowledge_bases | Load all knowledge bases attached to the agent. |
attach_knowledge_base | Link a knowledge base to the agent (in-memory only). |
knowledge_bases_retriever | Returns a search(query, num_documents) callable for use as a framework retriever. |
aget_db / get_db | Returns the Agno PG client backing the agent’s session storage. |
aget_user_sessions / get_user_sessions | All sessions for a given end-user. |
aget_session / get_session | Load a single session. |
adelete_session / delete_session | Delete a session. |
aget_streaming_spec / get_streaming_spec | Get the deployed agent’s streaming URL + auth key. |
aget_connection_string / get_connection_string | Get the agent’s DB connection details. |
Agent class reference for attribute documentation.
Quick patterns
Find and load
all_agents = await agents.alist()
for item in all_agents:
print(item.id, item.name, item.status)
agent = await all_agents[0].aload() # AgentsListItem.aload returns the full Agent
# equivalent to: await agents.aget(all_agents[0].id)
Pin to a specific version
agent = await agents.aget("agent-123", version=4)
version, you get the latest.
Default agent via env var
export XPANDER_AGENT_ID="agent-123"
agent = await agents.aget() # uses XPANDER_AGENT_ID
Agents.aget() falls back to Configuration.agent_id and then to XPANDER_AGENT_ID.
