Build on Agentyk

Quickstart

If you already use the OpenAI SDK, you are three lines away: change the base URL, drop in your agk_ key, pick a model.

curl https://api.agentyk.xyz/v1/chat/completions \
  -H "Authorization: Bearer $AGENTYK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agentyk-jaguar-1",
    "messages": [
      { "role": "user", "content": "Summarise the EU AI Act in three points." }
    ]
  }'

The surface

A focused, OpenAI-compatible /v1 surface plus self-serve account and key management.

Why build on Agentyk

Making the output a guarantee

Most of the time you do not want the model's opinion about the format — you want a value from a fixed set, and you want it every time. Three mechanisms can narrow what comes back, and they are not interchangeable. Only one of them is a guarantee.

# Bind each record's id to its OWN rule, so the label can only land
# on the record it belongs to.
root     ::= "[" rec-1041 "," rec-1042 "]"
rec-1041 ::= "{\"id\":\"T-1041\",\"label\":" label "}"
rec-1042 ::= "{\"id\":\"T-1042\",\"label\":" label "}"
label    ::= "\"billing\"" | "\"bug\"" | "\"feature-request\""

GRAMMAR = open("tickets.gbnf").read()

resp = client.chat.completions.create(
    model="jaguar-express",
    max_tokens=80,
    messages=[{"role": "user", "content":
        "T-1041: 'I was charged twice this month.' "
        "T-1042: 'The export button does nothing.' Label each ticket."}],
    extra_body={"grammar": GRAMMAR},   # not an OpenAI field — send it raw
)

# [{"id":"T-1041","label":"billing"},{"id":"T-1042","label":"bug"}]
#
# There is no other possible response. The set of strings the model is
# allowed to emit is the set you wrote, and it is checked token by token.

# TRAP. Every string here is permitted — so every PAIRING is permitted too.
root   ::= "[" record ("," record)* "]"
record ::= "{\"id\":" id ",\"label\":" label "}"
id     ::= "\"T-1041\"" | "\"T-1042\""
label  ::= "\"billing\"" | "\"bug\"" | "\"feature-request\""

# This grammar happily accepts all of the following:
#   [{"id":"T-1041","label":"bug"},{"id":"T-1041","label":"bug"}]   same id twice
#   [{"id":"T-1042","label":"billing"},{"id":"T-1041","label":"bug"}]   swapped
#
# A global list of permitted strings guarantees only that each string is
# permitted somewhere. If two fields have to agree, the rule that emits one
# must be the rule that emits the other.

root ::= yes_or_no          # ✗ underscore
yes_or_no ::= "yes" | "no"  #   -> HTTP 400, and the body does not mention the grammar

root ::= yes-or-no          # ✓ letters, digits and hyphens only
yes-or-no ::= "yes" | "no"

Structured output, and the thing it does not do

response_format accepts json_schema with strict: true, not only json_object. It is the right tool when you need a predictable object to deserialise — and the wrong tool, on its own, when you need exact string content.

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "ticket",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "id":    { "type": "string" },
        "label": { "type": "string" }
      },
      "required": ["id", "label"],
      "additionalProperties": false
    }
  }
}

// Returns, reliably:   { "id": "T-1041", "label": "Billing Issue" }
//
// Both keys present, both strings, nothing extra — the schema did its job.
// And "Billing Issue" is not one of your three labels, because you never
// told the schema what the labels were. Declaring
//     "label": { "type": "string", "enum": ["billing","bug","feature-request"] }
// changes that answer to "billing", because an enum becomes a real
// constraint. A bare "type": "string" never is.

Defaults worth knowing

We set no sampling parameters on your behalf. A request that sends none is served with the tier's own built-in defaults, and those are tuned for open-ended generation rather than for repeatability.

Constrained tool calls, and the two headers that tell you the truth

Set agentyk_strict_tools: true on a non-streaming call that forces exactly one function, and the function's parameter schema — enum and pattern included — is enforced on the arguments while they are generated, instead of being a suggestion the model usually follows.

resp = client.chat.completions.with_raw_response.create(
    model="jaguar-express",
    max_tokens=2500,         # ~1.5x the longest output your prompt can produce
    messages=messages,
    tools=tools,             # exactly one function
    tool_choice={"type": "function", "function": {"name": "classify"}},
    extra_body={"agentyk_strict_tools": True},
)

mode = resp.headers.get("X-Agentyk-Strict-Tools")         # enforced | fallback
why  = resp.headers.get("X-Agentyk-Strict-Tools-Reason")  # only when fallback
if mode != "enforced":
    logger.warning("strict tools fell back: %s", why)

completion = resp.parse()

What usage costs

Plans are flat monthly; metered usage on the API is billed per unit on top. These are the published rates — GET /api/credits/rates returns the same card, complete and machine-readable, for every tier.

Live transcription

Agentyk Scribe Live streams text back while the audio is still being spoken. Open one WebSocket per speaker, send raw PCM at real time, and read partials within about half a second; opt in to refine and the transcript you hold at the end is the same one a batch request would have returned.

import asyncio, json, wave, websockets

URL = "wss://api.agentyk.xyz/v1/realtime?model=agentyk-scribe-live-1.0"

async def main():
    async with websockets.connect(URL, additional_headers={"Authorization": "Bearer agk_..."}) as ws:
        await ws.send(json.dumps({"type": "start", "language": "de", "refine": True}))

        async def read():
            async for m in ws:
                f = json.loads(m)
                if f["type"] == "partial":        print("...", f["text"])   # provisional; replaces the previous partial
                elif f["type"] == "final":        print("   ", f["text"])   # committed
                elif f["type"] == "transcript":   print("== ", f["text"])   # the whole session, batch accuracy
                elif f["type"] in ("done", "error", "busy"):
                    print(f); return

        reader = asyncio.create_task(read())
        w = wave.open("meeting.wav", "rb")           # 16 kHz, mono, 16-bit PCM
        while frames := w.readframes(1600):          # 100 ms per frame, sent at real time
            await ws.send(frames)
            await asyncio.sleep(0.1)
        await ws.send(json.dumps({"type": "stop"}))
        await reader

asyncio.run(main())