> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an agent

> Send a question to a project agent, follow its events, and read the result.

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](/docs/cloud/authentication), and a runnable project agent. This example uses `triage-agent` in `support-assistant`.

[Create the agent](/docs/cloud/agents) and [deploy its project](/docs/cloud/deploy) 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:

```bash title="create-conversation.sh" theme={null}
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.

```bash title="start-agent.sh" theme={null}
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:

```bash title="follow-run.sh" theme={null}
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}`:

```bash title="read-run.sh" theme={null}
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](/docs/cloud/conversation-api/durable-execution) 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:

```bash title="cancel-run.sh" theme={null}
curl -X POST "https://api.veryfront.com/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY"
```

## API references

* [Create a conversation](/docs/cloud/rest/api-reference/conversations/create-conversation), [create a run](/docs/cloud/rest/api-reference/runs/create-a-run), and [read a run](/docs/cloud/rest/api-reference/runs/get-a-run).
* [Execution GraphQL operations](/docs/cloud/graphql/apis/execution) and [MCP tools](/docs/cloud/mcp/apis/execution) expose their supported execution operations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.