pinecallDocs
Key concepts / Voice app overview

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.py and a Ruby project in app.rb, with the same lines, rules, teams and flows: the voice app in Python and in Ruby.

The app, whole#

app.ts
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#

TypeScript
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#

TypeScript
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#

TypeScript
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#

TypeScript
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#

TypeScript
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:

TypeScript
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:

TypeScript
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.

Next steps#