Connect your own agent runtime

Run a Veryfront agent in your own process, in any language, while Veryfront records the run, its events, and its result.

Your process acts as an agent worker: it registers once, claims runs that Veryfront admits for it, appends events with a run-scoped token, and finishes the run.

Before you start

You need curl, jq, uuidgen, and a Veryfront project. Project owners and admins have every permission this guide uses. A member with a custom role needs:

PermissionUsed for
project.agents.writeCreating the agent definition
project.api_keys.manageCreating the project API key
project.conversations.createStoring the user message and starting the run
project.runtime.manageRegistering and removing the worker

Set the project slug for the commands below:

bash
export PROJECT="<project-slug>"

Create a project API key with write access

The worker flow and the AI gateway need a key with the read and write scopes. A key created without scopes gets only read: it can list models and read runs, but registering a worker returns 403 with requires project.read with the write scope.

In Studio, open the project's API Keys panel, select Create API key, and enable Read and Write. Over REST, call POST /api-keys with a signed-in user session (see Authentication):

A signed-in user session token is the authToken cookie of a browser signed in to Veryfront. Export it first:

bash
export VERYFRONT_SESSION_TOKEN="<session-token>"
bash
curl --fail-with-body https://api.veryfront.com/api-keys \
  -H "Authorization: Bearer $VERYFRONT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"agent-worker\",\"project_reference\":\"$PROJECT\",\"scopes\":[\"read\",\"write\"]}" > key.json

export VERYFRONT_API_KEY=$(jq -er '.key' key.json)
export API_KEY_ID=$(jq -er '.id' key.json)

Veryfront returns the secret in key only once. Store it in a secret manager or an untracked .env file.

If you created the key in Studio, export the copied secret instead:

bash
export VERYFRONT_API_KEY="<project-key>"

Look up the project UUID

POST /runs takes the project UUID, not the slug. Read it with GET /projects/{project_reference}:

bash
export PROJECT_ID=$(curl --fail-with-body "https://api.veryfront.com/projects/$PROJECT" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" | jq -er '.id')

Create the agent definition

Create the agent definition in the project and set AGENT_ID to its ID. The definition names the agent. Your worker executes it. Over REST:

bash
export AGENT_ID="support-agent"

curl --fail-with-body "https://api.veryfront.com/projects/$PROJECT/agents" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"id\":\"$AGENT_ID\",\"name\":\"Support agent\",\"system_prompt\":\"Answer briefly.\"}"

1. Register the worker

Call POST /agent-workers/projects/{project_reference}/workers. Choose an implementation_kind that names your runtime and a worker_key that is unique to this process:

bash
export WORKER_KEY="python-openai-$(uuidgen | cut -c1-8 | tr 'A-Z' 'a-z')"

curl --fail-with-body "https://api.veryfront.com/agent-workers/projects/$PROJECT/workers" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"implementation_kind\":\"python-openai\",\"worker_key\":\"$WORKER_KEY\"}" > worker.json

WORKER_ID=$(jq -er '.worker.id' worker.json)
WORKER_TOKEN=$(jq -er '.token' worker.json)

The response contains the worker and a token shown only once.

Worker lifecycle:

  • Re-register: Registering the same worker_key again returns the same worker ID with a new token. Re-register after a restart instead of storing the token.
  • Remove: DELETE /agent-workers/workers/{worker_id} disables the worker and invalidates its tokens. A claim then returns 401. The worker keeps its ID, and registering the same worker_key enables it again with a new token.
  • Claim order: A worker claims the oldest waiting run for its implementation_kind. Without worker_key pinning, any active worker of that kind in the project can claim a run.

2. Store the user message

For this conversation-backed run, store a user message first. Omit type to create a chat conversation for the top-level run. Saving the message does not start execution.

bash
curl --fail-with-body https://api.veryfront.com/conversations \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"project_reference\": \"$PROJECT\",
    \"initial_message\": {\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"text\":\"Summarize my open tickets.\"}]}
  }" > conversation.json

CONVERSATION_ID=$(jq -er '.id' conversation.json)

For a later turn, append the user message with POST /conversations/{conversation_id}/messages before you start the run.

3. Start the run on your worker

Call POST /runs with project_id, conversation_id, and config.agent_admission. Set mode to worker, implementation_kind to the value your worker registered with, and worker_key to pin the run to this worker:

bash
curl --fail-with-body https://api.veryfront.com/runs \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"project_id\": \"$PROJECT_ID\",
    \"conversation_id\": \"$CONVERSATION_ID\",
    \"target\": {\"type\":\"agent\",\"id\":\"$AGENT_ID\"},
    \"config\": {\"agent_admission\": {\"mode\":\"worker\",\"implementation_kind\":\"python-openai\",\"worker_key\":\"$WORKER_KEY\"}}
  }" > run.json

