CumulusDocs
Open Studio
On this page

Build your first agent in Studio

Build Service-ticket triage, a cloud task that reads a support ticket and replies with a category and reason. You will create a draft, run a test publication and inspect its transcript. This exercise needs no phone carrier, number or business endpoint.

The example uses fictional tickets and results. Keep the two nodes supplied by the Task template.

Before you start

Sign in to the Studio URL provided for your workspace and select the intended environment in the workspace switcher. Choose the sandbox so these practice agents and runs stay separate from production. Use the fictional input below and leave business actions disconnected.

A member can build agents and start runs; a viewer can review them. Your environment needs a ready conversation model and run admission enabled, which means it is allowed to start work. An organization admin manages API keys and credentials. If you need a sandbox, cannot find an available model or cannot start runs, ask your admin or Cumulus representative to confirm setup. See Workspace and access.

Build a flow

Service-ticket triage in Studio with the classification rules in Settings, Prompt, Global prompt

  1. Open Agents, create an agent and select the Task template. Name it Service-ticket triage, keep English selected and choose Create agent.
  2. The Flow tab opens the draft. Keep the starter conversation node and its transition to the end node. The conversation node completes the task supplied in the run input; the end node finishes the run.
  3. Open Settings → Prompt. Paste the following into Global prompt:
text
You classify fictional equipment-service tickets. Read the ticket field in the run input.
Use repair when equipment is broken or malfunctioning, booking when the request is only to arrange or change a visit, and other for anything else.
Reply once with a JSON object containing category and reason. Keep the reason to one sentence. Do not ask follow-up questions or claim to have booked or repaired anything.
  1. Open Settings → Model and check Conversation model. Keep the available default, or select a ready model if one is missing. Leave the starter cloud schemas unchanged and do not add actions, webhooks or triggers.

Edits save to the draft. A node is one step; its transition tells the agent when to move to the next step. The global prompt supplies rules that apply across the flow.

Editing the draft does not change a publication or a run already in progress. Agents explains nodes, variables, actions and revision conflicts.

Test a version

  1. Choose Test in the editor header, then Task in the test panel. Paste this fictional request into Input (JSON):
json
{
  "task": "Classify this equipment-service ticket and give a brief reason.",
  "ticket": "The loading-bay door is stuck closed and will not open."
}
  1. Choose Run task. Studio saves the draft, validates it and prepares a test publication with live: false, then starts a cloud task run against that exact version. This keeps the live version unchanged. The status badge identifies the version as test v….
  2. If validation reports errors, fix the listed problems and choose Run task again. Starting a run is not proof it completed; wait for Completed before reviewing the answer.

The run uses test: true, excluding it from billing, webhooks and event triggers. That flag still allows configured business actions to execute. This exercise has no business actions. A test publication and a test-marked run are different: the publication saves behavior; the run executes it.

For repeatable conversation checks, follow Test an agent to create a simulation suite. For a phone agent, a browser voice session checks speech and turn-taking; carrier routing needs a separate call to a number you own.

The publish-and-test recipe explains publication and simulation through the API.

Review a run

The two-node Service-ticket triage flow beside its completed Task test and repair classification

In the test panel, read the agent's reply. An expected reply is:

json
{
  "category": "repair",
  "reason": "The loading-bay door is malfunctioning and needs repair."
}

The model may phrase the reason differently. Check that the category is repair, the reason reflects the stuck door and the agent makes no claim that service was booked or completed.

Choose View run to open the saved run. Check its publication version and transcript. You can also find it under Calls & runs by filtering for this agent. Follow the timeline to see the executed path.

The starter template's structured result is {} because its output schema declares no fields. The classification above is the agent's transcript reply. To return fields your application can consume, configure an output schema and flow variables, then read the task result. Writing JSON in a reply does not configure those fields.

You have finished when the run is completed, its transcript contains a repair classification with a relevant reason, and its publication matches the test version.

Try a second case in the Task test panel. In Input (JSON), replace only the ticket value with Please move my technician visit to Friday. and keep the task value. Choose Run again and expect booking. Run again uses the input currently in that field; it does not clear or change the input for you. This second case checks that the agent follows the category rules.

The Runs guide explains the other outputs and how an application reads them.

Go live and iterate

The This exercise finishes with a test publication. Before ordinary business execution, test representative cases and real integrations, then publish the reviewed configuration explicitly with live: true. Verify its test flag and assign phone routes separately if applicable.

New API-started runs that omit a version select the head and still enforce its test flag; existing runs keep their original version. Incoming phone numbers keep their assigned publication even after promotion: reassign the number to use the new version. To roll back a behavior change, promote an earlier publication and review those phone assignments too. Run the same test cases against each new candidate to compare results.

For phone agents, complete carrier and number setup and confirm inbound routing if needed. For application integration, follow the API quickstart.

Choose your next workflow

Your next stepGuide
Add conditional routing and reusable componentsBranching support agent
Follow an action through a runInvestigate a run
Compare a candidate with its baselineRegression testing
Compare development responsibilitiesChoose your platform
Continue work after a conversationAfter-call operations
Release a tested publicationRelease an agent

Connect a business integration

Equipment-service coordination follows a warehouse service request through contact checks, booking and dispatch. Order resolution covers verification, policy and refunds. Qualification and booking connects discovery to a calendar reservation.

Content version 49435d78Customer SDKMarkdown source
Build your first agent in Studio · Cumulus developer docs