FAQ

Each answer is short and links to the page that has the whole of it.

Building#

What do I write an agent in?#

TypeScript with @pinecall/agents, Ruby with the pinecall gem, or Python with the pinecall package. All three use the same pinecall CLI, the same gateway and the same goldens. An agent is a class: its fields are the call's state, its tools are what the model may do, and its docstrings are the prompt. See Agent overview.

What differs between TypeScript, Ruby and Python?#

Hosting. pinecall deploy runs TypeScript projects only and refuses a project with a Ruby or a Python agent in it. Those run on your own server with pinecall start --prod. See Run it on your own server.

Do I need to run any servers?#

No. On Pinecall Cloud the gateway, the workers and the console run at cloud.pinecall.io. While you build, pinecall start runs your agent on your laptop against your sandbox. To go live, pinecall deploy uploads the project and Pinecall runs it. See Deploy to Pinecall.

Models, voices and languages#

Which models, speech and voices can my agent use?#

Any vendor with a LiveKit plugin that the runtime installs: more than forty, for the model, the ears (speech to text) and the voice. pinecall providers lists every vendor and whether it is ready to run a call. pinecall voices --language en lists voices. You choose them with pinecall agent set --llm … --stt … --tts … --voice …, or in the console. They are settings of the agent, never part of the class. See Voice & model providers.

Do I need my own vendor keys?#

A vendor your org has no key for runs on Pinecall's own key, within what your plan allows. pinecall providers add <vendor> makes every call of your org run on your own account with that vendor. The key is read from stdin, stored sealed, and never shown again by the CLI or the console. See Limits & provider keys.

Which languages can it speak?#

pinecall agent set --language es sets the language of the voice and the ears, as a tag like en, es or pt-BR. One of the rules every prompt carries is to answer in the language the caller speaks. The sentences Pinecall itself says, the AI disclosure and the recording notice, exist in English, Spanish, Portuguese, French, German and Italian; for any other language they are said in English. Your org can write its own disclosure.

How fast does it answer?#

Every call measures its latency by stage, so you can see where the time goes: see Call metrics. The platform keeps waits short in three ways:

• A search in the knowledge base or in memory starts while the caller is still speaking. After they stop, a spoken turn waits at most 250 ms for it.
• A tool that takes longer than 2.5 seconds plays the agent's hold music, if it has one.
• A model that has said nothing after 12 seconds is cut off, and the caller is asked to repeat. An agent can set its own deadline.

Phone, WhatsApp and the web#

How do I get a phone number?#

A number belongs to a carrier account of your org. Connect a Twilio account with pinecall carriers add twilio, list its numbers with pinecall numbers available, and point one at your agent with pinecall numbers import <number> --agent <slug>. Numbers from Telnyx, Vonage or Plivo, and from your own PBX as a SIP peer, are pointed at Pinecall from the carrier's side. See Phone numbers.

Can the same agent answer WhatsApp and a website?#

Yes. A WhatsApp Business number is added with pinecall carriers add whatsapp and imported with --channel whatsapp; the agent answers it in writing. On a website, the web widget is one tag, and @pinecall/room is for a page you design yourself.

Can it call people?#

Yes. Outbound calls go through the org's dialling rules: calling hours, a daily limit per number, consent and the do-not-call list. See Calling out.

Testing#

How do I test an agent?#

At several levels. Unit tests check the class with no network. Goldens (pinecall test) replay written conversations through your agent, under every model you name. Personas (pinecall simulate) are callers a model plays, in writing or out loud. Every finished call is judged at hang-up, and pinecall eval checks one real call again. See Tests overview.

Hosting and open source#

Is Pinecall open source?#

Yes. The runtime, the @pinecall/agents framework, the pinecall CLI, the Ruby and Python SDKs and @pinecall/room are Apache-2.0. The web widget is MIT.

Can I run Pinecall myself?#

Yes. Pinecall Cloud runs the same open-source runtime you can run on your own Kubernetes cluster. Your agent does not change: you link the project to your gateway with pinecall link --gateway <url>. See Self-hosting.

Does Pinecall use LiveKit?#

Yes. Each spoken call runs on a worker that is a LiveKit agent, and every vendor is a LiveKit plugin. Your code never imports LiveKit. See How Pinecall works.

Does a deploy drop calls?#

No. When you deploy, the release before keeps answering until the new one has registered; then it hands its calls over and stops. See A deploy never cuts a call.

How is Pinecall priced?#

Plans and prices are on pinecall.io/pricing. The console's Usage screen shows what your org has used.

Data and privacy#

Can another org see my calls?#

No. Every request acts in the org its key belongs to, never one the request names, and the database holds each request to that org's rows.

Are calls recorded?#

By default, yes. pinecall agent set --record off stops recording an agent's calls, and --record on starts it again. Each recording is encrypted with a key of its own.

How do I erase or export data?#

pinecall data erase call <call-id> and pinecall data erase contact <number> delete for good, and pinecall data erasures lists what was erased. pinecall data policy --retention-days <n> sets how long calls are kept. pinecall data export writes everything your org holds in the sandbox, or in production with --prod, as JSON Lines. pinecall memory forget <contact> erases what memory kept about one person (asked once on a terminal; a script adds --yes). See Data & privacy.

Can a caller or a document take over the agent?#

No. Only your prompt, its rules and your tools give orders. What a search or memory returns reaches the model as a tool result it may weigh, never as an instruction. See Prompt injection.