Skip to main content

Registering External Services & Pricing

Not everything your workflows call is an LLM. A service is any non-LLM external API your pipeline uses — a text-to-speech provider, an image generator, an avatar renderer. In the employees metaphor, services are the outside vendors your agents work with. The service registry is where you define those vendors and how they're billed, so workflows can call them and so their usage can be costed.

What you register​

A service is identified by a single slug — there's no separate display name — normalised to lowercase snake_case and immutable once created. You provide:

  • an API URL template, which may contain variables in double-curly-brace syntax, e.g. https://api.abc.com/endpoint/{{VIDEO_ID}};
  • a billing unit — one of seconds, bytes, megabytes, gigabytes, tokens, one-million tokens, characters, one-million characters, or requests;
  • a base cost and the unit quantity it applies to (e.g. a cost per 1,000 characters).

The billing unit and pricing are what let Circus turn reported usage into dollars in your logs and analytics — the same way model pricing does for agents.

Templates get filled in later​

The URL template's variables aren't given values here; that happens when you assign the service inside a service configuration set (the next article). The registry just declares the service and its shape; the configuration supplies the concrete values.

Disabling and deleting​

Each service has an enabled/disabled status. Disabling a service cascades: the service configurations that use it become invalid, and workflows depending on those configurations become unavailable — the same dependency rule that governs the rest of the chain. Deleting is different: it prompts you to confirm, showing which service configurations and workflows use the service, then removes the service and strips its assignments out of those configurations. Deletion doesn't disable anything — it simply pulls the service out, which may cause a later workflow run to fail. Guarding against that is up to you.