jq -r '.id' run.json

Veryfront accepts the run with 202 and holds it until the pinned worker claims it. Without worker_key, any worker of the same kind can claim it.

execution.runtime overrides don't apply to agents. Use agent_admission instead.

4. Claim the run

Poll POST /agent-workers/workers/{worker_id}/claim with the worker token, and stop after a timeout:

bash
abandon_run() {
  echo "$1" >&2
  curl --fail-with-body -X POST "https://api.veryfront.com/runs/$(jq -er '.id' run.json)/cancel" \
    -H "Authorization: Bearer $VERYFRONT_API_KEY" -H "Idempotency-Key: $(uuidgen)"
  curl --fail-with-body -X DELETE "https://api.veryfront.com/agent-workers/workers/$WORKER_ID" \
    -H "Authorization: Bearer $VERYFRONT_API_KEY"
  exit 1
}

rm -f claim.json
DEADLINE=$((SECONDS + 60))
until [ $SECONDS -ge $DEADLINE ]; do
  curl --fail-with-body "https://api.veryfront.com/agent-workers/workers/$WORKER_ID/claim" \
    -H "Authorization: Bearer $WORKER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"lease_duration_seconds":60}' > claim.json || abandon_run "Claim failed: $(cat claim.json)"
  jq -e '.run != null' claim.json > /dev/null && break
  sleep 2
done
jq -e '.run != null' claim.json > /dev/null 2>&1 || abandon_run "No run arrived within 60s"

WORKER_RUN_ID=$(jq -er '.run.run_id' claim.json)
RUN_ID=$(jq -er '.run.canonical_run_id' claim.json)
EVENT_TOKEN=$(jq -er '.credentials.run_event_token' claim.json)
TERMINAL_TOKEN=$(jq -er '.credentials.run_terminal_token' claim.json)
AUTH_TOKEN=$(jq -er '.credentials.auth_token' claim.json)

run is null while nothing is waiting. On an HTTP error or a timeout, abandon_run cancels the waiting run and removes the worker, because the run is pinned to this worker's key. If that happens, check that AGENT_ID exists in the project and that implementation_kind and worker_key match the worker. The claimed run includes the conversation and message IDs, so your code can read the user message.

Renew the lease with POST /agent-workers/workers/{worker_id}/runs/{run_id}/lease while the run takes longer than the lease. That path takes the worker run ID (WORKER_RUN_ID), not canonical_run_id. The Runs endpoints below use RUN_ID. A renewal that returns run: null means the lease is gone.

5. Append events

Append events with POST /runs/{run_id}/events and the run_event_token. API keys can't append events. Send up to 100 events per request.

bash
curl --fail-with-body "https://api.veryfront.com/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $EVENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"events":[
    {"type":"TOOL_CALL_START","toolCallId":"t1","toolCallName":"list_tickets"},
    {"type":"TOOL_CALL_ARGS","toolCallId":"t1","delta":"{\"status\":\"open\"}"},
    {"type":"TOOL_CALL_END","toolCallId":"t1"},
    {"type":"TOOL_CALL_RESULT","toolCallId":"t1","messageId":"r1","content":"3 open tickets","isError":false},
    {"type":"TEXT_MESSAGE_START","messageId":"m1","contentId":"c1","role":"assistant"},
    {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","contentId":"c1","delta":"You have 3 open tickets."},
    {"type":"TEXT_MESSAGE_END","messageId":"m1","contentId":"c1"}
  ]}'

Event fields use camelCase:

EventRequired fieldsOptional fields
TEXT_MESSAGE_STARTmessageId, contentId, role
TEXT_MESSAGE_CONTENTmessageId, contentId, delta
TEXT_MESSAGE_ENDmessageId, contentId
TOOL_CALL_STARTtoolCallId, toolCallNameparentMessageId
TOOL_CALL_ARGStoolCallId, delta (a JSON string fragment)
TOOL_CALL_ENDtoolCallId
TOOL_CALL_RESULTtoolCallId, isError (true, false, or null)messageId, content, role (tool)

A TOOL_CALL_RESULT without isError is rejected with 400. Veryfront writes RUN_STARTED and RUN_FINISHED itself. See the run event format for all event types.

6. Finish the run

Call POST /runs/{run_id}/succeed with the run credentials:

bash
curl --fail-with-body "https://api.veryfront.com/runs/$RUN_ID/succeed" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "X-Veryfront-Run-Terminal-Token: $TERMINAL_TOKEN" \
  -H "Idempotency-Key: $RUN_ID-succeed" \
  -H "Content-Type: application/json" \
  -d '{"output":{"text":"You have 3 open tickets."}}'

