> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Deploy the First Agent ## Prerequisites * Node.js 22.13 or later, and [`telnyx-edge`](https://developers.telnyx.com/docs/edge-compute/quickstart) 0.5.7 or later on the `PATH` (or `TELNYX_EDGE_BIN` pointing at it). * The CLI, installed and signed in: ```bash theme={null} npm install -g @telnyx/acp telnyx-acp login # OAuth through telnyx-edge; scripts and CI set TELNYX_API_KEY instead telnyx-acp models # confirms the session: lists the account's models, or exits 4 with "You are not signed in." ``` `telnyx-acp update` keeps it current from then on, and the CLI says when a newer release exists; [Utilities](https://developers.telnyx.com/docs/agents/cli/utilities.md#update) has both. > [!WARNING] > > **Beta.** `@telnyx/acp` is a pre-release, and the control plane has no API of its own yet. See [Beta Limitations](https://developers.telnyx.com/docs/agents/beta-limitations.md). ## 1. Create > [tab] Wizard > > `create` with no flags opens the wizard, the recommended way in: it asks one question at a time, checks each answer as it goes (a number is looked up in the account, a model picked from the ones the account can use), and shows what it will write before it writes it. It asks, in order, for: > > * the project name > * how to build the agent, and the language for a code project > * the model > * a phone number > * email > * a channel by artifact id > * a browser page > * a call greeting, when a number was added > * memory > * a step limit > > Then it shows what it will write, and writes it. > > ```bash theme={null} > telnyx-acp create > ``` > > Name the project: > > ![The wizard's Project prompt with support-agent typed](https://mintcdn.com/telnyx/IwbHhFfX3hCEfF-q/assets/images/agents-wizard-01-project.png?fit=max\&auto=format\&n=IwbHhFfX3hCEfF-q\&q=85\&s=e03ace70c3f69dc0f915fc2fb3a21c85) > > Choose configuration, the recommended path, or code: > > ![How would you like to build your agent? Define agent in configuration (recommended), Define agent in code, Skip](https://mintcdn.com/telnyx/IwbHhFfX3hCEfF-q/assets/images/agents-wizard-02-how-to-build.png?fit=max\&auto=format\&n=IwbHhFfX3hCEfF-q\&q=85\&s=dabf98f08319762a22f3a4490238f3ef) > > Pick the model from what the account can use; type to search. The example picks `zai-org/GLM-5.3-Flash`: > > ![The Model picker filtered by typing, with zai-org/GLM-5.3-Flash selected](https://mintcdn.com/telnyx/IwbHhFfX3hCEfF-q/assets/images/agents-wizard-03-model.png?fit=max\&auto=format\&n=IwbHhFfX3hCEfF-q\&q=85\&s=11930ec43debbc5977e85fa3dbaaca59) > > Say no to a phone number for now; step 5 adds one: > > ![Add a phone number now? with No selected, under a note on where to get a number](https://mintcdn.com/telnyx/IwbHhFfX3hCEfF-q/assets/images/agents-wizard-04-phone-later.png?fit=max\&auto=format\&n=IwbHhFfX3hCEfF-q\&q=85\&s=dd8f27686d2606dd853047116efc2655) > > Say no to email, to a channel and to a chat page as well; each is one `add` later. > > Keep memory on: > > ![Remember people with Agent Memory? with Yes selected](https://mintcdn.com/telnyx/IwbHhFfX3hCEfF-q/assets/images/agents-wizard-05-memory.png?fit=max\&auto=format\&n=IwbHhFfX3hCEfF-q\&q=85\&s=7768817497e0d57181f1429828521944) > > Say no to the step limit, which keeps the default of 8. Confirm what `create` will write, and it writes it: > > ![The summary of the files create will write, the Create it? prompt, the created files, and the next commands: dev, chat, deploy, status, logs](https://mintcdn.com/telnyx/IwbHhFfX3hCEfF-q/assets/images/agents-wizard-07-created.png?fit=max\&auto=format\&n=IwbHhFfX3hCEfF-q\&q=85\&s=875e3ca16813fd0b7d0b5bd2daa93566) > > ```bash theme={null} > cd support-agent > ``` > [tab] CLI > > Any flag skips the wizard: the flag form is for scripts and for a second project, and a missing or wrong flag is an error with the fix on one line (`--phone` not in E.164, a `--channel` without an id). > > ```bash theme={null} > telnyx-acp create --name support-agent --model zai-org/GLM-5.3-Flash > cd support-agent > ``` > > The project is five files: > > ```text theme={null} > support-agent/ > ├── agent.json # the agent: model, memory, limits, approvals, secrets (names only), channels > ├── instructions.md # what the agent is told > ├── AGENTS.md # notes for coding agents working in the project > ├── README.md > └── .gitignore > ``` > > The flag form leaves memory off; the wizard turns it on by default. `zai-org/GLM-5.3-Flash` is hosted by Telnyx, so the agent answers with no key added. `telnyx-acp models` lists what else the account can use; [Models and Instructions](https://developers.telnyx.com/docs/agents/models-and-instructions.md#byok-for-third-party-models) covers the BYOK scenario. `create` writes a starter system prompt in `instructions.md`. [Models and Instructions](https://developers.telnyx.com/docs/agents/models-and-instructions.md#instructions) covers customization. ## 2. Run It Locally ```bash theme={null} telnyx-acp dev ``` ```text theme={null} ✓ support-agent (configuration kind) running on this machine http://127.0.0.1:8787/agents/support-agent/ telnyx-acp invoke support-agent --conversation alice --local "hi" watching instructions.md and agent.json; Ctrl-C to stop ``` In a second terminal, start a session with `chat`; each line is a turn on the same conversation. ```bash theme={null} telnyx-acp chat --local ``` ```text theme={null} ✔ chatting with support-agent (conversation session-b969, on this machine) /exit or Ctrl-C leaves, /new starts a fresh conversation › my name is Alex ✔ support-agent is answering 2.0s support-agent › Hi Alex! How can I help you today? › what's my name? ✔ support-agent is answering 1.0s support-agent › Your name is Alex. › /exit to continue this conversation: $ telnyx-acp chat support-agent --conversation session-b969 --local ``` `invoke` is one turn per command, so turns across sessions can interleave; each conversation keeps its own context. ```bash theme={null} telnyx-acp invoke support-agent --conversation alice --local "my name is Alice" telnyx-acp invoke support-agent --conversation bob --local "my name is Bob" telnyx-acp invoke support-agent --conversation alice --local "what is my name?" telnyx-acp invoke support-agent --conversation bob --local "what is my name?" ``` ```text theme={null} Hi Alice! How can I help you today? Hi Bob! Nice to meet you. How can I help you today? Your name is Alice. Your name is Bob. ``` `--stream` prints each assistant message as it lands. The outbound calls are the model's and those of any tools; inbound channels and memory need a deploy; with a number or a `voice` block, the page's mic button tries the voice settings locally. [Local Development](https://developers.telnyx.com/docs/agents/local-development.md) lists what else differs. ## 3. Deploy ```bash theme={null} telnyx-acp deploy --dry-run # the plan; writes nothing telnyx-acp deploy # asks once, then ships; --yes in scripts ``` The first `deploy` registers the agent and builds it (a build typically takes about ten minutes; `deploy` waits up to 25); every `deploy` after that is a new revision. The agent comes up at its **mount**, the function's public URL: ```text theme={null} https://.telnyxcompute.com/agents/support-agent/ ``` > [!NOTE] > > `.telnyx/` is written beside the project files by `dev` and on every `deploy`; the scaffolded `.gitignore` already excludes it. After the first `deploy` `agent.json` also records the function id, the mount URL, the actor type and the active revision under `deployed`. ## 4. Invoke the Deployed Agent ```bash theme={null} telnyx-acp chat # a conversation with the deployed agent telnyx-acp invoke support-agent --conversation alice "hi" # one turn, for scripts telnyx-acp invoke support-agent --conversation alice --stream "what can you do?" ``` Then watch it: ```bash theme={null} telnyx-acp status # function, actor, revision, the address telnyx-acp logs --since 10m # one line per runtime record telnyx-acp logs --since 10m --type invocations # conversation, method, status, duration telnyx-acp logs --tail # live; lines land a few seconds after the request ``` ## 5. Give the Agent a Phone Number Prerequisites: 1. A number in the account with voice and messaging enabled. `telnyx-acp numbers` lists them; if there is none, buy one in [Mission Control → Numbers → Search & Buy](https://portal.telnyx.com/#/app/numbers/search-numbers). 2. The account's webhook public key (Mission Control → Account → Keys & Credentials → Public Key, [portal.telnyx.com/#/api-keys/public-key](https://portal.telnyx.com/#/api-keys/public-key)). `deploy` reads it from the account itself and asks only when that read fails. ```bash theme={null} telnyx-acp add phone +15550001234 telnyx-acp add secret TELNYX_PUBLIC_KEY # the webhook public key; prompts for the value, reads stdin when piped telnyx-acp deploy --dry-run # checks the number is in the account; writes nothing telnyx-acp deploy # asks once, ships, wires the number; --yes in scripts ``` ```text theme={null} ✓ support-agent deployed (revision a1b2c3d4e5f6) phone +15550001234 calls via call_control_application , created by deploy; texts via messaging_profile , created by deploy https://support-agent-.telnyxcompute.com/agents/support-agent/ ``` Call the number. Text it from the terminal: `telnyx-acp text "hi"` sends an SMS from one of the account's own numbers and prints the reply; both numbers are Telnyx's, so no 10DLC registration is needed. A text from a personal phone reaches the agent, but a US handset gets the reply only once the number is 10DLC-registered, and a phone outside the US cannot reach a US long code at all; [Messaging](https://developers.telnyx.com/docs/agents/messaging.md#testing-without-a-phone) has the detail. ## 6. Change It, Ship Again Edit `instructions.md`, or change one field of `agent.json` with `telnyx-acp set`, and run `telnyx-acp deploy` again. Every `deploy` is a new revision; `telnyx-acp versions support-agent` lists them, with the project's git short SHA when the project is a git repository. ## 7. Tear Down ```bash theme={null} telnyx-acp remove phone +15550001234 # the next deploy puts the number back where it was telnyx-acp delete support-agent # webhooks restored, number released, function and actor type deleted; --yes in scripts ``` `delete` removes the Telnyx resources `deploy` created and restores the webhooks of pre-existing ones; local project files stay.