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:
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_IDThe 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.
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_IDExpect 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:
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}:
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.jsonRepeat 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:
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
- Create a conversation, create a run, and read a run.
- Execution GraphQL operations and MCP tools expose their supported execution operations.