Antseed inference in GenLayer Studio
Use Antseed as an inference provider inside GenLayer Studio validators.
What GenLayer Studio is. Studio runs Intelligent Contract validators that consult LLMs to reach consensus. Each validator is configured with a provider entry that has a provider name, a plugin (one of openai-compatible / anthropic / google / ollama / custom), a model id, and a plugin_config with api_url and api_key_env_var.
How Antseed plugs in. Drop one JSON file per model into backend/node/create_nodes/default_providers/ with plugin: "openai-compatible" and api_url set to your Antseed gateway, and the gateway key in ANTSEED_API_KEY. Studio's openai-compatible plugin appends /v1/chat/completions automatically, so the gateway receives a standard OpenAI Chat request and selects the highest-ranked eligible offer under your routing policy. Mirror the existing LibertAI entry (PR #1526) - it is the closest analogue: an openai-compatible host with a hosted base URL replaced by your gateway.
Why a gateway, not the local buyer proxy. Studio's backend runs in Docker via genlayer up. The buyer proxy only accepts requests addressed to localhost or an IP address, so the container cannot use it. A gateway on a server or behind a tunnel works as is. For a gateway on the same computer, use http://host.docker.internal:8379: Mac/Windows Docker exposes the host under that name; on Linux add extra_hosts: ["host.docker.internal:host-gateway"] to the backend service and start the gateway with --host 0.0.0.0, on a network you trust.
Run Antseed first
Every integration needs an Antseed endpoint: a gateway, best on a small server so every tool on every machine can reach it, or the local buyer proxy (same computer only). One-time setup, a few minutes.
Before you start
Prerequisites
- GenLayer Studio cloned and running locally with
genlayer up(see https://docs.genlayer.com/developers/intelligent-contracts/tools/genlayer-studio)
Step 1
Install GenLayer Studio
- Gateway on this computer, Linux only - make `host.docker.internal` resolve from inside the backend container# docker-compose.yml - patch the backend (jsonrpc) service services: jsonrpc: extra_hosts: - "host.docker.internal:host-gateway"
Skip this with a gateway on a server or behind a tunnel, and on Mac and Windows, where Docker Desktop already exposes the host as
host.docker.internal. On Linux the gateway must also listen beyond loopback:antseed gateway start --host 0.0.0.0(plain HTTP, so only on a network you trust). Restart withgenlayer up --resetafter editing.
Step 2
Point GenLayer Studio at Antseed
Recommended: a gateway
Set api_url in each provider file to your gateway's address without /v1 (the plugin appends /v1/chat/completions), or http://host.docker.internal:8379 for a gateway on this computer.
Both schema files must be kept in sync - the backend uses one for validation, the frontend uses the other for the UI dropdown. This is exactly what PR #1526 did for LibertAI.
Step 3
Pick a model
Each provider JSON file defines exactly one model. Studio enumerates these into the validator-creation UI; pick model ids from the network-wide list (GET /v1/models on your gateway). To expose more models later, drop in more antseed_<model>.json files - no schema edit needed. To lock a file to one specific peer, set model to <peerId>@<service-id>.
The full list is every model on the network. Run GET /v1/models on your endpoint, antseed network browse, or open the live network page to see what's available right now.
Verify
Test it
- Restart Studio so it re-scans `default_providers/`genlayer up --reset
get_default_providers()inbackend/node/create_nodes/providers.pyreads every*.jsonin that folder once on boot, validates againstproviders_schema.json, and caches the result. Schema-validation errors abort startup with the offending file path - watch the logs. - In the Studio UI, create a new validator with provider "antseed"
You should see your
antseed_*.jsonmodel ids in the dropdown. Save and trigger a contract that callsgenlayer.eq_principle.prompt(…)- the request hits/v1/chat/completionson your gateway and is routed to the highest-ranked eligible offer under your routing policy. - Confirm the validator call hit Antseedcurl -s https://gateway.example.com/v1/key -H "Authorization: Bearer $ANTSEED_API_KEY"
Shows the key's usage so far. The console's Logs page lists each validator call with the seller that served it and its cost.
How GenLayer Studio talks to Antseed
- Wire format sent by GenLayer Studio:
OpenAI Chat Completions(hits/v1/chat/completionson your gateway or buyer proxy) - Best-fit services: any service whose
protocolsarray containsopenai-chat-completions. That's what the peer advertises as natively-supported - zero translation overhead, no transform edge cases. - How to check a peer: run
antseed network peer <peerId> --jsonand look atproviderServiceApiProtocols[provider].services[service]. The browse command exposes the same field per peer. - What happens when protocols don't match: Antseed's
@antseed/api-adaptertranslates between OpenAI Chat Completions and the service's native protocol on the fly, inside the buyer. So a request from GenLayer Studio can still reach a service that only advertisesanthropic-messages- just with a small transform step. - One known caveat: services whose only advertised protocol is
openai-responsesrequire streaming. If GenLayer Studio sends a non-streaming request and Antseed routes it to one of those services, the call fails withHTTP 400: Stream must be set to true. Pick a service whoseprotocolsincludesopenai-chat-completions(or another non-responses protocol) to avoid this.
If it goes wrong
Troubleshooting
Error validating file … antseed_*.jsonongenlayer upThe schema rejected your provider JSON. Most common cause: missing the if/then rule forprovider:antseed, so it falls through with the wrongplugin. Add the rule to *both*backend/.../providers_schema.jsonandfrontend/.../providers_schema.json. Rungenlayer up --resetafter editing.- Validator hangs, then errors with
Connection refusedtohost.docker.internal:8379The backend container can't reach a gateway on your computer. On Linux, addextra_hosts: ["host.docker.internal:host-gateway"]under the backend service indocker-compose.ymland start the gateway with--host 0.0.0.0. On Mac/Windows, confirm Docker Desktop is running and the gateway is up. Test from inside the container:docker compose exec jsonrpc curl http://host.docker.internal:8379/v1/models -H "Authorization: Bearer $ANTSEED_API_KEY". A server or tunnel gateway avoids all of this. - Pointing
api_urlat the local buyer proxy (host.docker.internal:8377) failsExpected: the buyer proxy only accepts requests addressed tolocalhostor an IP address, and never from other machines. Use a gateway instead. 401from the gatewayANTSEED_API_KEYin.envmust hold a gateway key from the console. Restart withgenlayer up --resetafter changing it.502 model_not_foundfrom a validator using e.g.kimi-k2.6No seller your routing policy allows currently advertises that model. CheckGET /v1/modelson your gateway. Either pick a model from that list or remove thatantseed_<model>.jsonfile.- First call after a restart takes 5–15 secondsAntseed opens a payment channel on the first request to a new peer (one Base-mainnet transaction). Subsequent calls reuse the channel. Pre-warm with one small chat completion to the gateway before triggering Studio.
Heads up
Caveats
- There is no hosted Antseed account: each operator runs their own gateway (or shares a team gateway) and funds its workspace wallet.
- Free services exist on the Antseed network (
in: 0, out: 0), but paid ones need funds in the gateway's workspace wallet: by card or USDC on Base, from the console's Wallet & Funding page.
Reference
Links
Same category