Skip to main content
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)
ParameterTypeDefaultDescription
configurationConfigurationNoneSDK configuration. Falls back to env vars.

​
Module methods

MethodReturnsWhat it does
alist / listlist[AgentsListItem]Summary list of every agent your org can access.
aget / getAgentLoad one agent fully (config + graph + tools).

​
Agent instance methods

Once you’ve loaded an Agent, use its instance methods for the actual work:
MethodWhat it does
acreate_task / create_taskCreate a new task and run it.
ainvoke_tool / invoke_toolInvoke a single tool bound to this agent.
aget_knowledge_bases / get_knowledge_basesLoad all knowledge bases attached to the agent.
attach_knowledge_baseLink a knowledge base to the agent (in-memory only).
knowledge_bases_retrieverReturns a search(query, num_documents) callable for use as a framework retriever.
aget_db / get_dbReturns the Agno PG client backing the agent’s session storage.
aget_user_sessions / get_user_sessionsAll sessions for a given end-user.
aget_session / get_sessionLoad a single session.
adelete_session / delete_sessionDelete a session.
aget_streaming_spec / get_streaming_specGet the deployed agent’s streaming URL + auth key.
aget_connection_string / get_connection_stringGet the agent’s DB connection details.
See the 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)
Versioning is opt-in. Without version, you get the latest.

​
Default agent via env var

export XPANDER_AGENT_ID="agent-123"

agent = await agents.aget()   # uses XPANDER_AGENT_ID
This works because Agents.aget() falls back to Configuration.agent_id and then to XPANDER_AGENT_ID.