# Set an agent's goal

Source: https://docs.vlayers.ai/reference/agents/set-agent-goal

`PUT /v1/agents/{id}/goal` · scope `workspace:write`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `goal` | body | string | yes | The goal in one sentence the judge can answer yes or no to, at most 500 characters. |
| `outcomeNames` | body | string[] | no | Outcomes of the published version that mean the goal was met; empty: every conversation is judged. |
| `sampleRate` | body | number | no | The share of conversations to score, above 0 up to 1. 1 scores every one. |
| `quietMinutes` | body | object | no | 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` | body | integer | no | The most times one conversation is scored again after new activity, 1 to 20. `null` goes back to the workspace value. |

## Request

cURL:

```bash
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
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { goal } = await voicelayer.agents.setGoal('<agent-id>', {
  goal: 'The caller booked an appointment',
  sampleRate: 0.5
});
console.log(goal);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.agents.set_goal(
    "<agent-id>",
    goal="The caller booked an appointment",
    sample_rate=0.5,
)
print(result.goal)
```

## Response `200`

```json
{
  "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
}
```
