Skills (ToolsRepository)

ToolsRepository is the registry that holds every skill an agent can call. In the SDK a skill is a Tool; agent.tools lists them. There are two kinds:

Backend skills: catalog skills and OpenAPI imports configured in Xpander Chat. Loaded automatically when you agents.aget(...) an agent.
Local skills: Python functions you decorate with @register_tool. Registered in-process and merged into the agent’s skill list.

Do not instantiate ToolsRepository yourself. agent.tools returns the configured instance for that agent.

agent = await agents.aget("agent-123")

# All tools (backend + local) merged into one list
for tool in agent.tools.list:
    print(tool.id, tool.name, tool.is_local)

# Look up by id or name
weather = agent.tools.get_tool_by_id("get_weather")
weather2 = agent.tools.get_tool_by_name("Weather")

# Framework-ready callables (used internally by Backend.aget_args)
fns = agent.tools.functions

Class layout

Type	Reference
`ToolsRepository`	This page
`Tool`	`Tool` class
`@register_tool` decorator	register_tool
MCP types	MCP
Skill call lifecycle hooks	`@on_tool_*`

Constructor

ToolsRepository(
    configuration: Optional[Configuration] = None,
    tools: List[Tool] = [],
    agent_graph: Optional[AgentGraph] = None,
    is_async: bool = True,
)

Parameter	Type	Default	Description
`configuration`	`Configuration`	`Configuration()`	SDK configuration.
`tools`	`list[Tool]`	`[]`	Backend-managed skills to seed the repository.
`agent_graph`	`AgentGraph`	`None`	Owning agent’s graph (for schema overrides).
`is_async`	`bool`	`True`	Whether `.functions` should produce async callables.

In practice, agents.aget(...) constructs a ToolsRepository for you with all four arguments populated.

Properties

`list`

agent.tools.list -> list[Tool]

A merged list of backend skills and locally-registered skills (de-duplicated by id). Each Tool has its Configuration set and any agent-graph schema overrides applied.

`functions`

agent.tools.functions -> list[Callable[..., Any]]

Callables ready for an agent loop, one for every skill in .list. Each callable accepts a single payload argument validated against the skill’s auto-generated Pydantic schema. The callable’s __name__ is the skill id and its __doc__ includes a usage example. This is what Backend.aget_args injects into your agent loop’s tools=... parameter: you rarely need it directly. Useful when binding skills to an agent loop the SDK has no integration for.

Methods

`get_tool_by_id`

agent.tools.get_tool_by_id("get_weather") -> Tool | None

Returns the Tool with the matching id, or None.

`get_tool_by_name`

agent.tools.get_tool_by_name("Weather") -> Tool | None

Returns the Tool with the matching name (display name), or None.

`register_tool` (classmethod)

ToolsRepository.register_tool(tool: Tool)

Adds a Tool to the global local registry. Used by the @register_tool decorator: you don’t usually call this directly.

`should_sync_local_tools`

agent.tools.should_sync_local_tools() -> bool

Returns True when at least one local skill is marked should_add_to_graph=True and hasn’t been synced yet.

`get_local_tools_for_sync`

agent.tools.get_local_tools_for_sync() -> list[Tool]

Returns local skills awaiting sync (used internally during agent.aload).

`aload_tool_by_id`

await agent.tools.aload_tool_by_id("<connector_id>_<operation_id>") -> None

Standalone skill loading: looks up a skill by its <connector_id>_<operation_id> form and seeds it into the repository. Useful when you want to invoke a single skill without loading an agent. The id is the skill’s connector_id UUID and the operation’s catalog id joined by a single underscore, for example "07687ac7-d474-4d24-8ec6-6debac476b00_6a581606eaade0ae8b8f2c9c". Both halves come from List Skill Operations. The sync sibling is load_tool_by_id.

Patterns

Iterate every skill

agent = await agents.aget("agent-123")

for tool in agent.tools.list:
    print(f"- {tool.id}: {tool.description[:60]}")

