huggingface/smolagents · info · UserWarning

Since `api_name` was not defined, it was automatically set t

Error message

Since `api_name` was not defined, it was automatically set to the first available API: `{api_name}`.

What it means

When constructing a Tool from a Hugging Face Space (`Tool.from_space(...)` or the SpaceUrl path) without an `api_name`, smolagents picks the first endpoint listed in the Space's `named_endpoints` and warns about it. The chosen endpoint may not be the one you intend to call. The warning is informational; you should confirm the picked `api_name` matches your expectation.

Source

Thrown at src/smolagents/tools.py:666

            def __init__(
                self,
                space_id: str,
                name: str,
                description: str = "",
                api_name: str | None = None,
                token: str | None = None,
            ):
                self.name = name
                self.description = description
                self.client = Client(space_id, hf_token=token)
                space_api = self.client.view_api(return_format="dict", print_info=False)
                assert isinstance(space_api, dict)
                space_description = space_api["named_endpoints"]

                # If api_name is not defined, take the first of the available APIs for this space
                if api_name is None:
                    api_name = list(space_description.keys())[0]
                    warnings.warn(
                        f"Since `api_name` was not defined, it was automatically set to the first available API: `{api_name}`."
                    )
                self.api_name = api_name

                try:
                    space_description_api = space_description[api_name]
                except KeyError:
                    raise KeyError(f"Could not find specified {api_name=} among available api names.")
                self.inputs = {}
                for parameter in space_description_api["parameters"]:
                    parameter_type = parameter["type"]["type"]
                    if parameter_type == "object":
                        parameter_type = "any"
                    self.inputs[parameter["parameter_name"]] = {
                        "type": parameter_type,
                        "description": parameter["python_type"]["description"],
                        "nullable": parameter["parameter_has_default"],
                    }

View on GitHub (pinned to 30bb116109)

Solutions

1. Pass an explicit `api_name`: `Tool.from_space('user/space', api_name='/predict')`
2. Inspect the Space's endpoints (`https://huggingface.co/spaces/user/space`) to find the correct named endpoint before constructing the tool
3. If the auto-picked endpoint is actually correct, verify `tool.api_name` after construction and suppress/ignore the warning

Example fix

# before
tool = Tool.from_space('black-forest-labs/FLUX.1-schnell')

# after
tool = Tool.from_space('black-forest-labs/FLUX.1-schnell', api_name='/infer')

from huggingface_hub import get_space_metadata  # or query the space config
import requests

def list_space_endpoints(space_id: str) -> list[str]:
    r = requests.get(f'https://huggingface.co/spaces/{space_id}/config', timeout=10)
    return list(r.json().get('named_endpoints', {}).keys())  # pass one as api_name

When it happens

Trigger: `Tool.from_space('username/space-name')` (or `Tool(url=...)`) with `api_name=None` while the Space exposes multiple named endpoints. The constructor takes `list(space_description['named_endpoints'].keys())[0]` as the API.

Common situations: Wrapping a multi-endpoint Gradio Space (e.g. image-to-image Spaces with extra endpoints like /upscale) and assuming a default route; Spaces that add new endpoints over time, silently changing which one is 'first'.

Related errors

• You must set an attribute {attr}.
• Attribute {attr} should have type {expected_type.__name__},
• Attribute output_schema should have type dict, got {type(out
• Invalid Tool name '{self.name}': must be a valid Python iden
• Input '{input_name}': when type is a list, all elements must

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/2cfd09cc9e6b042d. Report an issue: GitHub.