Create an Agent

An Agent is a persistent interactive configuration: an avatar, a voice profile, and a brain. You create it once, and it stays available behind its route links until you update or delete it.

Before you start, make sure you have:

• A READY avatar — see Generate Avatar or Build Avatar. You can check with mirako avatar list.
• A voice profile — a premade voice or a custom voice. List premade voices with mirako voice premade, and your own custom voices with mirako voice list (that command lists custom voices only, not premade ones).
• For a managed agent: an instruction prompt (up to 12,000 characters) that tells the avatar who it is and how to behave.

Note: The avatar must belong to your account and be READY — agent creation will fail otherwise. The voice can be any premade voice, or a custom voice profile that belongs to your account.

Create a Managed Agent

A managed agent is the fastest way to go live: Mirako runs the LLM for you, guided by your instruction.

With the CLI

Run the command with no flags and the CLI will walk you through choosing an avatar, a voice, and an instruction file:

mirako agent create

Or provide everything up front:

mirako agent create \
    --name "Support Agent" \
    --description "Answers product questions on our website" \
    --avatar <MY_AVATAR_ID> \
    --voice <MY_VOICE_ID> \
    --instruction "You are a friendly support agent. Answer product questions concisely and offer to connect a human when you are unsure."

For longer prompts, keep the instruction in a file (.txt, .md, or .markdown):

mirako agent create \
    --name "Support Agent" \
    --avatar <MY_AVATAR_ID> \
    --voice <MY_VOICE_ID> \
    --instruction-file ./support-instruction.md

Use --instruction or --instruction-file, not both. The command prints your new agent ID — save it, you will need it to create a route.

With the API

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://mirako.co"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_managed_agent():
    """Create a managed agent from an avatar, a voice, and an instruction."""
    response = requests.post(
        f"{BASE_URL}/v1/agents",
        headers=headers,
        json={
            "name": "Support Agent",
            "description": "Answers product questions on our website",
            "avatar_id": "MY_AVATAR_ID",
            "voice_profile_id": "MY_VOICE_ID",
            "runtime_kind": "managed_agent",
            "instruction": (
                "You are a friendly support agent. Answer product "
                "questions concisely."
            ),
        },
    )
    if response.status_code != 201:
        raise RuntimeError(
            f"Failed to create agent: {response.status_code} {response.text}"
        )
    agent = response.json()["data"]
    print(f"Created agent: {agent['id']}")
    return agent


agent = create_managed_agent()

See the Create Agent API reference for the full request and response schema.

Create a Custom Agent

A custom agent points Mirako at an agent endpoint you already run. Mirako handles the avatar, voice, speech, and video; your endpoint owns the prompt, the model, and the tools. Your endpoint must speak the Vercel AI SDK UI message stream protocol — see Building a Custom Agent before you wire one up.

mirako agent create \
    --name "My Existing Agent" \
    --avatar <MY_AVATAR_ID> \
    --voice <MY_VOICE_ID> \
    --runtime-kind custom_agent \
    --custom-agent-url "https://example.com/api/chat" \
    --custom-agent-bearer-token-file ./custom-agent-token.txt

def create_custom_agent():
    """Create a custom agent backed by your own endpoint."""
    response = requests.post(
        f"{BASE_URL}/v1/agents",
        headers=headers,
        json={
            "name": "My Existing Agent",
            "avatar_id": "MY_AVATAR_ID",
            "voice_profile_id": "MY_VOICE_ID",
            "runtime_kind": "custom_agent",
            "custom_agent_url": "https://example.com/api/chat",
            "custom_agent_bearer_token": "my-secret-token",
            "custom_agent_protocol": "vercel_ai_sdk",
        },
    )
    if response.status_code != 201:
        raise RuntimeError(
            f"Failed to create agent: {response.status_code} {response.text}"
        )
    return response.json()["data"]

Note: The bearer token is write-only. It is stored so the Interactive service can call your endpoint, but it is never returned by the API or shown by the CLI — responses only include has_custom_agent_bearer_token so you can confirm one is set. Prefer --custom-agent-bearer-token-file over putting the token directly on the command line.

Agent Fields

You can create up to 100 agents per account.

List, View, Update, and Delete

mirako agent list
mirako agent view <MY_AGENT_ID>
mirako agent delete <MY_AGENT_ID>

mirako agent view shows the full configuration. For a custom agent it shows whether a bearer token is configured, never the token itself. Add -j / --json to list or view for machine-readable output.

Update an Agent

Updates are available through the API. Send only the fields you want to change:

def update_instruction(agent_id, instruction):
    """Replace the instruction of a managed agent."""
    response = requests.post(
        f"{BASE_URL}/v1/agents/{agent_id}/update",
        headers=headers,
        json={"instruction": instruction},
    )
    if response.status_code != 200:
        raise RuntimeError(
            f"Failed to update agent: {response.status_code} {response.text}"
        )
    return response.json()["data"]

A few things to know about updates:

• An update takes effect on the next conversation. Every existing route to the agent picks it up automatically — you do not need to create new links.
• Switching runtime_kind clears the other kind's fields: switching to custom_agent clears instruction and tools; switching to managed_agent clears custom_agent_url and the bearer token.
• To clear a custom agent's bearer token, send "custom_agent_bearer_token": "".
• Changing avatar_id or voice_profile_id requires the new avatar or voice to belong to your account.

See the Update Agent API reference for all updatable fields.

Delete an Agent

Deleting an agent is permanent and cannot be undone. The CLI asks for confirmation unless you pass --force:

mirako agent delete <MY_AGENT_ID> --force

Deleting an agent does not delete its avatar or voice profile — you can still use them in other agents or videos.

Going Next

• Agent Routes: Create the shareable link for your agent
• Share & Embed: Put the conversation page inside your own app

Dive Deeper

• Create Agent API reference
• List Agents API reference
• Building a Custom Agent
• MCP Tools
• Authentication