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.

Task.areport_external_task is the @classmethod version of Backend.areport_external_task. It logs a task that was executed outside the xpander.ai runtime so it appears in task history and metrics. Use this form when you don’t have a Backend instance in scope but do have a Configuration. 
from xpander_sdk import Task, Tokens, Configuration

config = Configuration()  # picks up env vars

task = await Task.areport_external_task(
    configuration=config,
    agent_id="agent-123",
    id="ext-job-9921",
    input="Summarize Q4 earnings",
    result="Q4 revenue grew 22% YoY, driven by ...",
    tokens=Tokens(prompt_tokens=2_140, completion_tokens=380),
    duration=4.7,
    used_tools=["web_search", "fetch_pdf"],
    is_success=True,
)

​
Parameters

ParameterTypeRequiredDefaultDescription
configurationConfigurationNoNew Configuration()SDK config (api_key + organization_id).
agent_idstrYes–Agent the run belongs to.
idstrNoNoneExternal task id. Re-using the same id updates the existing record.
inputstrNoNoneRun input.
llm_responseAnyNoNoneRaw provider response. Stored verbatim.
tokensTokensNoNoneToken usage.
is_successboolNoTruePass/fail.
resultstrNoNoneFinal result.
durationfloatNo0Wall-clock seconds.
used_toolslist[str]No[]Tool names.

​
Returns Task

The platform-side Task after persistence. Carries the id, status, and timestamps assigned by the cloud.

​
When to use this vs. Backend.areport_external_task

Functionally identical. Backend.areport_external_task is more discoverable (it sits next to the other Backend methods you’d be using); this classmethod is convenient when you don’t want to instantiate Backend. 
# Equivalent ways to record an external run:

# 1. Backend
backend = Backend(configuration=config)
await backend.areport_external_task(agent_id="agent-123", id="ext-001", ...)

# 2. Task classmethod
await Task.areport_external_task(configuration=config, agent_id="agent-123", id="ext-001", ...)
See the Backend page for typical usage patterns (idempotent updates, failure reporting).

​
Sync version

Task.report_external_task(configuration=config, agent_id="agent-123", id="ext-001", ...)