Both terminal calls require an Idempotency-Key header. Reuse the same key when you retry. Call POST /runs/{run_id}/fail with {"error":{"code":"worker_error","message":"..."}} instead when your code fails.

7. Verify the result

Read the run with GET /runs/{run_id} and its events with GET /runs/{run_id}/events:

bash
curl --fail-with-body "https://api.veryfront.com/runs/$RUN_ID" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" | jq '{status, output}'

curl --fail-with-body "https://api.veryfront.com/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" | jq -r '.data[].event_type'

status is completed and output holds the result you sent. The events list is paged: each item in data has an event_type (the type you appended), and page_info holds the cursor for the next page. Studio shows the run and its events under Runs like any hosted run.

8. Remove the worker

Disable the worker when the process stops:

bash
curl --fail-with-body -X DELETE "https://api.veryfront.com/agent-workers/workers/$WORKER_ID" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY"

If you created the key only for this guide, revoke it. In Studio, delete it in the API Keys panel. If you created it over REST, delete it with the same session token:

bash
curl --fail-with-body -X DELETE "https://api.veryfront.com/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $VERYFRONT_SESSION_TOKEN"

A run that no worker claims keeps waiting. Cancel it with POST /runs/{run_id}/cancel, an API key, and an Idempotency-Key header.

Python example

The python-openai-agent script registers a worker and claims a run pinned to it. It calls the AI gateway, records the answer, verifies completion and removes the worker.

Install the dependencies and set the key, project slug, and agent ID from Before you start:

bash
pip install httpx openai
export VERYFRONT_API_KEY="<project-key>"
export VERYFRONT_PROJECT="<project-slug>"
export VERYFRONT_AGENT="<agent-id>"
export VERYFRONT_MODEL="openai/gpt-5.4-mini"

VERYFRONT_MODEL takes any Chat Completions model ID from GET /ai/v1/models. Then run python agent.py:

python
import os, sys, time, uuid

import httpx
from openai import OpenAI

API = os.environ.get("VERYFRONT_API_URL", "https://api.veryfront.com").rstrip("/")
API_KEY = os.environ["VERYFRONT_API_KEY"]
PROJECT = os.environ["VERYFRONT_PROJECT"]
AGENT = os.environ["VERYFRONT_AGENT"]
MODEL = os.environ.get("VERYFRONT_MODEL", "openai/gpt-5.4-mini")
KIND, LEASE_SECONDS, CLAIM_TIMEOUT_SECONDS = "python-openai", 60, 60
PROMPT = "In one sentence, what is an agent worker?"


def call(api, method, path, token, **kwargs):
    headers = {"Authorization": f"Bearer {token}", **kwargs.pop("headers", {})}
    response = api.request(method, path, headers=headers, **kwargs)
    if response.status_code >= 400:
        raise RuntimeError(f"{method} {path} returned {response.status_code}: {response.text[:500]}")
    return response.json() if response.content else {}


def start_run(api, worker_key):
    project_id = call(api, "GET", f"/projects/{PROJECT}", API_KEY)["id"]
    message = {"role": "user", "parts": [{"type": "text", "text": PROMPT}]}
    conversation = call(api, "POST", "/conversations", API_KEY,
                        json={"project_reference": PROJECT, "initial_message": message})
    admission = {"mode": "worker", "implementation_kind": KIND, "worker_key": worker_key}
    run = call(api, "POST", "/runs", API_KEY, headers={"Idempotency-Key": str(uuid.uuid4())},
               json={"project_id": project_id, "conversation_id": conversation["id"],
                     "target": {"type": "agent", "id": AGENT},
                     "config": {"agent_admission": admission}})
    return run["id"]


def claim_run(api, worker):
    deadline = time.monotonic() + CLAIM_TIMEOUT_SECONDS
    while time.monotonic() < deadline:
        claim = call(api, "POST", f"/agent-workers/workers/{worker['worker']['id']}/claim",
                     worker["token"], json={"lease_duration_seconds": LEASE_SECONDS})
        if claim.get("run"):
            return claim
        time.sleep(2)
    raise RuntimeError(f"No run arrived within {CLAIM_TIMEOUT_SECONDS}s. Check VERYFRONT_AGENT.")


def renew_lease(api, worker, claim):
    path = f"/agent-workers/workers/{worker['worker']['id']}/runs/{claim['run']['run_id']}/lease"
    if not call(api, "POST", path, worker["token"], json={"lease_duration_seconds": LEASE_SECONDS}).get("run"):
        raise RuntimeError("The run lease expired before the model call.")


def ask_model():
    # The gateway refuses a run's auth_token, so model calls use the API key.
    llm = OpenAI(base_url=f"{API}/ai/v1", api_key=API_KEY)
    reply = llm.chat.completions.create(model=MODEL, messages=[{"role": "user", "content": PROMPT}])
    return reply.choices[0].message.content or ""


