Agent class - xpander.ai

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.

The sync sibling is 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).

sync_local_tools

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.

​Class methods

​Agent.aload(agent_id, configuration=None, version=None) -> Agent

​Attributes

​Computed properties

​Instance methods

​Streaming spec

​Connection string

​sync_local_tools