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:

create-conversation.sh

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": "project_agent",
    "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.

start-agent.sh

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:

follow-run.sh

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

read-run.sh

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

Use POST /runs/{run_id}/cancel if you need to stop an active run, then read its status again:

cancel-run.sh

set -e

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

API references

Create a conversation, create a run, and read a run.
Execution GraphQL operations and MCP tools expose their supported execution operations.

Get started

APIs

REST API

GraphQL API

MCP API

Before you start

1. Store the question

2. Start the run

3. Follow progress

4. Read the result

Cancel active work

API references

​Before you start

​1. Store the question

​2. Start the run

​3. Follow progress

​4. Read the result

​Cancel active work

​API references

Before you start

1. Store the question

2. Start the run

3. Follow progress

4. Read the result

Cancel active work

API references