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:
Set the project slug for the commands below:
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:
export VERYFRONT_SESSION_TOKEN="<session-token>"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:
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}:
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:
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 a token shown only once.
Worker lifecycle:
- Re-register: Registering the same
worker_keyagain 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 returns401. The worker keeps its ID, and registering the sameworker_keyenables it again with a new token. - Claim order: A worker claims the oldest waiting run for its
implementation_kind. Withoutworker_keypinning, 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.
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:
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.jsonVeryfront 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:
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.
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:
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:
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:
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:
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:
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:
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:
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-60196376The 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-referenceheader. An account key needs that header to select a project. Without it the gateway returnsgateway_project_required. - Serving location: Allowed deployments depend on deployment settings and stored project restrictions. In
GET /ai/v1/models,veryfront.processingiseufor 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}/usageand a signed-in user session. A project key gets403on that endpoint, and/account/usagealways needs a signed-in user.
API references
Next steps
- Inspect logs and traces for the recorded run.
- Run an agent on the hosted runtime instead.