Create Agent By Template

Create a new Agent from a template

curl --request POST \
  --url https://api.trugen.ai/v1/ext/agentbytemplate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "avatar_ids": [
    "1e4ea106",
    "665a1170"
  ],
  "template_id": "76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55"
}
'

import requests

url = "https://api.trugen.ai/v1/ext/agentbytemplate"

payload = {
    "avatar_ids": ["1e4ea106", "665a1170"],
    "template_id": "76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    avatar_ids: ['1e4ea106', '665a1170'],
    template_id: '76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55'
  })
};

fetch('https://api.trugen.ai/v1/ext/agentbytemplate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trugen.ai/v1/ext/agentbytemplate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'avatar_ids' => [
        '1e4ea106',
        '665a1170'
    ],
    'template_id' => '76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trugen.ai/v1/ext/agentbytemplate"

	payload := strings.NewReader("{\n  \"avatar_ids\": [\n    \"1e4ea106\",\n    \"665a1170\"\n  ],\n  \"template_id\": \"76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trugen.ai/v1/ext/agentbytemplate")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"avatar_ids\": [\n    \"1e4ea106\",\n    \"665a1170\"\n  ],\n  \"template_id\": \"76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trugen.ai/v1/ext/agentbytemplate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"avatar_ids\": [\n    \"1e4ea106\",\n    \"665a1170\"\n  ],\n  \"template_id\": \"76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "51ed8d70-9379-422f-aed4-f9f2b293ba4a",
  "message": "Agent created successfully"
}

{
  "error": "Invalid request body"
}

{
  "error": "Unauthorized: not a valid authorization api key"
}

{
  "error": "Failed to fetch template/avatar"
}

POST

ext

agentbytemplate

Create a new Agent from a template

curl --request POST \
  --url https://api.trugen.ai/v1/ext/agentbytemplate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "avatar_ids": [
    "1e4ea106",
    "665a1170"
  ],
  "template_id": "76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55"
}
'

import requests

url = "https://api.trugen.ai/v1/ext/agentbytemplate"

payload = {
    "avatar_ids": ["1e4ea106", "665a1170"],
    "template_id": "76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    avatar_ids: ['1e4ea106', '665a1170'],
    template_id: '76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55'
  })
};

fetch('https://api.trugen.ai/v1/ext/agentbytemplate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trugen.ai/v1/ext/agentbytemplate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'avatar_ids' => [
        '1e4ea106',
        '665a1170'
    ],
    'template_id' => '76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trugen.ai/v1/ext/agentbytemplate"

	payload := strings.NewReader("{\n  \"avatar_ids\": [\n    \"1e4ea106\",\n    \"665a1170\"\n  ],\n  \"template_id\": \"76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trugen.ai/v1/ext/agentbytemplate")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"avatar_ids\": [\n    \"1e4ea106\",\n    \"665a1170\"\n  ],\n  \"template_id\": \"76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trugen.ai/v1/ext/agentbytemplate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"avatar_ids\": [\n    \"1e4ea106\",\n    \"665a1170\"\n  ],\n  \"template_id\": \"76d9ff1d-b1d5-4dee-9b9a-d4c4d58c9c55\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "51ed8d70-9379-422f-aed4-f9f2b293ba4a",
  "message": "Agent created successfully"
}

{
  "error": "Invalid request body"
}

{
  "error": "Unauthorized: not a valid authorization api key"
}

{
  "error": "Failed to fetch template/avatar"
}

Create a new agent from a saved template. The template supplies the shared configuration (prompt, knowledge, guardrails, LLM, TTS); you pass in the per-agent overrides (avatar, email, per-user context).

Why templates

Templates keep configuration consistent across many agents. If you run 50 agents that share the same behavior but differ in avatar and per-user context, define the behavior once as a template and spawn agents from it. The new agent inherits everything attached to the template, including its knowledge bases, tools, MCPs, and guardrails. You don’t need to pass any of that again in this request.

Required fields

template_id: the template to instantiate from
avatar_key_id: the visual identity for this specific agent

Optional fields

email: used for external meetings as the meeting invite identity
context_override: inject per-agent context that will be appended to the shared system prompt

Example

curl --request POST \
  --url https://api.trugen.ai/v1/ext/agentbytemplate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "template_id": "tpl_abc123",
    "avatar_key_id": "665a1170",
    "email": "priya@example.com",
    "context_override": "User is on the Growth plan, 30 seats, last ticket about SSO."
  }'

Response:

{
  "id": "agt_98765example",
  "message": "Agent created successfully"
}

Common patterns

Per-customer rollout

Loop over your customer list; for each customer, spin up a template-derived agent with per-customer context:

for (const customer of customers) {
  await fetch("https://api.trugen.ai/v1/ext/agentbytemplate", {
    method: "POST",
    headers: {
      "x-api-key": process.env.TRUGEN_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: "tpl_customer_support",
      avatar_key_id: "665a1170",
      email: `support-${customer.slug}@meetings.trugen.ai`,
      context_override: `Customer: ${customer.name}. Plan: ${customer.plan}.`,
    }),
  });
}

Next steps

Authorizations

x-api-key

string

header

required

Body

application/json

avatar_ids

string[]

required

List of avatar IDs to associate with the new agent

template_id

string<uuid>

required

ID of the template to use for creating the agent

Response

Agent created successfully

string<uuid>

ID of the newly created agent

message

string

Confirmation message

API Documentation

Video Agents

Avatars

Vision

Conversations

External Meetings

Knowledge Base

Visual Presentations

MCPs

Persona Templates

Providers

Tools

Guardrails

Text to Video Generation

Why templates

Required fields

Optional fields

Example

Common patterns

Per-customer rollout

Next steps

Authorizations

Body

Response

​Why templates

​Required fields

​Optional fields

​Example

​Common patterns

​Per-customer rollout

​Next steps

Authorizations

Body

Response

Why templates

Required fields

Optional fields

Example

Common patterns

Per-customer rollout

Next steps