Set an agent's goal

PUT
/v1/agents/{id}/goal

Sets what the agent is for. Every scored conversation is charged at its price (see the quote): a goal read from a known outcome is free, a judged one is not. outcomeNames must be outcomes the published version declares, else 422 goal_outcome_unknown. The quiet windows and the re-score limit are this agent's own; leave them out to use the workspace's.

Requires an API key with the workspace:write scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The agent id.

Request Body

application/json
  1. body
goal*string

The goal in one sentence the judge can answer yes or no to, at most 500 characters.

Length1 <= length <= 500
outcomeNames?array<>

Outcomes of the published version that mean the goal was met; empty: every conversation is judged.

Itemsitems <= 24
Default[]
sampleRate?number

The share of conversations to score, above 0 up to 1. 1 scores every one.

Range0 < value <= 1
Default1
quietMinutes?

How long a text conversation stays quiet before it is scored: immediate for chat-style channels, asynchronous for slow ones such as email. null goes back to the workspace value.

maxScoresPerConversation?|

The most times one conversation is scored again after new activity, 1 to 20. null goes back to the workspace value.

Range1 <= value <= 20

Response Body

The goal after the change, with its price

application/json
  1. response
goal*string
Length1 <= length <= 500
outcomeNames?array<>
Itemsitems <= 24
Default[]
sampleRate?number
Range0 < value <= 1
Default1
quietMinutes?
maxScoresPerConversation?|
Range1 <= value <= 20
agentId*string
Formatuuid
evaluationId*string
Formatuuid
judgedBy*string
Value in"outcome""judge""outcome_or_judge"
knownOutcomes*array<>
quote*
enabled*boolean
Example Request
curl -X PUT "https://api.vlayers.ai/v1/agents/$AGENT_ID/goal" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "goal": "The caller booked an appointment",    "sampleRate": 0.5  }'
Example Response
{  "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",  "evaluationId": "0192f5f7-b0cf-7a1d-9c6d-7e8f90123456",  "goal": "The caller books a table",  "outcomeNames": [    "booked"  ],  "sampleRate": 1,  "judgedBy": "outcome_or_judge",  "knownOutcomes": [    {      "name": "booked",      "description": "A table was booked"    }  ],  "quote": {    "maxUsd": 0.0123,    "typicalUsd": 0.0031,    "maxScoresPerConversation": 3,    "sampleRate": 1,    "outcomeIsFree": true  },  "enabled": true}