Connect Custom Skills

• The skills catalog doesn’t have what you need.
• You want to call a private API.
• You want the LLM to run logic that already lives in your codebase.

​

Prerequisites

• Complete the Quickstart so the CLI, SDK, and xpander login are already set up.
• Python 3.12+ for the local handler.
• At least one agent loaded in code via Agents().aget(agent_id=...) or inside an @on_task handler.

​

1. Turn a Python function into a skill

from xpander_sdk import register_tool

@register_tool
def weather_check(location: str) -> str:
    """Check the current weather for a city."""
    return f"Weather in {location}: Sunny, 25C"

1. You don’t write the schema yourself. Type hints are the schema. location: str becomes a required string parameter; add = "Paris" and it becomes optional with a default.
2. The docstring is the skill’s pitch to the LLM. It’s the text the model reads when deciding whether to use this skill, so write it for that audience: what the function does, what kind of input it expects, what it returns.
3. The function name becomes the skill name. The LLM calls it as weather_check. Pick names the model can disambiguate from other skills on the agent.
4. The decorator runs at import time. As long as the module containing it is imported by your handler, the skill shows up in agent.tools. Conditional imports break discovery (the skill will be silently missing) so import the module unconditionally and gate the function’s behavior inside its body.
5. The function stays normal Python. You can unit-test it, call it from scripts, and refactor it without affecting the agent’s other capabilities.

​

2. Use Pydantic for richer input schemas

from typing import Optional
from pydantic import BaseModel
from xpander_sdk import register_tool

class CustomerFilter(BaseModel):
    status: str
    region: Optional[str] = None
    min_lifetime_value: float = 0.0

@register_tool
def search_customers(filter: CustomerFilter, limit: int = 50) -> list[dict]:
    """Search customers by status, optionally filtered by region and minimum lifetime value."""
    # Your implementation goes here.
    return []

1. The model’s fields become a nested object in the skill’s schema. The LLM sees status (required), region and min_lifetime_value (optional with defaults), and supplies them as a structured payload.
2. The SDK validates the incoming payload before your function runs. A bad value never reaches your code; the agent gets a ValueError it can react to in the next turn.
3. Anything Pydantic can model, you can use here. Optional, Union, Literal, Enum, field validators. Whatever the model expresses ends up in the schema the LLM sees.

​

3. Make the skill async when it does I/O

import httpx
from xpander_sdk import register_tool

@register_tool
async def fetch_external_data(api_endpoint: str, headers: dict = None) -> dict:
    """Fetch JSON from an external HTTP endpoint."""
    async with httpx.AsyncClient() as client:
        response = await client.get(api_endpoint, headers=headers or {})
        return response.json()

1. async def is the only difference from a sync skill. Type hints, docstring, decorator, all the same.
2. Use async-native clients for the actual I/O. httpx.AsyncClient for HTTP, asyncpg or SQLAlchemy 2.x async for Postgres, aio-pika for RabbitMQ, etc. A blocking client inside an async def blocks the event loop and slows every other skill call running concurrently.
3. Return the value, don’t return the coroutine. Always await the I/O inside the function. If you forget the await, the SDK passes the coroutine object back as the skill result and the LLM sees garbage.

​

4. Wire custom skills into your agent loop

from dotenv import load_dotenv
load_dotenv()

from xpander_sdk import on_task, Task, Backend, register_tool
from agno.agent import Agent

@register_tool
def weather_check(location: str) -> str:
    """Check the current weather for a city."""
    return f"Weather in {location}: Sunny, 25C"

@on_task
async def handler(task: Task) -> Task:
    backend = Backend(configuration=task.configuration)
    # weather_check is already in args["tools"] alongside the connectors.
    agno_agent = Agent(**(await backend.aget_args(task=task)))
    result = await agno_agent.arun(input=task.to_message())
    task.result = result.content
    return task

from xpander_sdk import Agents, register_tool
from agents import Agent as OpenAIAgent, Runner

@register_tool
def weather_check(location: str) -> str:
    """Check the current weather for a city."""
    return f"Weather in {location}: Sunny, 25C"

xpander_agent = await Agents().aget(agent_id="agt_01H...")
oa_agent = OpenAIAgent(
    name=xpander_agent.name,
    instructions=xpander_agent.instructions.full,
    tools=xpander_agent.openai_agents_sdk_tools,   # connectors + weather_check
    model=xpander_agent.model_name,
)
result = await Runner.run(oa_agent, input="Weather in Paris?")

from xpander_sdk import Agents, register_tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

@register_tool
def weather_check(location: str) -> str:
    """Check the current weather for a city."""
    return f"Weather in {location}: Sunny, 25C"

xpander_agent = await Agents().aget(agent_id="agt_01H...")
react = create_react_agent(
    model=ChatOpenAI(model=xpander_agent.model_name),
    tools=xpander_agent.tools.functions,           # connectors + weather_check
    state_modifier=xpander_agent.instructions.full,
)

from xpander_sdk import Agents, register_tool
from strands.agent import Agent as StrandsAgent

@register_tool
def weather_check(location: str) -> str:
    """Check the current weather for a city."""
    return f"Weather in {location}: Sunny, 25C"

xpander_agent = await Agents().aget(agent_id="agt_01H...")
strands_agent = StrandsAgent(
    name=xpander_agent.name,
    system_prompt=xpander_agent.instructions.full,
    tools=xpander_agent.strands_tools,             # connectors + weather_check
    model=xpander_agent.model_name,
)

​

5. Make a skill selectively available

from datetime import datetime
from xpander_sdk import Backend

backend = Backend(configuration=task.configuration)

def _local_clock() -> str:
    """Return the developer's local clock for debugging."""
    return datetime.now().isoformat()

args = await backend.aget_args(
    task=task,
    tools=[_local_clock],   # appended to connectors + @register_tool functions
)

​

6. Inspect and invoke custom skills directly

from xpander_sdk import Agents

agent = await Agents().aget(agent_id="agt_01H...")

# Every tool on the agent: connectors + @register_tool functions + MCP tools.
for tool in agent.tools.list:
    kind = "local" if tool.is_local else "connector"
    print(tool.name, kind, tool.description[:60])

# Look up a single custom tool and invoke it directly.
weather_tool = agent.tools.get_tool_by_name("weather_check")
result = await agent.ainvoke_tool(
    tool=weather_tool,
    payload={"location": "Paris"},
)
print(result.is_success, result.result)

1. Custom skills and catalog skills look the same to the runtime. They share agent.tools.list, the same lookup helpers, and the same ainvoke_tool entry point. tool.is_local distinguishes the two when you need to.
2. Direct invocation skips the LLM. Useful for migration scripts, batch jobs, or testing the skill’s contract before exposing it to the model.
3. The payload structure follows the schema you declared. For a function typed with primitives, the payload is the keyword args dict. For a Pydantic-typed parameter, the payload is the model’s serialized form.

​

7. Register custom skills with the runtime

@register_tool(add_to_graph=True)
async def lookup_internal_ticket(ticket_id: str) -> dict:
    """Look up an internal support ticket by ID."""
    ...

1. Code changes need a new rollout of your handler. Adding, editing, or removing a @register_tool function changes the code. Settings changes (instructions, model, attached skills) stay live without one.
2. add_to_graph=True syncs on agent load, not on deploy. The first task after rollout triggers the runtime sync; the deploy itself doesn’t. The flag is idempotent. Subsequent loads skip already-synced skills, so you can leave it set permanently.
3. Leave add_to_graph off when you don’t need runtime-side features. The LLM doesn’t need it to call the skill, and skipping it keeps Xpander Chat’s view scoped to runtime-managed configuration.

​

Troubleshooting

​

Next steps