Skip to main content

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.

Agents.aget loads one agent’s complete configuration: instructions, model settings, the execution graph, all attached tools, knowledge-base links, and framework settings. Use this whenever you need to actually invoke an agent or inspect its config in code. 
from xpander_sdk import Agents

agents = Agents()
agent = await agents.aget("agent-123")
print(agent.name, agent.model_provider, agent.model_name)

​
Parameters

ParameterTypeRequiredDefaultDescription
agent_idstrNo¹Configuration.agent_id → XPANDER_AGENT_IDAgent to load.
versionintNoNoneSpecific version. Latest if omitted.
¹ The method falls back to Configuration.agent_id and then XPANDER_AGENT_ID. If none of those are set, you’ll hit a 404 from the cloud.

​
Returns Agent

A full Agent instance. See Agent class reference for attributes (instructions, framework, graph, deployment_type, tools, knowledge_bases, agno_settings, etc.).

​
Examples

​
Latest version

agent = await agents.aget("agent-123")

​
Pinned version

agent = await agents.aget("agent-123", version=4)
print(agent.version)   # 4
The version corresponds to deployment snapshots in the Workbench. Pin a version in production to avoid surprises when someone edits the agent.

​
Use a default agent ID

export XPANDER_AGENT_ID="agent-123"

agent = await agents.aget()        # uses XPANDER_AGENT_ID
This is the pattern used inside @on_task handlers: you don’t usually pass an agent ID explicitly because the runtime injects it.

​
Sync version

agent = agents.get("agent-123")
Same parameters; blocks until the agent is loaded.

​
What gets loaded

When you call aget, the SDK:
  1. Fetches the agent record (GET /agents/:id).
  2. Builds the AgentGraph from the graph items returned in the response.
  3. Initializes a ToolsRepository populated with the agent’s tools.
  4. If any local tools (Python @register_tool functions) need syncing to the platform’s graph, kicks off a background sync_local_tools task: non-blocking.
You can read agent.graph to inspect the tool/connector wiring, agent.tools.list for all tools, agent.knowledge_bases for KB links, and agent.mcp_servers for the configured MCP servers.

​
Errors

aget raises ModuleException on failure:
StatusCause
404Agent not found, or wrong organization.
403Agent exists but isn’t accessible to your account.
500Server error or network failure.