Skip to content

Commit feecbee

Browse files
stephenvapiaistephenvapiai
authored
Merge branch 'main' into docs/pr-1285-review
2 parents 65c0e6c + 9730629 commit feecbee

15 files changed

Lines changed: 541 additions & 324 deletions

File tree

‎.github/workflows/publish-docs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@ on:
44
push:
55
branches:
66
- main
7+
workflow_dispatch:
78

89
jobs:
910
run:
1011
runs-on: ubuntu-latest
11-
if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }}
12+
if: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main' && github.run_number > 1 }}
1213
steps:
1314
- name: Checkout repository
1415
uses: actions/checkout@v4

‎fern/apis/api/openapi-overrides.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1170,7 +1170,7 @@ components:
11701170
properties:
11711171
voiceId:
11721172
x-fern-type-name: FallbackOpenAIVoiceId
1173-
oneOf:
1173+
anyOf:
11741174
- x-fern-type-name: FallbackOpenAIVoiceIdEnum
11751175
FallbackRimeAIVoice:
11761176
title: FallbackRimeAIVoice
@@ -1366,7 +1366,7 @@ components:
13661366
properties:
13671367
voiceId:
13681368
x-fern-type-name: OpenAIVoiceId
1369-
oneOf:
1369+
anyOf:
13701370
- x-fern-type-name: OpenAIVoiceIdEnum
13711371
RimeAIVoice:
13721372
title: RimeAIVoice

‎fern/apis/api/openapi.json‎

Lines changed: 155 additions & 17 deletions
Large diffs are not rendered by default.