Bind skills to an agent loop by hand

fns = agent.tools.functions   # list of callables, each accepts `payload`

# Pass directly to a framework that expects callables:
my_framework_agent = MyAgent(tools=fns)

Standalone invocation (no agent context)

from xpander_sdk import ToolsRepository

repo = ToolsRepository()
await repo.aload_tool_by_id("07687ac7-d474-4d24-8ec6-6debac476b00_6a581606eaade0ae8b8f2c9c")
tool = repo.list[0]

invoke = tool.get_invocation_function(is_async=True)
result = await invoke({"channel": "#general", "text": "Hello"})

This pattern is how you call a single catalog skill without going through an agent.

@register_tool

@register_tool turns a Python function into a skill the agent can invoke. The SDK extracts type hints and the docstring to build a schema and description automatically: there’s no manual schema writing.

from xpander_sdk import register_tool

@register_tool
def calculate_sum(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

This decorator runs at module import. Once it does, calculate_sum is available to every Agents().aget(...) call as a local skill with id "calculate_sum".

Decorator forms

@register_tool                                    # plain
def fn(...): ...

@register_tool(add_to_graph=True)                 # with options
def fn(...): ...

Parameter	Type	Default	Description
`add_to_graph`	`bool`	`False`	When `True`, the skill is pushed into the agent’s execution graph (so the runtime routes calls through it). When `False`, the skill is only available in-process.

What it does

Inspects the function’s parameters and type hints.
Builds a Pydantic model (<FunctionName>Args) from the parameters: required if no default, optional otherwise.
Constructs a Tool with:
- id = function name
- name = function name
- description = function docstring
- parameters = generated JSON schema
- fn = the function
- is_local = True
- should_add_to_graph = add_to_graph
Registers the Tool in ToolsRepository’s class-level _local_tools list (process-wide singleton).
Returns the original function unchanged: calculate_sum(2, 3) still works as plain Python.

Examples

Async functions are supported

@register_tool
async def fetch_url(url: str) -> str:
    """Fetch the body of a URL."""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
    return response.text

When the agent calls this skill, the SDK awaits the coroutine.

Optional parameters

@register_tool
def search(query: str, limit: int = 10, region: str = "US") -> list[str]:
    """Search the catalog. Returns matching SKUs."""
    ...

Defaults become optional fields in the JSON schema.

Push to the agent graph

@register_tool(add_to_graph=True)
async def analyze_data(data: list, analysis_type: str) -> dict:
    """Analyze incoming data; returns aggregated metrics."""
    ...

add_to_graph=True registers the skill on the agent in Xpander Chat for the next agents.aget(...): the SDK sync runs in the background after aget returns.

Use the function directly

@register_tool
def add(a: int, b: int) -> int:
    """Add two ints."""
    return a + b

# Still callable as a regular function
add(2, 3)   # 5

Visibility rules

The decorator registers skills at module-import time on a process-wide registry. That means:

Every agent loaded by Agents().aget(...) in this process inherits the local skills.
Skills defined inside a function body register the first time the function runs, but stay registered for the rest of the process’s lifetime.
If you del or rename a function after decoration, the registered Tool keeps its captured reference (the fn attribute): it doesn’t unregister itself.

For per-invocation skills, use Backend.aget_args(tools=[fn]) instead: that adds callables to one specific aget_args call without polluting the global registry.

Schema details

The generated schema uses Pydantic’s model_json_schema(mode="serialization"). Parameter names, types, and defaults map directly:

@register_tool
def book_flight(origin: str, destination: str, date: str = "tomorrow") -> dict:
    """Book a flight."""
    ...

generates roughly:

{
  "properties": {
    "origin": {"type": "string", "title": "Origin"},
    "destination": {"type": "string", "title": "Destination"},
    "date": {"type": "string", "title": "Date", "default": "tomorrow"}
  },
  "required": ["origin", "destination"],
  "title": "BookFlightArgs",
  "type": "object"
}

The agent’s LLM sees this schema; the docstring becomes the skill’s description. Write docstrings the way you’d write a skill description for the model: that’s exactly what the LLM reads.

Tool class: what the decorator creates.
@on_tool_before / @on_tool_after / @on_tool_error: lifecycle hooks around any skill invocation.

`Tool` class

Tool represents a single skill an agent can invoke: a catalog skill operation, an OpenAPI endpoint, a skill served over MCP, 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`	Skill 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 skill is a `@register_tool` Python function.
`is_synced`	`bool`	For local skills: `True` after the skill has been pushed to the runtime’s graph.
`is_standalone`	`bool`	`True` when loaded via `aload_tool_by_id` (no agent context).
`should_add_to_graph`	`bool`	Whether this skill should be added to agent execution graphs.
`connector_id`	`str \| None`	For backend skills: the id of the catalog skill.
`operation_id`	`str \| None`	For backend skills: the operation id.
`schema_overrides`	`AgentGraphItemSchema \| None`	Per-agent input/output schema overrides.
`fn`	`Callable \| None`	The Python function for local skills. Excluded from serialization.
`configuration`	`Configuration`	SDK configuration.

Computed properties

`schema`

tool.schema -> type[BaseModel]

A dynamically-generated Pydantic model class derived from tool.parameters. The model’s name is {ToolIdPascalCase}PayloadSchema. If the agent has schema overrides for this skill, they’re applied here.

WeatherSchema = tool.schema
WeatherSchema(city="NYC")          # validates input

`payload_schema`

tool.payload_schema -> type[BaseModel]

A wrapper schema with a single payload field whose type is tool.schema. Useful when an agent loop expects every skill call to be wrapped in {"payload": {...}}.

PayloadModel = tool.payload_schema
PayloadModel(payload={"city": "NYC"})

Methods

`ainvoke` / `invoke`

Invoke the skill. 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 skill.
`payload`	`Any`	Yes	-	Skill 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	The skill’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 agent loop’s skill hook (so events aren’t double-emitted).

Returns a ToolInvocationResult (see below). Sync sibling: tool.invoke(...). ainvoke runs the configured skill call lifecycle hooks (@on_tool_before / @on_tool_after / @on_tool_error) around the call.

`acall_remote_tool` / `call_remote_tool`

Lower-level: makes the API call without local-skill 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 runtime to validate a hypothetical skill 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

Factory that returns a pre-configured invocation function bound to this skill’s connector_id + configuration. Use for standalone invocation (no agent context):

invoke = tool.get_invocation_function(is_async=True)
result = await invoke({"city": "NYC"})   # ToolInvocationResult

This skips agent-id and task-id binding: the underlying call hits the catalog skill via connector_id_operation_id and returns the raw response wrapped in ToolInvocationResult. Use it after ToolsRepository.aload_tool_by_id(...) to call a single skill without an agent.

`ToolInvocationResult`

The shape returned by ainvoke and the standalone invocation function.

Field	Type	Description
`tool_id`	`str`	The skill’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 skill’s response.
`is_success`	`bool`	`True` on 2xx.
`is_error`	`bool`	`True` on failure.
`is_local`	`bool`	`True` for local skills.

is_success and is_error are mutually exclusive in normal operation: check is_error first to branch on failure cases.

Examples

Inspect a skill’s schema

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 skill 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,
)

Inside Agno-driven flows, leave it at False: the Agno hook reports the call automatically and you’d otherwise double-emit events.

MCP types

The Model Context Protocol (MCP) lets agents connect to skills served over MCP. The SDK exposes MCPServerDetails for declaring MCP endpoints per task, and a few enums for the supported transports and auth types.

from xpander_sdk import MCPServerDetails, MCPServerType, MCPServerAuthType

server = MCPServerDetails(
    type=MCPServerType.Remote,
    name="internal-docs",
    url="https://mcp.internal.acme.com",
    auth_type=MCPServerAuthType.APIKey,
    api_key="...",
)

Pass a list of these to Agent.acreate_task(mcp_servers=[...]) to attach MCP endpoints for a single run without registering them in Xpander Chat; endpoints already registered there are added automatically.

`MCPServerDetails`

MCPServerDetails(
    type: MCPServerType = MCPServerType.Remote,
    name: Optional[str] = None,
    command: Optional[str] = None,
    url: Optional[str] = None,
    transport: MCPServerTransport = MCPServerTransport.HTTP_Transport,
    auth_type: MCPServerAuthType = MCPServerAuthType._None,
    api_key: Optional[str] = None,
    use_secrets_manager: bool = False,
    client_id: Optional[str] = None,
    client_secret: Optional[str] = None,
    headers: Dict = {},
    env_vars: Dict = {},
    allowed_tools: List[str] = [],
    additional_scopes: List[str] = [],
    share_user_token_across_other_agents: bool = True,
)

Field	Type	Description
`type`	`MCPServerType`	`Local` (stdio) or `Remote` (HTTP/SSE).
`name`	`str`	Server name (used in logs and Xpander Chat).
`command`	`str`	For `Local` servers: the binary to run.
`url`	`str`	For `Remote` servers: the server endpoint.
`transport`	`MCPServerTransport`	`STDIO`, `SSE`, or `HTTP_Transport` (default).
`auth_type`	`MCPServerAuthType`	`_None`, `APIKey`, `OAuth2`, or `CustomHeaders`.
`api_key`	`str`	For `APIKey` auth.
`use_secrets_manager`	`bool`	Resolve the API key from xpander’s secrets manager.
`client_id` / `client_secret`	`str`	For `OAuth2`.
`headers`	`dict`	Custom headers (used with `CustomHeaders` auth or always-on).
`env_vars`	`dict`	Env vars to set when launching `Local` servers.
`allowed_tools`	`list[str]`	Whitelist of skills to expose from this MCP endpoint. Empty = all.
`additional_scopes`	`list[str]`	Extra OAuth scopes.
`share_user_token_across_other_agents`	`bool`	When `True`, end users only authenticate once even when multiple agents use the same server.

Enums

`MCPServerType`

Value	Meaning
`Local` (`"local"`)	Run a local stdio process. Requires `command` and optional `env_vars`.
`Remote` (`"remote"`)	Connect to a remote HTTP / SSE server. Requires `url`.

`MCPServerTransport`

Value	Meaning
`STDIO` (`"stdio"`)	Standard input/output (Local servers).
`SSE` (`"sse"`)	Server-sent events.
`HTTP_Transport` (`"streamable-http"`)	HTTP streaming (default for remote servers).

`MCPServerAuthType`

Value	Meaning
`_None` (`"none"`)	No auth.
`APIKey` (`"api_key"`)	Static API key in `api_key`.
`OAuth2` (`"oauth2"`)	OAuth2 with `client_id` / `client_secret`. Triggers `auth_event`s during runs.
`CustomHeaders` (`"custom_headers"`)	Send `headers` as auth.

Examples

Local server (stdio)

local_server = MCPServerDetails(
    type=MCPServerType.Local,
    name="my-local-mcp",
    command="python -m my_mcp_module",
    transport=MCPServerTransport.STDIO,
    env_vars={"DEBUG": "1"},
)

Remote with API key

remote_server = MCPServerDetails(
    type=MCPServerType.Remote,
    name="docs-mcp",
    url="https://mcp.docs.acme.com",
    transport=MCPServerTransport.HTTP_Transport,
    auth_type=MCPServerAuthType.APIKey,
    api_key="sk-...",
)

Remote with OAuth2

oauth_server = MCPServerDetails(
    type=MCPServerType.Remote,
    name="github-mcp",
    url="https://mcp.github.com",
    auth_type=MCPServerAuthType.OAuth2,
    client_id="...",
    client_secret="...",
    additional_scopes=["repo", "read:user"],
)

OAuth2 servers fire auth_events during a run when end-user authorization is required. Register an @on_auth_event handler to route the OAuth URL to your UI.

Per-task server attachment

task = await agent.acreate_task(
    prompt="Search our internal docs for the Q4 roadmap.",
    mcp_servers=[remote_server],
)

These are appended to the agent’s persistent MCP config for this task only.

Limit which skills are exposed

restricted = MCPServerDetails(
    type=MCPServerType.Remote,
    name="github-mcp",
    url="https://mcp.github.com",
    auth_type=MCPServerAuthType.OAuth2,
    client_id="...",
    client_secret="...",
    allowed_tools=["search_repositories", "get_issue"],
)

Only search_repositories and get_issue will be exposed to the agent: every other skill the MCP endpoint offers is hidden.

OAuth response types (for `@on_auth_event` payloads)

When OAuth flows fire, event.data is shaped like one of these:

Type	Field	Description
`MCPOAuthGetTokenResponse`	`type: MCPOAuthResponseType`	Discriminator.
	`data: ...`	One of the variants below.

Variant	Fields
`MCPOAuthGetTokenLoginRequiredResponse`	`url`, `server_url`, `server_name`
`MCPOAuthGetTokenTokenReadyResponse`	`access_token`
`MCPOAuthGetTokenGenericResponse`	`message`

MCPOAuthResponseType values: not_supported, login_required, token_issue, token_ready. Use these in your auth handler to display the right state to the end user (login URL vs. “we’re working on it” vs. success).

​Class layout

​Constructor

​Properties

​list

​functions

​Methods

​get_tool_by_id

​get_tool_by_name

​register_tool (classmethod)

​should_sync_local_tools

​get_local_tools_for_sync

​aload_tool_by_id

​Patterns

​Iterate every skill

​Bind skills to an agent loop by hand

​Standalone invocation (no agent context)

​@register_tool

​Decorator forms

​What it does

​Examples

​Async functions are supported

​Optional parameters

​Push to the agent graph

​Use the function directly

​Visibility rules

​Schema details

​Related

​Tool class

​Attributes

​Computed properties

​schema

​payload_schema

​Methods

​ainvoke / invoke

​acall_remote_tool / call_remote_tool

​agraph_preflight_check / graph_preflight_check

​get_invocation_function

​ToolInvocationResult

​Examples

​Inspect a skill’s schema

​Per-call configuration override

​Reporting activity for non-Agno callers

​MCP types

​MCPServerDetails

​Enums

​MCPServerType

​MCPServerTransport

​MCPServerAuthType

​Examples

​Local server (stdio)

​Remote with API key

​Remote with OAuth2

​Per-task server attachment

​Limit which skills are exposed

​OAuth response types (for @on_auth_event payloads)

Class layout

Constructor

Properties

`list`

`functions`

Methods

`get_tool_by_id`

`get_tool_by_name`

`register_tool` (classmethod)

`should_sync_local_tools`

`get_local_tools_for_sync`

`aload_tool_by_id`

Patterns

Iterate every skill

Bind skills to an agent loop by hand

Standalone invocation (no agent context)

@register_tool

Decorator forms

What it does

Examples

Async functions are supported

Optional parameters

Push to the agent graph

Use the function directly

Visibility rules

Schema details

Related

`Tool` class

Attributes

Computed properties

`schema`

`payload_schema`

Methods

`ainvoke` / `invoke`

`acall_remote_tool` / `call_remote_tool`

`agraph_preflight_check` / `graph_preflight_check`

`get_invocation_function`

`ToolInvocationResult`

Examples

Inspect a skill’s schema

Per-call configuration override

Reporting activity for non-Agno callers

MCP types

`MCPServerDetails`

Enums

`MCPServerType`

`MCPServerTransport`

`MCPServerAuthType`

Examples

Local server (stdio)

Remote with API key

Remote with OAuth2

Per-task server attachment

Limit which skills are exposed

OAuth response types (for `@on_auth_event` payloads)