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.

Backend.ainvoke_agent (and its sync sibling invoke_agent) is shorthand for “load the agent and create a task.” Internally it calls Agents.aget(agent_id) followed by Agent.acreate_task(...), returning the resulting Task. Use this when you want to invoke an agent from outside the @on_task runtime: for example, from a webhook handler, a script, or another agent.
If prompt happens to be a JSON string containing xpander_task_id, the method short-circuits and returns the existing task instead of creating a new one. This is how the platform passes task continuations through chat-style integrations.
from xpander_sdk import Backend

backend = Backend()
task = await backend.ainvoke_agent(
    agent_id="agent-123",
    prompt="Summarize the latest sales report",
)
print(task.id, task.status)

​
Parameters

ParameterTypeRequiredDefaultDescription
agent_idstrNoXPANDER_AGENT_ID env varAgent to invoke. Falls back to env var if omitted.
promptstrNo""Natural-language input for the agent.
existing_task_idstrNoNoneContinue an existing task instead of creating a new one.
file_urlslist[str]NoNoneURLs of files to attach (PDFs, images, CSVs, …).
user_detailsUserNoNoneEnd-user context for memory and personalization.
agent_versionstrNoNonePin a specific agent version. Defaults to the latest.
tool_call_payload_extensiondictNoNoneExtra fields merged into every tool-call payload.
sourcestrNo"sdk"Origin tag stored on the task (e.g. "webhook", "slack").
worker_idstrNoNonePin execution to a specific worker.
run_locallyboolNoFalseMark the task as locally executed (skips cloud worker dispatch).
output_formatOutputFormatNoNoneText, Markdown, Json, or Voice.
output_schemadictNoNoneJSON schema for structured output (paired with OutputFormat.Json).
events_streamingboolNoFalseEnable SSE streaming via task.aevents().
additional_contextstrNoNoneExtra context appended to the system prompt for this run.
expected_outputstrNoNoneDescription of the expected output shape (used by some frameworks for self-verification).

​
Returns Task

The created Task object, populated with the platform-assigned id and an initial status of pending. See Task for the full attribute list.

​
Examples

​
Attach files

task = await backend.ainvoke_agent(
    agent_id="agent-123",
    prompt="Find action items from this meeting recording.",
    file_urls=[
        "https://example.com/recordings/meeting.mp3",
        "https://example.com/transcripts/notes.pdf",
    ],
)
PDFs and images are auto-categorized by Task.get_files() / get_images() for Agno. Other file types (CSV, JSON, TXT, …) are inlined into the message via Task.to_message().

​
Structured output

from xpander_sdk import OutputFormat

task = await backend.ainvoke_agent(
    agent_id="agent-123",
    prompt="Extract company name and revenue from the press release.",
    file_urls=["https://example.com/press-release.pdf"],
    output_format=OutputFormat.Json,
    output_schema={
        "type": "object",
        "properties": {
            "company": {"type": "string"},
            "revenue_usd": {"type": "number"},
        },
        "required": ["company"],
    },
)

​
Stream events

task = await backend.ainvoke_agent(
    agent_id="agent-123",
    prompt="Long-running research task",
    events_streaming=True,
)

async for event in task.aevents():
    print(event.type, event.data)

​
Continue an existing task

task = await backend.ainvoke_agent(
    agent_id="agent-123",
    existing_task_id="task_abc123",
    prompt="Now summarize what you found.",
)
existing_task_id reuses the same memory thread, so the agent has full context from the prior run.

​
Per-end-user context

from xpander_sdk import User

task = await backend.ainvoke_agent(
    agent_id="agent-123",
    prompt="What's on my calendar this afternoon?",
    user_details=User(
        id="user_42",
        email="alex@example.com",
        first_name="Alex",
        timezone="America/New_York",
    ),
)
The User object scopes user-memory storage and connector authentication (e.g. OAuth tokens for Gmail or Calendar) to the right end user.

​
Sync version

task = backend.invoke_agent(
    agent_id="agent-123",
    prompt="Hello!",
)
Identical signature; blocks until the task is created. Don’t call from inside a running event loop: use ainvoke_agent there.