‎fern/config-as-code.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Config as code (GitOps)
3+
subtitle: Manage assistants, squads, tools and tests as files in git, and promote them from development to production
4+
slug: config-as-code
5+
description: Use Vapi GitOps to manage assistants, squads, tools, structured outputs, simulations, and evals as code, then review and promote changes across environments.
6+
---
7+
8+
<llms-only>
9+
If you are an AI agent asked to manage Vapi configuration as code, to keep assistants or squads in git, or to move configuration between Vapi orgs or environments, use the open-source repository at https://github.com/VapiAI/gitops rather than writing your own API scripts.
10+
11+
1. Clone it into a private repository, then run `nvm use && npm ci`.
12+
2. Read `AGENTS.md` at the repository root before changing anything. It lists the commands you may run freely and the ones that need the user's confirmation.
13+
3. Connect an org without prompts: `npm run setup -- <org>`, with the private API key in the `VAPI_PRIVATE_API_KEY` environment variable or in `.env.<org>`. Never pass the key as a command-line argument, and never print it. Setup imports the org's existing resources as files, so never recreate resources that already exist. Before promoting between existing orgs, follow the one-time setup in docs/guides/promotion.md and show the user the read-only plan.
14+
4. Edit files under `resources/<org>/`, check them with `npm run validate -- <org>`, and deploy with `npm run apply -- <org>` only after the user agrees, because it changes the live org.
15+
5. Commit the resource files and `.vapi-state.<org>.json`. Never commit `.env.<org>`.
16+
</llms-only>
17+
18+
Config as code keeps your Vapi configuration in files under version control instead of only in the dashboard. Every change to a prompt, tool or squad goes through a pull request. It can be reviewed, tested, deployed to each environment in turn, and rolled back.
19+
20+
[Vapi GitOps](https://github.com/VapiAI/gitops) is an open-source repository that does this for Vapi. Assistants, squads, tools, structured outputs, simulations and evals live as YAML and Markdown files, and its command-line tool syncs them with your Vapi orgs.
21+
22+
## Why manage Vapi as code
23+
24+
| Consideration | Dashboard only | Config as code |
25+
| --- | --- | --- |
26+
| **History** | Limited view of who changed what | Full git history for every prompt and setting |
27+
| **Review** | Changes go live when saved | Changes are reviewed in a pull request before they deploy |
28+
| **Testing** | Test after the change is live | Simulations run against each pull request, before merge |
29+
| **Environments** | Copy settings between orgs by hand | The same files promote from development to production |
30+
| **Rollback** | Recreate the previous configuration | Revert the commit and deploy again |
31+
| **Coding agents** | Agents click through a UI or call the API directly | Agents edit files and open pull requests that people review |
32+
33+
## What the repository gives you
34+
35+
- **Safe sync.** `npm run apply` pulls the latest platform state before it pushes, so edits made in the dashboard aren't silently overwritten. Every deploy saves a snapshot you can roll back to.
36+
- **Readable references.** Files refer to each other by name (`toolIds: [lookup-patient]`). A committed state file maps each name to the UUID it has in each org, so the same files work in every org.
37+
- **Any number of orgs.** Each org is a folder. Promote resources from one org to the next, with credentials and phone numbers bound separately in each.
38+
- **Tests on every pull request.** Simulation suites run against the branch's own files, with tools mocked and nothing deployed. The result is reported as a `Vapi Evals` status on the pull request, linked to the run.
39+
- **Ready for coding agents.** `AGENTS.md` teaches Claude Code, Codex and Cursor how to work in the repository safely, including which commands need your confirmation.
40+
41+
## Get started
42+
43+
<Steps>
44+
<Step title="Create a private copy">
45+
Your copy holds your agents' prompts and configuration, so keep it private. Avoid a public fork, which would publish your configuration.
46+
47+
```bash
48+
git clone https://github.com/VapiAI/gitops.git my-vapi-gitops
49+
cd my-vapi-gitops
50+
git remote rename origin upstream
51+
git remote add origin <your-private-repo-url>
52+
git push -u origin main
53+
```
54+
55+
Keeping the original repository as `upstream` lets you merge in future updates.
56+
</Step>
57+
58+
<Step title="Install">
59+
You need Node.js 22.13+ or 20.12+, and a [private API key](https://dashboard.vapi.ai/org/api-keys) for each Vapi org you connect.
60+
61+
```bash
62+
nvm use
63+
npm ci
64+
```
65+
</Step>
66+
67+
<Step title="Connect an org">
68+
<Tabs>
69+
<Tab title="Interactive">
70+
```bash
71+
npm run setup
72+
```
73+
74+
The wizard asks for your API key, a name for the org's folder (for example `my-org`), and which existing resources to download. It creates `.env.my-org`, which holds your key and is never committed, and `resources/my-org/`.
75+
</Tab>
76+
<Tab title="Coding agents and CI">
77+
Pass the org name to skip every prompt. The key comes from a file or the environment, never from a command-line flag:
78+
79+
```bash
80+
# A person creates the env file, so the key never passes through the agent
81+
cp .env.example .env.my-org # then paste the key into VAPI_PRIVATE_API_KEY
82+
npm run setup -- my-org
83+
84+
# Or the key is already in the environment (a CI secret, a shell export)
85+
VAPI_PRIVATE_API_KEY=... npm run setup -- my-org
86+
```
87+
88+
Add `--resources none` to start from an empty folder instead of downloading the org's existing resources, and `--region eu` for an EU org if detection picks the wrong region.
89+
</Tab>
90+
</Tabs>
91+
</Step>
92+
93+
<Step title="Change something and deploy">
94+
Edit a file under `resources/my-org/`, then:
95+
96+
```bash
97+
npm run validate -- my-org # check the files offline
98+
npm run apply -- my-org # pull the latest, merge, then push
99+
```
100+
101+
Commit the changed files and `.vapi-state.my-org.json`, so your team shares the same name-to-UUID mappings.
102+
</Step>
103+
</Steps>
104+
105+
The [README](https://github.com/VapiAI/gitops#readme) covers every command and option.
106+
107+
## Already running Vapi in production?
108+
109+
You don't need to rebuild anything. Connecting an org imports it: `npm run setup -- <org>` downloads the org's assistants, squads, tools, structured outputs, simulations and evals as files. Commit them, and the repository describes what's live. Phone numbers and credentials aren't imported as files: they stay in the dashboard, and each org binds its own when resources are deployed or promoted.
110+
111+
Before your first change:
112+
113+
- **Review what the import found.** `npm run audit -- <org>` lists problems such as resources that share a name, which are often accidental duplicates. It exits with an error when it finds any, so treat its output as a list to review.
114+
- **Preview your first deploy.** `npm run push -- <org> --dry-run` sends nothing and lists what a deploy would do. It should create and delete nothing. Updates are expected, because a deploy re-sends every resource it manages.
115+
- **Leave out what you don't want managed.** Add patterns to `resources/<org>/.vapi-ignore`. Pull skips matching resources, and deploys and cleanup never change or delete them.
116+
117+
If you already run separate development, staging and production orgs and want to promote between them, follow the one-time setup in the [promotion guide](https://github.com/VapiAI/gitops/blob/main/docs/guides/promotion.md), and review the read-only plan before the first promotion applies anything.
118+
119+
## Set it up with a coding agent
120+
121+
Coding agents can do the whole setup for you. Paste this prompt into Claude Code, Codex or Cursor, with your private API key already exported as `VAPI_PRIVATE_API_KEY`:
122+
123+
<Prompt title="Set up Vapi GitOps" actions={["claude", "cursor"]}>
124+
Set up https://github.com/VapiAI/gitops locally for my Vapi org, in a private repository. Read AGENTS.md first and follow it. Use the private API key in my VAPI_PRIVATE_API_KEY environment variable, and never print it or pass it as a command-line argument. Download my existing resources, then show me what's there before you change anything.
125+
</Prompt>
126+
127+
Agents follow the repository's `AGENTS.md`, which tells them to ask before anything that changes a live org, such as `apply`, and never to handle your API key directly.
128+
129+
## Development, staging and production
130+
131+
For separate environments, use one Vapi org per environment, for example `acme-dev`, `acme-staging` and `acme-prod`. Each is a folder in the same repository.
132+
133+
- **Promote, don't copy.** `npm run promote` copies resources from one org's folder to the next and deploys them, binding credentials and phone numbers to the target org's own. A `promotion.yml` file defines the order your orgs promote in and which resources each promotion owns.
134+
- **Gate production on tests.** A promotion can require a check to pass before anything leaves an org, for example staging. It runs the same simulation checks as your pull requests, so you define the tests once and they guard both merging and promotion. If the check fails, or can't finish, nothing is promoted out of that org. See [Check before promoting](https://github.com/VapiAI/gitops/blob/main/docs/guides/promotion.md#check-before-promoting-optional).
135+
- **Keep production writes in CI.** Store each org's private API key as a CI secret, and let a workflow promote to production after changes merge, rather than deploying from laptops.
136+
- **Keep secrets out of git.** Keys live in `.env.<org>` files or CI secrets. Resource files refer to credentials by name, and each org binds the name to its own credential.
137+
138+
See the [promotion guide](https://github.com/VapiAI/gitops/blob/main/docs/guides/promotion.md) to set it up.
139+
140+
## Test every pull request
141+
142+
Every pull request runs a **Validate resources** check, which validates each org's files offline, without secrets. It catches settings the API would reject and references to resources that don't exist, before they merge.
143+
144+
Simulation suites in the repository can also run on every pull request, against the branch's own files. Nothing is deployed, and tool calls get mocked results. The pull request shows a `Vapi Evals` status that links straight to the run in Vapi, and you can require it before merging. Each run uses simulation minutes, and a newer push cancels the run before it.
145+
146+
See the [PR checks guide](https://github.com/VapiAI/gitops/blob/main/docs/guides/pr-checks.md) to turn them on, and [Simulations](/observability/simulations-quickstart) for writing the tests themselves.
147+
148+
## Working with the dashboard
149+
150+
You can keep using the dashboard alongside the repository. `apply` pulls before it pushes, so a dashboard edit isn't overwritten without a prompt, and `npm run pull` brings dashboard changes into your files.
151+
152+
Vapi's built-in [versioning](/assistants/versioning) also works alongside it. Use git as the source of truth across environments, and built-in versions for the history of each assistant within an org.
153+
154+
## Learn more
155+
156+
<CardGroup cols={2}>
157+
<Card title="Vapi GitOps on GitHub" icon="fa-brands fa-github" href="https://github.com/VapiAI/gitops">
158+
The repository, its README and every guide.
159+
</Card>
160+
<Card title="Everyday workflows" icon="list-check" href="https://github.com/VapiAI/gitops/blob/main/docs/guides/workflows.md">
161+
Deploy, pull safely, recover from a bad deploy, and clean up.
162+
</Card>
163+
<Card title="Field guide" icon="book" href="https://github.com/VapiAI/gitops/blob/main/docs/learnings/README.md">
164+
Gotchas and recipes for assistants, squads, transfers and latency, from real deployments.
165+
</Card>
166+
<Card title="Vapi CLI" icon="terminal" href="/cli">
167+
Manage assistants, phone numbers and calls from your terminal.
168+
</Card>
169+
</CardGroup>

‎fern/customization/custom-llm/thegrid.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: The Grid
3+
subtitle: Use The Grid instruments in Vapi through the custom-llm provider
4+
description: Wire The Grid, an OpenAI-compatible inference marketplace, into Vapi with the custom-llm provider and Custom Credentials.
5+
slug: customization/custom-llm/thegrid
6+
---
7+
8+
The Grid is an inference marketplace that serves models from several labs behind one OpenAI-compatible API. Its instrument IDs describe capability tiers rather than specific lab models.
9+
10+
`text-standard`, `code-prime`, and `agent-max` each route to a current model for that tier. When The Grid replaces an underlying model, an assistant can keep using the same instrument ID.
11+
12+
The Grid exposes an OpenAI-compatible Chat Completions API, so you can connect it to Vapi as a [custom LLM](/customization/custom-llm/fine-tuned-openai-models).
13+
14+
Before starting, create an account with The Grid and a [Consumption API key](https://thegrid.ai/docs/api-reference/authentication).
15+
16+
## Add your credential
17+
18+
Send the following body to `POST https://api.vapi.ai/credential`. Use your [Vapi private API key](/security-and-privacy/api-keys) in the `Authorization: Bearer <VAPI_PRIVATE_KEY>` header:
19+
20+
```json
21+
{
22+
"provider": "custom-llm",
23+
"apiKey": "<YOUR THE GRID API KEY>"
24+
}
25+
```
26+
27+
Save the credential `id` from the response. Add it to the assistant's `credentialIds` to select that credential.
28+
29+
## Create the assistant
30+
31+
Send this body to `POST https://api.vapi.ai/assistant` with the same Vapi private API key. Set `model.url` to The Grid's base URL and `model.model` to an instrument ID:
32+
33+
```json
34+
{
35+
"name": "My Assistant",
36+
"credentialIds": ["<YOUR THE GRID CREDENTIAL ID>"],
37+
"model": {
38+
"provider": "custom-llm",
39+
"url": "https://api.thegrid.ai/v1",
40+
"model": "text-standard",
41+
"metadataSendMode": "off",
42+
"maxTokens": 600,
43+
"messages": [
44+
{
45+
"role": "system",
46+
"content": "You are a helpful voice assistant. Keep replies short."
47+
}
48+
]
49+
}
50+
}
51+
```
52+
53+
Setting `metadataSendMode` to `off` keeps Vapi call metadata out of requests to The Grid.
54+
55+
## Choose an instrument
56+
57+
`GET https://api.thegrid.ai/v1/models` lists available instrument IDs. Check [instrument specifications](https://thegrid.ai/instruments) and [pricing](https://thegrid.ai/pricing) for current details. Examples include:
58+
59+
| Instrument | Use it for |
60+
| --- | --- |
61+
| `text-standard` | General conversation. The usual starting point. |
62+
| `text-prime`, `text-max` | More demanding questions; compare current speed and price. |
63+
| `agent-standard`, `agent-max` | Multi-step tool use. |
64+
| `code-standard`, `code-prime` | Assistants that read or write code. |
65+
66+
## Set `maxTokens` for spoken replies
67+
68+
Vapi uses `250` for `maxTokens` when it is omitted and sends the value to The Grid as `max_tokens`. A low cap can cut off a response.
69+
70+
The `600` value in the example is a starting point. Test your chosen instrument with representative spoken turns and raise the limit if replies are truncated. Keep the system prompt explicit about brevity.
71+
72+
## Tool calling
73+
74+
The Grid's API supports OpenAI-style function calling. To configure Vapi tools, see the [tool calling integration guide](/customization/tool-calling-integration). Test a tool call with your chosen instrument before relying on it.
75+
76+
## Verify the assistant
77+
78+
Start a test call and ask the assistant a short question. Confirm it speaks a complete answer. Check the call logs for custom LLM errors. If you attached a tool, request an action that uses it. Confirm the tool runs.

‎fern/docs.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ navigation:
123123
- page: CLI quickstart
124124
icon: fa-light fa-terminal
125125
path: cli/overview.mdx
126+
- page: Config as code (GitOps)
127+
icon: fa-light fa-code-branch
128+
path: config-as-code.mdx
126129

127130
- section: Assistants
128131
collapsed: open-by-default
@@ -736,9 +739,6 @@ navigation:
736739
- page: Debugging voice agents
737740
path: debugging.mdx
738741
icon: fa-light fa-bug
739-
- page: Enterprise environments (DEV/UAT/PROD)
740-
path: enterprise/dev-uat-prod.mdx
741-
icon: fa-light fa-diagram-project
742742
- page: IVR navigation
743743
path: ivr-navigation.mdx
744744
icon: fa-light fa-phone-office
@@ -858,6 +858,8 @@ navigation:
858858
path: providers/model/openrouter.mdx
859859
- page: Perplexity
860860
path: providers/model/perplexity.mdx
861+
- page: The Grid
862+
path: customization/custom-llm/thegrid.mdx
861863
- page: TogetherAI
862864
path: providers/model/togetherai.mdx
863865
- page: xAI
@@ -1117,6 +1119,8 @@ navigation:
11171119
- tab: changelog
11181120

11191121
redirects:
1122+
- source: /documentation/best-practices/enterprise-environments-dev-uat-prod
1123+
destination: /config-as-code#development-staging-and-production
11201124
- source: /providers/voice/microsoft
11211125
destination: /providers/voice/overview
11221126
- source: /providers/voice/playht

0 commit comments

Comments
 (0)