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.

The Backend module is the bridge between your code and an agent stored in the xpander.ai platform. It does three things:
  1. Resolves runtime arguments for your AI framework: aget_args(agent_id=...) returns kwargs you can spread directly into Agno (or another supported framework’s) agent constructor.
  2. Invokes agents directly: ainvoke_agent(agent_id=..., prompt=...) is shorthand for “load the agent, create a task.” Useful when you don’t need framework-level control.
  3. Reports externally executed runs: areport_external_task(...) lets you log a run that happened outside the platform (e.g. in a queue worker or another runtime) so it shows up in the same task history and metrics as platform-managed runs.
from xpander_sdk import Backend

backend = Backend()

​
Constructor

Backend(configuration: Optional[Configuration] = None)
ParameterTypeDefaultDescription
configurationConfigurationNoneSDK configuration. Falls back to env vars.
When called without arguments, the module reads XPANDER_API_KEY, XPANDER_ORGANIZATION_ID, and XPANDER_BASE_URL from the environment.

​
Methods

MethodWhat it does
ainvoke_agent / invoke_agentLoad an agent and create a task in one call. Returns a Task.
aget_args / get_argsResolve framework-specific kwargs (model, system prompt, tools, memory, …) from a stored agent configuration.
areport_external_task / report_external_taskRecord an external execution (run outside the platform) so it appears in task history.

​
Typical pattern

from xpander_sdk import Backend, on_task
from xpander_sdk.modules.tasks.sub_modules.task import Task
from agno.agent import Agent as AgnoAgent

backend = Backend()

@on_task
async def handler(task: Task) -> Task:
    args = await backend.aget_args(
        agent_id=task.agent_id,
        agent_version=task.agent_version,
        task=task,
    )
    agno_agent = AgnoAgent(**args)
    result = await agno_agent.arun(input=task.to_message())
    task.result = result.content
    return task
@on_task listens for incoming task events from the platform; the handler resolves framework args for the current task, builds an Agno agent, runs it, and stores the result on the task. The platform records status, metrics, and tool calls automatically.

​
Environment variable shortcut

Set XPANDER_AGENT_ID and you can omit agent_id from every Backend call: 
export XPANDER_AGENT_ID="agent-123"

backend = Backend()
args = await backend.aget_args()                     # uses XPANDER_AGENT_ID
task = await backend.ainvoke_agent(prompt="Hello")   # same
Explicit arguments always override the env var.