Documentation
Use your own AI model
Besides the catalogue's models, an organization can run its agents on a model it serves itself: an open model hosted on your servers, a Hugging Face model, or a model you trained. Squadico does not host it: it calls it, like any provider, through an OpenAI-compatible API.
What you need
- An OpenAI-compatible API: the /v1/chat/completions route (with streaming) and, ideally, /v1/models to list your models.
- An https:// address reachable from the Internet. Squadico calls your model from its own servers: an address on your organization's internal network (localhost, 10.x, 192.168.x…) is refused. Opening it to Squadico is up to you (public domain, gateway, reverse proxy).
- An access token, sent in the Authorization: Bearer header. Squadico stores it encrypted and never shows it again.
- For the agent to use tools: a model trained for tool calling, and a server configured to expose it (with vLLM: --enable-auto-tool-choice and --tool-call-parser).
- A plan that includes custom models (see below).
Adding a model in Squadico
- Open Organization settings, Models tab, then click Add a connection.
- Pick the API type: Hugging Face (the router address is filled in for you) or OpenAI-compatible for any other server.
- Name the connection, enter the API base address (without /chat/completions) and the token, then click Declare.
- Click List the models: Squadico calls your API's /models route. Tick the models to add. If your API lists nothing, type the model id by hand.
- For each model, say whether it can use tools and read images (see Capabilities), then click Declare.
- The model appears in the model tree, under the connection, with the Custom badge. Pick it in an agent's settings like any other model.
A model's capabilities
- Tools: tick only if both the model and your server handle tool calling. A model without it is never handed the agent's tools; a model declared with it by mistake fails conversations as soon as the agent has a tool.
- Images: tick if the model takes images as input (a vision model). Without it, image attachments are not sent to it.
- Both boxes start unticked: nothing in the API lets Squadico guess. You can change them later.
Hugging Face models
- The Inference Providers router (https://router.huggingface.co/v1) is OpenAI-compatible and billed per use on your Hugging Face account. Create a token under huggingface.co → Settings → Access Tokens, with the "Make calls to Inference Providers" permission.
- The router does not serve every Hub model: only those a partner provider hosts (a few hundred). Use List the models rather than typing an id: the list comes from the router, and everything in it answers.
- Providers must be enabled on your account (huggingface.co → Settings → Inference Providers), or the router refuses even a model it lists.
- For a model outside that list — a Hub model, private or fine-tuned — deploy it on a dedicated Inference Endpoint (the model page's Deploy button, vLLM or TGI engine). Then declare an OpenAI-compatible connection with the endpoint's address followed by /v1.
Your own model
Serve your model behind an OpenAI-compatible server, then expose it over HTTPS with a token. Example with vLLM:
# Serve the model (OpenAI-compatible API on port 8000) vllm serve your-org/your-model \ --api-key "$SQUADICO_TOKEN" \ --enable-auto-tool-choice \ --tool-call-parser hermes # Then expose it over HTTPS on a public address (reverse proxy, gateway…) # and declare https://models.your-company.com/v1 in Squadico.
- Other compatible servers: TGI, SGLang, Ollama, LM Studio, or a managed service (SageMaker, Vertex AI, Azure ML) in OpenAI-compatible mode.
- If your API is not OpenAI-compatible, put LiteLLM in front of it: it translates to that format.
- The model needs a correct chat template, or its answers will be incoherent.
Check your API before declaring it
These two calls are the ones Squadico makes. If they answer from a machine outside your network, the connection will work.
BASE_URL=https://models.your-company.com/v1
# GET /v1/models: the models Squadico offers to add
curl -s "$BASE_URL/models" -H "Authorization: Bearer $TOKEN"
# POST /v1/chat/completions: a conversation, as an agent sends it
curl -s "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"model": "your-org/your-model", "messages": [{"role": "user", "content": "Hello"}]}'Custom models per plan
How many custom models an organization may add (across all its connections) depends on its plan. Their usage is not billed by Squadico: your server or your provider bills it.
| Plan | Custom models |
|---|---|
| Free | Not included |
| Pro | 1 |
| Business | 10 |
| Enterprise | Unlimited |
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| "Enter an address reachable from the Internet" | The address is http://, or it points to a private address. Expose the API over https:// on a public address. |
| "The requested model … is not supported by any provider you have enabled" | Hugging Face: no inference provider serves this model, or providers are disabled on your account. Pick a model offered by List the models, enable the providers, or deploy the model on an Inference Endpoint. |
| "The AI provider does not offer this agent's model" | The model id matches no model your server loads. Check it with GET /v1/models: that exact id is the one to declare. |
| "The AI provider refused the key" | The token is invalid or expired. Update it from the connection. |
| The agent fails as soon as it has a tool | The model is declared with Tools but your server does not expose tool calling. Untick Tools, or enable it on the server (vLLM: --enable-auto-tool-choice --tool-call-parser …). |
| "Not listed by the API" on a typed model | Your API does not list this model: check the id. If your server lists only some of its models, you can add it anyway. |
| A connection cannot be added | Your plan includes no custom model, or its quota is reached. Remove a model or upgrade your plan. |