Set an agent's 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.
apiKeyAuthorizationBearer <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.
id*stringThe agent id.
application/json- body
goal*stringThe goal in one sentence the judge can answer yes or no to, at most 500 characters.
1 <= length <= 500outcomeNames?array<>Outcomes of the published version that mean the goal was met; empty: every conversation is judged.
items <= 24[]sampleRate?numberThe share of conversations to score, above 0 up to 1. 1 scores every one.
0 < value <= 11quietMinutes?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.
1 <= value <= 20The goal after the change, with its price
application/json- response
goal*string1 <= length <= 500outcomeNames?array<>items <= 24[]sampleRate?number0 < value <= 11quietMinutes?maxScoresPerConversation?|1 <= value <= 20agentId*stringuuidevaluationId*stringuuidjudgedBy*string"outcome""judge""outcome_or_judge"knownOutcomes*array<>quote*enabled*booleancurl -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 }'{ "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}