create

telnyx-acp create
telnyx-acp create --name support-agent \
  --model zai-org/GLM-5.3-Flash

telnyx-acp create --name code-agent --kind code --model zai-org/GLM-5.3-Flash

code-agent/
├── agent.json        kind "code", with "entry": "src/agent.ts" in place of instructions
├── src/agent.ts      the class, the one file the user owns
├── package.json      depends on @telnyx/edge-runtime
├── .gitignore        excludes .telnyx/ and node_modules/
├── README.md
└── AGENTS.md

import { Agent, rpc, type Claim, type Env } from "@telnyx/edge-runtime";
import { AgentHttpServer } from "@telnyx/edge-runtime/agent-http";

// The one file you own. `telnyx-acp deploy` writes the manifest and the
// entry that mount this class; you never edit those.
//
// Each conversation is one durable instance of this class: its messages,
// state and scheduled work survive restarts and are kept until destroyed.
//
// `receive`, `receiveVia`, `run`, `fetch` and `authorize` are the
// contract `telnyx-acp invoke`, `chat`, the browser page and the phone and
// email handlers rely on; keep them. `process` is the turn: yours.

/** What a run leaves behind; `telnyx-acp invoke` reads `lastRunId` and `lastReply`. */
type State = {
  from?: string;
  lastRunId?: string;
  lastReply?: string;
  at?: number;
  /** Each run's status by id, what `run` answers: "accepted" | "completed". */
  runs?: Record<string, string>;
};

/** Where a reply goes when the message came in on a channel: the handler passes this to `receiveVia`. */
type ReplyVia =
  | { kind: "messaging"; profileId: string; from: string; to: string }
  | { kind: "email"; inboxId: string; messageId: string; from: string };

/** The platform's Telnyx client, bound as `TELNYX` by the manifest `deploy` writes. */
type Bindings = Env & {
  TELNYX?: { messages: { send(params: Record<string, unknown>): Promise<unknown> }; post(path: string, options: { body: Record<string, unknown> }): Promise<unknown> };
};

export class CodeAgent extends Agent<Bindings, State> {
  private door: AgentHttpServer<State> | undefined;

  /** The streams and RPC over HTTP, what `invoke`, `chat` and the page talk to. */
  override fetch(req: Request): Promise<Response> {
    return (this.door ??= new AgentHttpServer<State>(this.connectionEngine)).fetch(req);
  }

  /** Who may read the streams and call the @rpc methods: everyone, in the beta phase. */
  protected override authorize(): readonly Claim[] {
    return ["read", "rpc"];
  }

  /** One inbound message from `invoke`, `chat` or the page. Record it, answer off the request path, say which run will. */
  @rpc({ description: "Deliver one inbound message; the reply is produced off the request path" })
  async receive(text: string, from?: string, key?: string): Promise<{ runId: string; duplicate: boolean }> {
    return this.admit(text, from, key);
  }

  /** The same from a text or an email; the reply goes back out on that channel. */
  async receiveVia(text: string, from: string, key: string, via: ReplyVia): Promise<{ runId: string; duplicate: boolean }> {
    return this.admit(text, from, key, via);
  }

  /** One run's status, which `invoke` polls until the state names the run. */
  @rpc({ description: "One run's status" })
  async run(runId: string): Promise<{ id: string; status: string } | undefined> {
    const status = (await this.getState()).runs?.[runId];
    return status === undefined ? undefined : { id: runId, status };
  }

  private async admit(text: string, from: string | undefined, key: string | undefined, via?: ReplyVia): Promise<{ runId: string; duplicate: boolean }> {
    const runId = key === undefined ? `run-${Date.now()}-${crypto.randomUUID()}` : `run-${key}`;
    const state = await this.getState();
    if (state.runs?.[runId] !== undefined) return { runId, duplicate: true }; // a redelivered message runs once
    await this.setState({ ...(from === undefined ? {} : { from }), runs: { [runId]: "accepted" } });
    await this.messages.add("user", text);
    await this.queue("process", { runId, via });
    return { runId, duplicate: false };
  }

  /** The turn: read the history, produce a reply, remember it, plan a follow-up. */
  async process({ runId, via }: { runId: string; via?: ReplyVia }): Promise<void> {
    const history = await this.messages.toLangChain();
    void history; // hand this to your model
    const reply = "Hello! How can I help?";
    await this.messages.add("assistant", reply);
    await this.setState({ lastRunId: runId, lastReply: reply, at: Date.now(), runs: { [runId]: "completed" } });
    if (via) await this.deliver(reply, via);
    await this.schedule(86_400, "nudge", null, { id: "nudge" });
  }

  /** A reply back out on the channel the message came in on. */
  protected async deliver(text: string, via: ReplyVia): Promise<void> {
    const telnyx = this.env.TELNYX;
    if (!telnyx) throw new Error("replying on a channel needs the TELNYX binding");
    if (via.kind === "messaging") await telnyx.messages.send({ from: via.to, to: via.from, text, messaging_profile_id: via.profileId });
    else await telnyx.post(`/email_inboxes/${encodeURIComponent(via.inboxId)}/messages/${encodeURIComponent(via.messageId)}/actions/reply`, { body: { text } });
  }

  /** Runs a day later unless the conversation moved on. */
  async nudge(): Promise<void> {
    const last = await this.messages.last();
    if (last?.role !== "assistant") return;
  }
}

npm install
telnyx-acp dev

telnyx-acp deploy