# Replace an agent's definition > PUT /v1/agents/{agent_id}/definition Put a definition back onto an agent: its prompt, configuration, voice, languages, analysis, and the tools and knowledge bases it names. On a published agent the change is live at once, as an edit in the console is, until the next publish freezes it as a version. Needs `agents:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `definition` | object | Yes | The agent's new definition. Its kind and direction must be the agent's own. | | `name` | string or null | No | A new name, if it is to change. | ## Answer `200` with [AgentWritten](/reference/objects/AgentWritten). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The project already has an agent with that name, or it is frozen. | | `422` | The definition cannot be read, holds something an agent may not, or is for another kind or direction of agent. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Replace an agent's definition. On a published agent the change is live at once. With a live key. curl -sS --fail-with-body -X PUT "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }' ``` **JavaScript** ```js // Replace an agent's definition. On a published agent the change is live at once. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition", { method: "PUT", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Replace an agent's definition. On a published agent the change is live at once. With a live key. # pip install httpx import os import httpx response = httpx.put( "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking.", }, "references": {}, }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Replace an agent's definition. On a published agent the change is live at once. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }`) request, err := http.NewRequest("PUT", "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") response, err := http.DefaultClient.Do(request) if err != nil { panic(err) } defer response.Body.Close() body, _ := io.ReadAll(response.Body) if response.StatusCode >= 400 { fmt.Fprintln(os.Stderr, string(body)) os.Exit(1) } fmt.Println(string(body)) } ``` **Java** ```java // Replace an agent's definition. On a published agent the change is live at once. With a live key. import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { String body = """ { "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PUT", HttpRequest.BodyPublishers.ofString(body)) .build(); // HTTP/1.1: on a plain-http address Java's default asks to upgrade, which not every // server allows. HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { System.err.println(response.body()); System.exit(1); } System.out.println(response.body()); } } ``` **C#** ```csharp // Replace an agent's definition. On a published agent the change is live at once. With a live key. using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Put, "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition") { Content = new StringContent( """ { "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } } """, Encoding.UTF8, "application/json"), }; var response = await client.SendAsync(request); var body = await response.Content.ReadAsStringAsync(); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(body); return 1; } Console.WriteLine(body); return 0; ``` **PHP** ```php "PUT", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "definition" => [ "format" => "agently.agent/1", "agent" => [ "name" => "Aigently front desk", "kind" => "custom", "direction" => "outbound", "system_prompt" => "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking.", ], "references" => new \stdClass(), ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ```