Extending the Managed Agent

@telnyx/acp/managed exports the classes the CLI generates for a configuration project. A code-based agent extends them.

Export	What It Is
`defineManagedAgent(spec, host?)`	A class bound to the spec: the managed loop for texts and `invoke`.
`defineManagedVoiceAgent(spec, host?)`	The same, wrapped in the `voice()` mixin from `@telnyx/edge-runtime/voice`, which answers calls.
`ManagedAgent`	The loop itself, for a class that builds its own host in the constructor.
`ReplyVia`, `ManagedAgentSpec`, `ManagedAgentHost`	The types.

Every class is a runtime SDK Agent, so this.messages, getState() and setState(), queue(), schedule(), @rpc methods and the rest of its API are there to use.

The Host

The second argument is what agent.json cannot say:

import { ManagedAgent, type ManagedAgentHost, type ManagedEnv } from "@telnyx/acp/managed";
import type { ActorContext } from "@telnyx/edge-runtime";
import { tool } from "ai";
import { z } from "zod";

const spec = { name: "support-agent", model: "zai-org/GLM-5.3-Flash", instructions: "…", approvals: { refund_order: "ask" } } as const;

const host: ManagedAgentHost = {
  tools: {
    refund_order: tool({
      description: "Refund an order",
      inputSchema: z.object({ orderId: z.string() }),
      execute: async ({ orderId }) => ({ refunded: orderId }),
    }),
  },
  authorization: myAuthorizationProvider,   // who may approve; without it the default allows every decision under the agent's own identity
  approvalTtlMs: 15 * 60 * 1000,            // how long a granted approval stays usable (5 min to 24 h)
};

export class SupportAgent extends ManagedAgent<ManagedEnv> {
  constructor(ctx: ActorContext, env: ManagedEnv) {
    super(ctx, env, spec, host);
  }
}

Host Field	Meaning
`tools`	A tool set, in the `ai` package’s shape. `spec.approvals` marks each tool. An `ask` tool pauses the run until `approve` or `deny`, and a `deny` tool is withheld.
`authorization`	Identity and policy for approvals, registered as the harness’s authorization port.
`approvalTtlMs`	5 minutes to 24 hours.
`model`	A language model used outright, instead of `spec.model` over the platform.
`completions`	Chat completions for `spec.model`, when the platform’s endpoint is not the right one.
`environmentKeys`	Which bindings cross into the harness ports’ `environment` (none by default).
`authorize(token, req)`	Who may read the streams and call `@rpc` methods over the mount. Everyone, unless the class narrows it.

Approvals, End to End

A run that reaches a tool marked ask pauses, and the state records the paused run as awaitingApprovalRunId; invoke ends with a line naming that run instead of waiting. Under dev, the line also carries the approval’s id. A decision is one RPC on the conversation:

telnyx-acp rpc support-agent --conversation alice inspectApproval <approvalId>
telnyx-acp rpc support-agent --conversation alice approve <approvalId>
telnyx-acp rpc support-agent --conversation alice deny <approvalId>

Under dev, approvals are authorized by a fixed local identity that allows every decision, and a paused run is printed with the rpc … --local approve <id> line to decide it. Deployed, a host that passes no authorization gets the loop’s built-in default: every decision is allowed, under the agent’s own identity (agent:<name>), so whoever the mount admits to rpc decides (everyone, in the beta phase). Pass authorization to require a real caller identity and policy; the harness itself refuses a run with an ask tool when no provider is registered at all.

What to Override

import { defineManagedAgent, type ReplyVia } from "@telnyx/acp/managed";
import { rpc } from "@telnyx/edge-runtime";

export class SupportAgent extends defineManagedAgent(spec) {
  /** Where a reply goes out. The default sends a text on the profile the message came in on. */
  protected override async deliver(text: string, via: ReplyVia): Promise<void> {
    await super.deliver(text, via);
    await this.queue("audit", { text });              // the class's own persistent follow-up
  }

  /** An RPC of the class's own, reachable over the mount and with `telnyx-acp rpc`. */
  @rpc({ description: "The last reply" })
  async lastReply(): Promise<string | undefined> {
    return (await this.getState()).lastReply;
  }

  protected override async onTask(name: string, payload: unknown, info: { attempt: number }): Promise<void> {
    if (name === "audit") return;                     // handle the class's own; everything else is the loop's
    await super.onTask(name, payload, info);
  }
}

The loop keeps its six @rpc methods, receive, approve, deny, inspectApproval, pendingApproval and run. Methods without @rpc are private over the mount, which is how the webhook handler’s receiveVia (which names where a reply goes) is reachable in-process only.

The Voice Hooks

defineManagedVoiceAgent(spec) answers calls. Its hooks, all overridable:

Hook	When	Default
`greeting(call)`	the call is answered	`spec.voice.greeting`, or “Hi, this is <name>. How can I help?”
`turnEngine()`	each turn	the direct engine (model + in-memory history); the harness with `voice.harness`
`reply(transcript, call)`	each reply	the mixin’s reply wrapped in `withFiller`, which says one short phrase when the model is slow to start, tuned by `voice.filler`
`speechProviders()`	the call starts	STT and TTS, tuned from `spec.voice`
`turnEnded(metrics, call)`	a turn’s playout ends	logs the turn’s clock, writes the exchange
`callEnded(call, reason)`	hang-up	writes the last reply, ingests the call into memory
`warmCall(from?)`	before the call is answered	starts the instance, names the caller, begins the first turn’s reading

call.from and call.to are the numbers, call.callControlId the call. The Voice Loop shows how the class drives the mixin.

Dropping to the SDK

A class that extends the runtime SDK’s Agent directly, or voice(Agent), is also a valid entry. The CLI deploys any exported agent class and wires the declared channels to it, and the loop is left to the user. The webhook handlers then call receiveVia(text, from, key, via) on that class for a text and open the media socket to it for a call. A class of the user’s own implements them as the managed loop does, or as Bring Your Own Framework shows.

Get Started

Inside the Managed Harness

The Agent Harness SDK

The Agent Runtime SDK

The Agent Client SDK

For AI Agents

Extending the Managed Agent

The Host

Approvals, End to End

What to Override

The Voice Hooks

Dropping to the SDK

​The Host

​Approvals, End to End

​What to Override

​The Voice Hooks

​Dropping to the SDK

The Host

Approvals, End to End

What to Override

The Voice Hooks

Dropping to the SDK