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.
Agent is the rich object returned by Agents.aget() and AgentsListItem.aload(). It carries the agent’s full stored configuration, plus methods for creating tasks, invoking tools, and managing sessions.
from xpander_sdk import Agents
agent = await Agents().aget("agent-123")
print(agent.name)
print(agent.model_provider, agent.model_name)
print(agent.deployment_type.value) # "serverless" or "container"
print(len(agent.tools.list))
Class methods
Agent.aload(agent_id, configuration=None, version=None) -> Agent
Load an agent by ID. This is what Agents.aget() calls internally. Use the module-level agents.aget(...) in normal code; Agent.aload(...) is for places where you have a Configuration but no Agents instance.
from xpander_sdk import Agent, Configuration
config = Configuration(api_key="...", organization_id="...")
agent = await Agent.aload(agent_id="agent-123", configuration=config)
| Parameter | Type | Required | Default | Description |
|---|
agent_id | str | Yes | – | Agent to load. |
configuration | Configuration | No | None | SDK config. Uses defaults if omitted. |
version | int | No | None | Specific version. Latest if omitted. |
Agent.load(...).
Attributes
| Attribute | Type | Description |
|---|
id | str | Agent identifier. |
organization_id | str | Owning organization. |
name | str | Display name. |
description | str | None | Long description. |
unique_name | str | URL-safe slug. |
icon | str | Emoji or icon. Defaults to "🚀". |
status | AgentStatus | DRAFT, ACTIVE, or INACTIVE. |
version | int | Loaded version. |
created_by | str | None | Creator user id. |
created_at | datetime | None | Creation timestamp. |
access_scope | AgentAccessScope | Personal or Organizational. |
type | AgentType | None | Manager, Regular, A2A, Curl, Orchestration. |
framework | Framework | Always Agno today. Other values reserved. |
deployment_type | AgentDeploymentType | Serverless or Container. |
instructions | AgentInstructions | role: list[str], goal: list[str], general: str. |
graph | AgentGraph | Execution graph (source nodes, tools, sub-agents, MCP). |
tools | ToolsRepository | Repository of attached tools. See Tools Repository. |
knowledge_bases | list[AgentKnowledgeBase] | Linked knowledge bases (id pointers). |
model_provider | str | e.g. "openai", "anthropic", "bedrock". |
model_name | str | e.g. "gpt-4o", "claude-sonnet-4". |
llm_reasoning_effort | LLMReasoningEffort | Low, Medium, or High. |
llm_api_base | str | None | Override for the LLM endpoint (Bedrock / Azure / Ollama). |
llm_extra_headers | dict[str, str] | Extra headers for LLM calls. |
output_format | OutputFormat | Default output format. |
output_schema | dict | None | Default JSON schema (used when output_format == Json). |
expected_output | str | Description of the expected output. |
agno_settings | AgnoSettings | Memory, tool-call limits, guardrails, reasoning settings. |
webhook_url | str | None | Configured webhook for completed tasks. |
connectivity_details | AIAgentConnectivityDetailsA2A | AIAgentConnectivityDetailsCurl | dict | Wire details for A2A and Curl agent types. |
voice_id | str | None | Voice ID for OutputFormat.Voice. |
task_level_strategies | TaskLevelStrategies | None | Retry / iterative / stop strategies and per-day caps. |
orchestration_nodes | list[OrchestrationNode] | Sub-nodes for orchestration agents. |
notification_settings | NotificationSettings | Alerting config. |
use_oidc_pre_auth | bool | Whether the agent uses OIDC pre-auth tokens. |
pre_auth_audiences | list[str] | OIDC audiences for pre-auth. |
using_nemo | bool | Whether NeMo is in use. |
deep_planning | bool | Whether deep planning is enabled. |
enforce_deep_planning | bool | Strict plan enforcement. |
llm_credentials | LLMCredentials | None | Per-agent LLM credentials, if overridden. |
Computed properties
| Property | Type | Description |
|---|
mcp_servers | list[MCPServerDetails] | MCP servers configured in the graph. |
output | AgentOutput | Resolved output configuration (Pydantic schema, markdown flag, JSON-mode flag). |
search_knowledge | bool | True when the agent has at least one linked knowledge base. |
is_a_team | bool | True when the agent has sub-agents (Manager / Team mode). |
is_active | bool | agent.status == AgentStatus.ACTIVE. |
sanitized_name | str | name munged to a valid Python identifier. |
strands_tools | list | Strands-formatted tool wrappers. |
openai_agents_sdk_tools | list | OpenAI Agents SDK-formatted tool wrappers. |
Instance methods
| Method | Reference |
|---|
acreate_task / create_task | Create a task |
ainvoke_tool / invoke_tool | Invoke a tool |
aget_knowledge_bases / get_knowledge_bases | Knowledge bases |
attach_knowledge_base | Knowledge bases |
knowledge_bases_retriever | Knowledge bases |
aget_db / get_db | Sessions |
aget_user_sessions / get_user_sessions | Sessions |
aget_session / get_session | Sessions |
adelete_session / delete_session | Sessions |
Streaming spec
agent.aget_streaming_spec() -> StreamingSpecResponse: returns the deployed agent’s streaming URL and an API key for the container’s /invoke endpoint. Useful when you want to bypass the SSE channel and POST directly to a deployed worker.
spec = await agent.aget_streaming_spec()
print(spec.url) # https://<agent>.containers.xpander.ai/invoke
print(spec.api_key) # auth token for the /invoke endpoint
StreamingSpecResponse has two fields: url (str | None) and api_key (str | None). Both can be None if the agent isn’t deployed yet.
Connection string
agent.aget_connection_string() -> DatabaseConnectionString: returns DB connection details for agents using session storage. The result is cached on the instance after the first call.
conn = await agent.aget_connection_string()
print(conn.connection_uri.uri)
DatabaseConnectionString has id, name, organization_id, and connection_uri.uri (a Postgres-compatible URI).
await agent.sync_local_tools(tools=[...]): pushes locally-decorated @register_tool(add_to_graph=True) tools to the platform’s graph. Called automatically when Agent.aload detects unsynced tools, so you rarely need to invoke it directly.
