Can I use Retell AI as a CLI?

Yes. KosmoKrator exposes a Retell AI CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Retell AI through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Retell AI tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Retell AI credentials stored?

Retell AI credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Retell AI MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Retell AI Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Retell AI KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.retell_ai.*. Use lua_read_doc("integrations.retell-ai") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Retell AI workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.retell_ai.create_phone_call({agent_id = "example_agent_id", metadata = "example_metadata", options = "example_options"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("retell-ai"))' --json
kosmo integrations:lua --eval 'print(docs.read("retell-ai.create_phone_call"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local retell_ai = app.integrations.retell_ai
local result = retell_ai.create_phone_call({agent_id = "example_agent_id", metadata = "example_metadata", options = "example_options"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.retell_ai, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.retell_ai.default.* or app.integrations.retell_ai.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Retell AI, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Retell AI - Lua API Reference

Namespace: app.integrations.retell_ai

Retell uses API-root paths for agents, phone numbers, LLMs, and voices, while calls use /v2/... paths. This integration normalizes older /v2 base URL configs back to https://api.retellai.com.

Calls

local call = app.integrations.retell_ai.create_call({
  agent_id = "agent_123",
  metadata = {customer_id = "cus_123"},
  options = {
    from_number = "+14155550100",
    to_number = "+14155550199"
  }
})

local web_call = app.integrations.retell_ai.create_web_call({
  data = {agent_id = "agent_123"}
})

local calls = app.integrations.retell_ai.list_calls({
  filter = {agent_id = "agent_123"}
})

local details = app.integrations.retell_ai.get_call({call_id = "call_123"})

app.integrations.retell_ai.update_call({
  call_id = "call_123",
  metadata = {reviewed = true}
})

app.integrations.retell_ai.stop_call({call_id = "call_123"})
app.integrations.retell_ai.delete_call({call_id = "call_123"})

Agents

local agents = app.integrations.retell_ai.list_agents({})
local agent = app.integrations.retell_ai.get_agent({agent_id = "agent_123"})

local created = app.integrations.retell_ai.create_agent({
  voice_id = "11labs-Adrian",
  prompt = "You are a helpful appointment scheduling agent.",
  options = {
    agent_name = "Scheduling Agent"
  }
})

app.integrations.retell_ai.update_agent({
  agent_id = "agent_123",
  data = {agent_name = "Updated Agent"}
})

app.integrations.retell_ai.delete_agent({agent_id = "agent_123"})

Phone Numbers

local numbers = app.integrations.retell_ai.list_phone_numbers({})

local number = app.integrations.retell_ai.get_phone_number({
  phone_number = "+14155550100"
})

app.integrations.retell_ai.update_phone_number({
  phone_number = "+14155550100",
  data = {
    inbound_agent_id = "agent_123"
  }
})

LLMs And Voices

local llms = app.integrations.retell_ai.list_retell_llms({})
local llm = app.integrations.retell_ai.get_retell_llm({llm_id = "llm_123"})

local voices = app.integrations.retell_ai.list_voices({})
local voice = app.integrations.retell_ai.get_voice({voice_id = "11labs-Adrian"})

Generic API Helpers

Use generic helpers only for documented Retell endpoints that do not yet have a dedicated tool. path must be relative to the configured API base URL; absolute URLs are rejected.

local flows = app.integrations.retell_ai.api_get({
  path = "/list-conversation-flows"
})

local created_llm = app.integrations.retell_ai.api_post({
  path = "/create-retell-llm",
  body = {general_prompt = "You are a concise support agent."}
})

local updated = app.integrations.retell_ai.api_patch({
  path = "/update-agent/agent_123",
  body = {agent_name = "Updated Agent"}
})

local deleted = app.integrations.retell_ai.api_delete({
  path = "/delete-retell-llm/llm_123"
})

Multi-Account Usage

app.integrations.retell_ai.list_agents({})
app.integrations.retell_ai.default.list_agents({})
app.integrations.retell_ai.production.list_calls({
  filter = {agent_id = "agent_123"}
})

All account namespaces expose the same tools; only stored API keys differ.

Raw agent markdown

# Retell AI - Lua API Reference

Namespace: `app.integrations.retell_ai`

Retell uses API-root paths for agents, phone numbers, LLMs, and voices, while calls use `/v2/...` paths. This integration normalizes older `/v2` base URL configs back to `https://api.retellai.com`.

## Calls

```lua
local call = app.integrations.retell_ai.create_call({
  agent_id = "agent_123",
  metadata = {customer_id = "cus_123"},
  options = {
    from_number = "+14155550100",
    to_number = "+14155550199"
  }
})

local web_call = app.integrations.retell_ai.create_web_call({
  data = {agent_id = "agent_123"}
})

local calls = app.integrations.retell_ai.list_calls({
  filter = {agent_id = "agent_123"}
})

local details = app.integrations.retell_ai.get_call({call_id = "call_123"})

app.integrations.retell_ai.update_call({
  call_id = "call_123",
  metadata = {reviewed = true}
})

app.integrations.retell_ai.stop_call({call_id = "call_123"})
app.integrations.retell_ai.delete_call({call_id = "call_123"})
```

## Agents

```lua
local agents = app.integrations.retell_ai.list_agents({})
local agent = app.integrations.retell_ai.get_agent({agent_id = "agent_123"})

local created = app.integrations.retell_ai.create_agent({
  voice_id = "11labs-Adrian",
  prompt = "You are a helpful appointment scheduling agent.",
  options = {
    agent_name = "Scheduling Agent"
  }
})

app.integrations.retell_ai.update_agent({
  agent_id = "agent_123",
  data = {agent_name = "Updated Agent"}
})

app.integrations.retell_ai.delete_agent({agent_id = "agent_123"})
```

## Phone Numbers

```lua
local numbers = app.integrations.retell_ai.list_phone_numbers({})

local number = app.integrations.retell_ai.get_phone_number({
  phone_number = "+14155550100"
})

app.integrations.retell_ai.update_phone_number({
  phone_number = "+14155550100",
  data = {
    inbound_agent_id = "agent_123"
  }
})
```

## LLMs And Voices

```lua
local llms = app.integrations.retell_ai.list_retell_llms({})
local llm = app.integrations.retell_ai.get_retell_llm({llm_id = "llm_123"})

local voices = app.integrations.retell_ai.list_voices({})
local voice = app.integrations.retell_ai.get_voice({voice_id = "11labs-Adrian"})
```

## Generic API Helpers

Use generic helpers only for documented Retell endpoints that do not yet have a dedicated tool. `path` must be relative to the configured API base URL; absolute URLs are rejected.

```lua
local flows = app.integrations.retell_ai.api_get({
  path = "/list-conversation-flows"
})

local created_llm = app.integrations.retell_ai.api_post({
  path = "/create-retell-llm",
  body = {general_prompt = "You are a concise support agent."}
})

local updated = app.integrations.retell_ai.api_patch({
  path = "/update-agent/agent_123",
  body = {agent_name = "Updated Agent"}
})

local deleted = app.integrations.retell_ai.api_delete({
  path = "/delete-retell-llm/llm_123"
})
```

## Multi-Account Usage

```lua
app.integrations.retell_ai.list_agents({})
app.integrations.retell_ai.default.list_agents({})
app.integrations.retell_ai.production.list_calls({
  filter = {agent_id = "agent_123"}
})
```

All account namespaces expose the same tools; only stored API keys differ.

Metadata-derived Lua example

local result = app.integrations.retell_ai.create_phone_call({agent_id = "example_agent_id", metadata = "example_metadata", options = "example_options"})
print(result)

Functions

create_phone_call Write

Create a new AI-powered phone call using a Retell AI voice agent. Specify the agent ID and optional metadata to attach context to the call.

Lua path: app.integrations.retell_ai.create_phone_call
Full name: retell-ai.retell_ai_create_call

Parameter	Type	Required	Description
`agent_id`	string	yes	The Retell AI agent ID to use for the call (e.g., "agent_17a9b81c3c0").
`metadata`	object	no	Optional key-value metadata to attach to the call for tracking and context (e.g., {"customer_id": "12345", "campaign": "onboarding"}).
`options`	object	no	Additional create-phone-call fields such as from_number, to_number, override_agent_id, and retell_llm_dynamic_variables.

create_web_call Write

Create a Retell web call.

Lua path: app.integrations.retell_ai.create_web_call
Full name: retell-ai.retell_ai_create_web_call

Parameter	Type	Required	Description
No parameters.

get_call Read

Retrieve details for a specific phone call by its ID. Returns call status, duration, transcript, and associated metadata.

Lua path: app.integrations.retell_ai.get_call
Full name: retell-ai.retell_ai_get_call

Parameter	Type	Required	Description
`call_id`	string	yes	The unique identifier of the call to retrieve (e.g., "call_17a9b81c3c0").

list_calls Read

List phone calls from Retell AI. Returns call records with status, duration, and metadata. Supports optional filters for agent, status, or date range.

Lua path: app.integrations.retell_ai.list_calls
Full name: retell-ai.retell_ai_list_calls

Parameter	Type	Required	Description
`filter`	object	no	Optional filters to apply. Supported keys may include agent_id, status, start_timestamp, end_timestamp, etc.

update_call Write

Update call metadata.

Lua path: app.integrations.retell_ai.update_call
Full name: retell-ai.retell_ai_update_call

Parameter	Type	Required	Description
No parameters.

stop_call Write

Stop an in-progress call.

Lua path: app.integrations.retell_ai.stop_call
Full name: retell-ai.retell_ai_stop_call

Parameter	Type	Required	Description
No parameters.

delete_call Write

Delete a call record.

Lua path: app.integrations.retell_ai.delete_call
Full name: retell-ai.retell_ai_delete_call

Parameter	Type	Required	Description
No parameters.

list_agents Read

List all configured voice agents in your Retell AI account. Returns agent IDs, names, voice settings, and other configuration details.

Lua path: app.integrations.retell_ai.list_agents
Full name: retell-ai.retell_ai_list_agents

Parameter	Type	Required	Description
No parameters.

get_agent Read

Get a voice agent.

Lua path: app.integrations.retell_ai.get_agent
Full name: retell-ai.retell_ai_get_agent

Parameter	Type	Required	Description
No parameters.

create_agent Write

Create a new voice AI agent in Retell AI. Specify the voice ID and system prompt. Additional options like agent name, language, and behavior settings can be provided.

Lua path: app.integrations.retell_ai.create_agent
Full name: retell-ai.retell_ai_create_agent

Parameter	Type	Required	Description
`voice_id`	string	yes	The voice ID to assign to the agent (e.g., "11labs_Alice"). Determines the voice the agent speaks with.
`prompt`	string	yes	The system prompt that defines the agent's behavior, personality, and conversation guidelines.
`options`	object	no	Additional agent configuration options (e.g., {"agent_name": "Support Agent", "language": "en", "ambient_noise": true}).

update_agent Write

Update a voice agent.

Lua path: app.integrations.retell_ai.update_agent
Full name: retell-ai.retell_ai_update_agent

Parameter	Type	Required	Description
No parameters.

delete_agent Write

Delete a voice agent.

Lua path: app.integrations.retell_ai.delete_agent
Full name: retell-ai.retell_ai_delete_agent

Parameter	Type	Required	Description
No parameters.

list_phone_numbers Read

List phone numbers.

Lua path: app.integrations.retell_ai.list_phone_numbers
Full name: retell-ai.retell_ai_list_phone_numbers

Parameter	Type	Required	Description
No parameters.

get_phone_number Read

Get a phone number.

Lua path: app.integrations.retell_ai.get_phone_number
Full name: retell-ai.retell_ai_get_phone_number

Parameter	Type	Required	Description
No parameters.

update_phone_number Write

Update phone number routing.

Lua path: app.integrations.retell_ai.update_phone_number
Full name: retell-ai.retell_ai_update_phone_number

Parameter	Type	Required	Description
No parameters.

list_llms Read

List Retell LLMs.

Lua path: app.integrations.retell_ai.list_llms
Full name: retell-ai.retell_ai_list_retell_llms

Parameter	Type	Required	Description
No parameters.

get_llm Read

Get a Retell LLM.

Lua path: app.integrations.retell_ai.get_llm
Full name: retell-ai.retell_ai_get_retell_llm

Parameter	Type	Required	Description
No parameters.

list_voices Read

List voices.

Lua path: app.integrations.retell_ai.list_voices
Full name: retell-ai.retell_ai_list_voices

Parameter	Type	Required	Description
No parameters.

get_voice Read

Get a voice.

Lua path: app.integrations.retell_ai.get_voice
Full name: retell-ai.retell_ai_get_voice

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Retrieve current Retell AI account information, including available agents and account status. Useful for verifying connectivity and understanding account capabilities.

Lua path: app.integrations.retell_ai.get_current_user
Full name: retell-ai.retell_ai_get_current_user

Parameter	Type	Required	Description
No parameters.

api_get Read

Call a documented GET endpoint.

Lua path: app.integrations.retell_ai.api_get
Full name: retell-ai.retell_ai_api_get

Parameter	Type	Required	Description
No parameters.

api_post Write

Call a documented POST endpoint.

Lua path: app.integrations.retell_ai.api_post
Full name: retell-ai.retell_ai_api_post

Parameter	Type	Required	Description
No parameters.

api_patch Write

Call a documented PATCH endpoint.

Lua path: app.integrations.retell_ai.api_patch
Full name: retell-ai.retell_ai_api_patch

Parameter	Type	Required	Description
No parameters.

api_delete Write

Call a documented DELETE endpoint.

Lua path: app.integrations.retell_ai.api_delete
Full name: retell-ai.retell_ai_api_delete

Parameter	Type	Required	Description
No parameters.