def append_answer(api, run_id, event_token, text):
    ids = {"messageId": str(uuid.uuid4()), "contentId": str(uuid.uuid4())}
    events = [{"type": "TEXT_MESSAGE_START", **ids, "role": "assistant"},
              {"type": "TEXT_MESSAGE_CONTENT", **ids, "delta": text},
              {"type": "TEXT_MESSAGE_END", **ids}]
    call(api, "POST", f"/runs/{run_id}/events", event_token, json={"events": events})


def finish_run(api, run_id, creds, outcome, body):
    headers = {"X-Veryfront-Run-Terminal-Token": creds["run_terminal_token"],
               "Idempotency-Key": f"{run_id}-{outcome}"}
    call(api, "POST", f"/runs/{run_id}/{outcome}", creds["auth_token"], headers=headers, json=body)


def main():
    worker_key = f"{KIND}-{uuid.uuid4().hex[:8]}"
    with httpx.Client(base_url=API, timeout=30) as api:
        worker = call(api, "POST", f"/agent-workers/projects/{PROJECT}/workers", API_KEY,
                      json={"implementation_kind": KIND, "worker_key": worker_key})
        print(f"Registered worker {worker_key}")
        try:
            run_id = start_run(api, worker_key)
            print(f"Started run {run_id}")
            try:
                claim = claim_run(api, worker)
            except Exception:
                # The run is pinned to this worker key; cancel it so it doesn't wait forever.
                call(api, "POST", f"/runs/{run_id}/cancel", API_KEY,
                     headers={"Idempotency-Key": f"{run_id}-cancel"})
                raise
            creds = claim["credentials"]
            try:
                renew_lease(api, worker, claim)
                text = ask_model()
                append_answer(api, run_id, creds["run_event_token"], text)
                finish_run(api, run_id, creds, "succeed", {"output": {"text": text}})
            except Exception as error:
                failure = {"code": "worker_error", "message": str(error)[:4000] or "Worker failed"}
                try:
                    finish_run(api, run_id, creds, "fail", {"error": failure})
                except RuntimeError:
                    # The lease is gone, so the run credentials no longer work.
                    call(api, "POST", f"/runs/{run_id}/cancel", API_KEY,
                         headers={"Idempotency-Key": f"{run_id}-cancel"})
                raise
            run = call(api, "GET", f"/runs/{run_id}", API_KEY)
            events = call(api, "GET", f"/runs/{run_id}/events", API_KEY)
            print(f"Run status: {run['status']}")
            print("Run events: " + ", ".join(e["event_type"] for e in events["data"]))
        finally:
            call(api, "DELETE", f"/agent-workers/workers/{worker['worker']['id']}", API_KEY)
            print(f"Removed worker {worker_key}")


if __name__ == "__main__":
    try:
        main()
    except RuntimeError as error:
        sys.exit(f"Error: {error}")

Expected output, with a different run ID each time:

text
Registered worker python-openai-60196376
Started run 74b087fc-3523-473a-968f-7dea0214e48e
Run status: completed
Run events: AGENT_RUN_REQUEST_ENQUEUED, RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, RUN_FINISHED
Removed worker python-openai-60196376

The example renews the lease once before the model call and assumes that call finishes within LEASE_SECONDS. For longer work, renew the lease on a timer until the run ends. The run is pinned to this process's worker_key, so no other worker can take it over. If the lease expires and the fail call is refused, the sample cancels the run. To resume work after a restart instead, keep a stable worker_key and re-register it.

In production, read the user message from the claimed run's conversation instead of using PROMPT.

AI gateway calls from a worker

  • Credential: The gateway doesn't accept the run's auth_token. Call it with the project API key.
  • Project header: A project key identifies its project, so the gateway needs no x-veryfront-project-reference header. An account key needs that header to select a project. Without it the gateway returns gateway_project_required.
  • Serving location: Allowed deployments depend on deployment settings and stored project restrictions. In GET /ai/v1/models, veryfront.processing is eu for models served in the EU. See Discover a model and serving restrictions.
  • Usage: Gateway usage is billed to the key's project and isn't attributed to the run. Read it in Studio under API Keys, or with GET /api-keys/{id}/usage and a signed-in user session. A project key gets 403 on that endpoint, and /account/usage always needs a signed-in user.

API references

InterfaceOperations
RESTRegister a worker · Claim a run · Renew a run lease · Append run events · Succeed a run · Fail a run
GraphQL and MCPExecution GraphQL operations and MCP tools create conversations and runs and read results. They also append run events (GraphQL, MCP) and record run heartbeats (GraphQL, MCP). Worker registration, claims and lease renewal are REST only.

Next steps