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, an API credential, 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 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

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

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

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

export ENVIRONMENT_ID="<ENVIRONMENT_ID>"

jq -n --arg conversation "$CONVERSATION_ID" --arg environment "$ENVIRONMENT_ID" '{
  kind: "agent",
  owner: {kind: "conversation", id: $conversation},
  request: {
    mode: "agent",
    input: {
      agent_id: "triage-agent",
      source_target_kind: "environment",
      runtime_target_kind: "environment",
      target_environment_id: $environment
    }
  }
}' | curl --fail-with-body https://api.veryfront.com/runs \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- > run.json

export RUN_ID=$(jq -er '.run.run_id' run.json)

Expect HTTP 202 and accepted: true. Keep RUN_ID for subsequent requests. Acceptance does not mean execution has finished.

3. Follow progress

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

follow-run.sh

curl --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

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, message_id}' result.json

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

curl -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