Voice app overview
One file that says what a project answers: its numbers, who picks up, the rules every agent keeps and what happens around a call.
A voice app is one file, app.ts, that says what a project answers: which agent picks up each
phone number, the words a call opens with, and what every agent of the project shares. An agent
is one conversation; the app is everything around it.
What is a voice app?#
A project is a folder of agents. Without an app, each agent answers the number pointed at it and
knows nothing of the others. With an app.ts at the project's root, the project has one place that
says how its agents work together.
The app is optional. A project with no app.ts runs exactly as before.
This page writes the app in TypeScript. A Python project writes the same app in
app.pyand a Ruby project inapp.rb, with the same lines, rules, teams and flows: the voice app in Python and in Ruby.
The app, whole#
import { voiceApp } from "@pinecall/agents";
import Billing from "./agents/billing/agent";
import FrontDesk from "./agents/front-desk/agent";
import { clinic } from "./lib/clinic";
const app = voiceApp("brightside-dental", { timezone: "America/Los_Angeles" });
app.line("+1 415 555 0134", {
greeting: "Brightside Dental. How can I help?",
answers: FrontDesk,
team: [Billing],
});
app.rule("Never say an amount of money that a tool did not give you.");
app.silence({ after: "8s", say: "Are you still there?", times: 2 });
app.on("visit.booked", (call, visit) => {
clinic.remind(visit);
});
export default app;
pinecall start finds the file and serves the project's agents with it. A save of it reloads them.
| you write | what it does |
|---|---|
voiceApp(name, { timezone }) |
the app, named like its project. timezone is the zone every agent reads its day and its clock in |
app.line(number, { greeting, answers, team }) |
which agent answers a number, the words the call opens with, and who the call may pass to |
app.rule("…") |
a rule every agent of the app keeps |
app.silence({ after, say, times }) |
what any agent says to a caller who went quiet |
app.on(name, handler) |
your code, run when something happens on a call |
The line#
app.line("+1 415 555 0134", {
greeting: "Brightside Dental. How can I help?",
answers: FrontDesk,
});
greeting is said as written the moment the call comes in, before any model runs. answers is the
agent on the call when it starts. app.line(number, FrontDesk) is the short form, with no greeting.
The number is still your org's. Point it at the agent with pinecall numbers; until then,
pinecall start says once that the line's number does not ring at that agent, and the chat and the
web work all the same.
The timezone#
const app = voiceApp("brightside-dental", { timezone: "America/Los_Angeles" });
Every agent of the app is told the date, the weekday and the hour in that zone as a call opens, so
"tomorrow at nine" is counted on the clinic's clock and not on a server's. this.call.today is that
day too. An agent with no app says it itself: @agent({ timezone: "America/Los_Angeles" }).
A rule every agent keeps#
app.rule("Never say an amount of money that a tool did not give you.");
The rule is read into the prompt of every agent of the app. It also adds a judge that asks, of each
finished call, whether the rule was kept: the call's score says so. The judges are named
app-rule-1, app-rule-2, in the order the rules are written. The judge reads the call and its evidence: the
documents searched, the tools' answers and the state, so a rule about what an agent may say is held to what the
call gave it.
An agent's declared judges are its whole list. In an app with rules, name the ones of Pinecall's you want beside them in the class:
@agent({ judges: ["grounded"] }).
What the app hears#
app.on("visit.booked", (call, visit) => {
clinic.remind(visit);
});
app.on("call.ended", (call, ended) => {
db.calls.insert({ call: call.id, agent: call.agent, reason: ended.reason });
});
app.on(name, handler) runs your function on every entry of that name, on any call of the app's
agents. The name is one of two things:
| the name | what it hears |
|---|---|
| an entry of the call's log, by its type | call.started, call.ended, call.score, handoff when a call passes to a teammate |
| a line an agent logs, by the name it gave it | this.log("visit.booked", visit) in a tool reaches app.on("visit.booked", …) |
The handler is told the call (id, agent) and what the entry carries. The handlers run in the
process that serves your agents: what happens on a call while it is down is not heard later. What
has to happen later, or survive a restart, is a flow: app.on("visit.booked", remindVisit).
The app's page#
app.page("ui/dist");
An app can have a page of its own, drawn by its agents. app.page names the folder the page's build
writes. pinecall deploy sends it with the release, and Pinecall serves it at the app's own name:
https://brightside-dental--acme.app.pinecall.io production
https://brightside-dental--acme--sandbox.app.pinecall.io the sandbox
A page may be one environment's alone: app.page("site", { only: "sandbox" }) is a guide or a demo
beside the agent while it is tried, and a deploy to production then sends the app alone, with no
page. only: "production" is the other way round. Left out, the page is in both.
The page has no server and holds no key. It asks its own name for a visitor's ticket, and Pinecall
answers after a captcha. With @pinecall/room that is one line:
const call = useRoom(hosted());
What the page shows is up to the agents. Each one has a screen() beside its tools that returns
parts from its state (an agenda, a form, a ticket), and the page draws each part with a component of
its own:
override screen() {
if (this.visit !== null) return <Ticket visit={this.visit} />;
return <Agenda slots={this.slots} />;
}
pinecall start serves the same page on http://localhost:4747 while you write it.
The whole of it, the parts, the taps and the deploy, is in Pages & screens.