Run an agent

Create a conversation with a question, start an agent run, and follow the execution to its result.

Before you start

You need curl, jq, uuidgen, an API credential with permission to create and read runs, and a runnable project agent. This example uses triage-agent in support-assistant.

Create the agent and deploy its project to an available environment first. Set PROJECT_ID to the project's UUID and ENVIRONMENT_ID to that environment's UUID. Replace the project reference in the examples if you use another project.

1. Store the question

Call POST /conversations with an initial user message:

bash
set -e

curl --fail-with-body https://api.veryfront.com/conversations \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_reference": "support-assistant",
    "type": "chat",
    "title": "Support triage",
    "initial_message": {
      "role": "user",
      "parts": [{"type":"text","text":"I was charged twice. Which support team should handle this?"}]
    }
  }' > conversation.json

CONVERSATION_ID=$(jq -er '.id' conversation.json) || exit 1
export CONVERSATION_ID

The response contains the conversation ID. The message is stored, but the agent has not executed yet.

2. Start the run

Set the environment ID, then call POST /runs. The run reads its input from the conversation's stored messages.

bash
set -e

export PROJECT_ID="<PROJECT_ID>"
export ENVIRONMENT_ID="<ENVIRONMENT_ID>"
RUN_IDEMPOTENCY_KEY=$(uuidgen) || exit 1
export RUN_IDEMPOTENCY_KEY

jq -n --arg project "$PROJECT_ID" --arg conversation "$CONVERSATION_ID" \
  --arg environment "$ENVIRONMENT_ID" '{
  project_id: $project,
  target: {type: "agent", id: "triage-agent"},
  conversation_id: $conversation,
  execution: {runtime: {type: "environment", id: $environment}}
}' > agent-request.json

curl --fail-with-body https://api.veryfront.com/runs \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_IDEMPOTENCY_KEY" \
  --data-binary @agent-request.json > run.json

RUN_ID=$(jq -er '.id' run.json) || exit 1
export RUN_ID

Expect HTTP 202 and a run object with a top-level id. Keep RUN_ID for subsequent requests. Acceptance does not mean execution has finished.

Reuse the same idempotency key and request body when retrying this creation request. Use a new key for a separate run. A credential without read access receives only run_id and status. Use a credential with read access for this walkthrough.

3. Follow progress

Call GET /runs/{run_id}/stream to replay and follow the run's events:

bash
set -e

curl --fail-with-body --no-buffer "https://api.veryfront.com/runs/$RUN_ID/stream" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Accept: text/event-stream"

If the connection drops, reconnect with Last-Event-ID set to the last received SSE event ID. Do not create another run merely to reconnect.

4. Read the result

Call GET /runs/{run_id}:

bash
set -e

curl --fail-with-body "https://api.veryfront.com/runs/$RUN_ID" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" > result.json

jq '{status, output, error, conversation_id, input_message_id, output_message_id}' result.json

Repeat the read while status is pending or running. A completed run has status: "completed". Inspect output and the associated conversation messages to verify the response. For a failed run, inspect error and its events.

A waiting run needs the input or resume condition recorded for it. See run lifecycle before submitting a response or resuming execution.

Cancel active work

To stop an active run, call POST /runs/{run_id}/cancel, then read its status again. Reuse the cancellation key when retrying this request:

bash
set -e

CANCEL_IDEMPOTENCY_KEY="${CANCEL_IDEMPOTENCY_KEY:-$(uuidgen)}" || exit 1
export CANCEL_IDEMPOTENCY_KEY

curl --fail-with-body -X POST "https://api.veryfront.com/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Idempotency-Key: $CANCEL_IDEMPOTENCY_KEY"

API references