Back

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

  1. Open Organization settings, Models tab, then click Add a connection.
  2. Pick the API type: Hugging Face (the router address is filled in for you) or OpenAI-compatible for any other server.
  3. Name the connection, enter the API base address (without /chat/completions) and the token, then click Declare.
  4. 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.
  5. For each model, say whether it can use tools and read images (see Capabilities), then click Declare.
  6. 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.

PlanCustom models
FreeNot included
Pro1
Business10
EnterpriseUnlimited

Troubleshooting

SymptomCause 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 toolThe 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 modelYour 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 addedYour plan includes no custom model, or its quota is reached. Remove a model or upgrade your plan.