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:

Permission	Used for
`project.agents.write`	Creating the agent definition
`project.api_keys.manage`	Creating the project API key
`project.conversations.create`	Storing the user message and starting the run
`project.runtime.manage`	Registering and removing the worker

Set the project slug for the commands below:

project.sh

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:

session.sh

export VERYFRONT_SESSION_TOKEN="<session-token>"

create-key.sh

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:

studio-key.sh

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}:

project-id.sh

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:

create-agent.sh

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:

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 its token. Veryfront returns the token 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

A worker run starts from a persisted user message. Create a conversation with one. Omit type: the API creates a chat conversation, which is the type for top-level runs.

create-conversation.sh

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:

start-run.sh

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:

claim.sh

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.

append-events.sh

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:

Event	Required fields	Optional fields
`TEXT_MESSAGE_START`	`messageId`, `contentId`, `role`
`TEXT_MESSAGE_CONTENT`	`messageId`, `contentId`, `delta`
`TEXT_MESSAGE_END`	`messageId`, `contentId`
`TOOL_CALL_START`	`toolCallId`, `toolCallName`	`parentMessageId`
`TOOL_CALL_ARGS`	`toolCallId`, `delta` (a JSON string fragment)
`TOOL_CALL_END`	`toolCallId`
`TOOL_CALL_RESULT`	`toolCallId`, `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:

succeed.sh

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:

verify.sh

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:

remove-worker.sh

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:

revoke-key.sh

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 example runs the whole flow in one script. It registers a worker, starts a run pinned to it, and claims the run within a timeout. It then asks a model through the AI gateway, appends the answer, finishes and verifies the run, and removes the worker. Install the dependencies and set the key, project slug, and agent ID from Before you start:

setup.sh

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:

agent.py

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:

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. Read the user message from the conversation in the claimed run instead of PROMPT in production code.

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.
EU models: Inference is EU-only by default. In GET /ai/v1/models, veryfront.processing is eu for models served in the EU. See Discover a model.
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

Interface	Operations
REST	Register a worker · Claim a run · Renew a run lease · Append run events · Succeed a run · Fail a run
GraphQL and MCP	Execution 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

Inspect logs and traces for the recorded run.
Run an agent on the hosted runtime instead.

Get started

APIs

REST API

GraphQL API

MCP API

Connect your own agent runtime

Before you start

Create a project API key with write access

Look up the project UUID

Create the agent definition

1. Register the worker

2. Store the user message

3. Start the run on your worker

4. Claim the run

5. Append events

6. Finish the run

7. Verify the result

8. Remove the worker

Python example

AI gateway calls from a worker

API references

Next steps

​Before you start

​Create a project API key with write access

​Look up the project UUID

​Create the agent definition

​1. Register the worker

​2. Store the user message

​3. Start the run on your worker

​4. Claim the run

​5. Append events

​6. Finish the run

​7. Verify the result

​8. Remove the worker

​Python example

​AI gateway calls from a worker

​API references

​Next steps

Before you start

Create a project API key with write access

Look up the project UUID

Create the agent definition

1. Register the worker

2. Store the user message

3. Start the run on your worker

4. Claim the run

5. Append events

6. Finish the run

7. Verify the result

8. Remove the worker

Python example

AI gateway calls from a worker

API references

Next steps