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.
Tool represents a single callable an agent can invoke: a connector operation, an OpenAPI endpoint, an MCP tool, or a local Python function registered with @register_tool. You normally get one from agent.tools.list or agent.tools.get_tool_by_id(...).
agent = await agents.aget("agent-123")
tool = agent.tools.get_tool_by_id("get_weather")
print(tool.id, tool.name, tool.description)
print(tool.parameters) # raw JSON schema
print(tool.schema) # Pydantic model class generated from parameters
Attributes
| Attribute | Type | Description |
|---|
id | str | Tool identifier (used as the function name when invoked by the LLM). |
name | str | Display name. |
method | str | HTTP method for remote invocation ("POST", "GET", …). |
path | str | Endpoint path. |
description | str | Human-readable description (used by the LLM to decide when to call). |
parameters | dict | JSON schema for the input payload. |
is_local | bool | True when the tool is a @register_tool Python function. |
is_synced | bool | For local tools: True after the tool has been pushed to the platform’s graph. |
is_standalone | bool | True when loaded via aload_tool_by_id (no agent context). |
should_add_to_graph | bool | Whether this tool should be added to agent execution graphs. |
connector_id | str | None | For platform tools: the connector id. |
operation_id | str | None | For platform tools: the operation id. |
schema_overrides | AgentGraphItemSchema | None | Per-agent input/output schema overrides. |
fn | Callable | None | The Python function for local tools. Excluded from serialization. |
configuration | Configuration | SDK configuration. |
Computed properties
schema
tool.schema -> type[BaseModel]
tool.parameters. The model’s name is {ToolIdPascalCase}PayloadSchema. If the agent has schema overrides for this tool, they’re applied here.
WeatherSchema = tool.schema
WeatherSchema(city="NYC") # validates input
payload_schema
tool.payload_schema -> type[BaseModel]
payload field whose type is tool.schema. Useful when a framework expects every tool call to be wrapped in {"payload": {...}}.
PayloadModel = tool.payload_schema
PayloadModel(payload={"city": "NYC"})
Methods
ainvoke / invoke
Invoke the tool. Validates the payload against tool.schema, executes locally (is_local=True) or remotely, and returns a ToolInvocationResult.
result = await tool.ainvoke(
agent_id="agent-123",
payload={"city": "Tokyo"},
)
print(result.result, result.is_success)
| Parameter | Type | Required | Default | Description |
|---|
agent_id | str | Yes | – | Agent invoking the tool. |
payload | Any | Yes | – | Tool input. Validated against tool.schema. |
agent_version | str | No | None | Pin to a specific agent version. |
payload_extension | dict | No | {} | Extra fields deep-merged into the payload (headers, auth, etc.). |
configuration | Configuration | No | Tool’s config | Override SDK configuration. |
task_id | str | No | None | Associate with a task (for activity logging). |
tool_call_id | str | No | None | Correlation id matching the LLM’s tool-call id. |
report_activity | bool | No | False | Push ToolCallRequest / ToolCallResult events to the task activity log. Set this when invoking outside the framework’s tool hook (so events aren’t double-emitted). |
ToolInvocationResult (see below). Sync sibling: tool.invoke(...).
ainvoke runs the configured tool lifecycle hooks (@on_tool_before / @on_tool_after / @on_tool_error) around the call.
Lower-level: makes the API call without local-tool fallback or hook execution. Used internally by ainvoke when is_local=False. Use directly only for advanced cases (preflight checks, custom invocation pipelines).
result = await tool.acall_remote_tool(
agent_id="agent-123",
payload={"city": "Tokyo"},
)
agraph_preflight_check / graph_preflight_check
Asks the platform to validate a hypothetical tool invocation without executing it. Used internally for graph routing.
get_invocation_function
tool.get_invocation_function(
is_async: bool = False,
configuration: Optional[Configuration] = None,
) -> Callable
invoke = tool.get_invocation_function(is_async=True)
result = await invoke({"city": "NYC"}) # ToolInvocationResult
connector_id_operation_id and returns the raw response wrapped in ToolInvocationResult. Use it after ToolsRepository.aload_tool_by_id(...) to call a single connector without an agent.
The shape returned by ainvoke and the standalone invocation function.
| Field | Type | Description |
|---|
tool_id | str | The tool’s id. |
tool_call_id | str | None | The correlation id, if passed. |
task_id | str | None | The task id, if passed. |
payload | Any | The payload that was sent. |
status_code | int | HTTP status (200 by default). |
result | Any | The tool’s response. |
is_success | bool | True on 2xx. |
is_error | bool | True on failure. |
is_local | bool | True for local tools. |
is_success and is_error are mutually exclusive in normal operation: check is_error first to branch on failure cases.
Examples
tool = agent.tools.get_tool_by_id("get_weather")
# Pydantic schema (from parameters)
schema = tool.schema
print(schema.model_json_schema())
# Validate a payload before sending
schema.model_validate({"city": "NYC"}) # raises ValidationError on bad shape
Per-call configuration override
from xpander_sdk import Configuration
custom_config = Configuration(api_key="other-key", organization_id="other-org")
result = await tool.ainvoke(
agent_id="agent-123",
payload={"city": "Berlin"},
configuration=custom_config,
)
Reporting activity for non-Agno callers
When invoking a tool outside an Agno-driven flow (e.g. from your own agent loop), set report_activity=True so the call shows up in the task’s activity log:
result = await tool.ainvoke(
agent_id="agent-123",
task_id=task.id,
payload={...},
report_activity=True,
)
False: the Agno hook reports the call automatically and you’d otherwise double-emit events.
