> ## Documentation Index
> Fetch the complete documentation index at: https://vida.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookbook: Build and Launch an Agent

> Create or select an Agent account, configure staging, test it, publish it, and verify the live result.

Use this workflow when an API client or external AI agent must take a conversational Agent from an
authorized account to a verified production configuration.

## Required inputs

* an authorized Vida API token
* the organization account ID
* the intended Agent account, or approval to create one
* the business workflow and acceptance criteria
* approval for writes that can affect billing or production behavior

Keep `targetAccountId`, Agent-account IDs, and `agentConfigId` values distinct. Read IDs from Vida;
do not reconstruct them from names.

## 1. Resolve the account

1. [Read the authenticated or selected account](/docs/api-reference/accounts/get-account-details).
2. Confirm its type, parent organization, enabled capabilities, and intended customer.
3. [List Agent accounts](/docs/api-reference/accounts/list-agent-accounts) under the organization.
4. Reuse the intended Agent account, or create one only after confirming the account and billing
   impact.

Save the returned Agent account ID. Use it as `targetAccountId` for Agent-scoped operations.

## 2. Discover available capabilities

Do not copy model, voice, function, or app identifiers from another account.

* [List supported models](/docs/api-reference/models/list-supported-ai-models).
* [List Agent voices](/docs/api-reference/agents/list-agent-voices).
* [List Agent functions](/docs/api-reference/agents/list-agent-functions).
* [List Agent apps](/docs/api-reference/apps/list-agent-apps).

Read the detail for every app or function that has setup requirements.

## 3. Read and update staging

1. [Read staging](/docs/api-reference/agents/fetch-staging-agent).
2. Preserve writable values the user did not ask to change, especially authored arrays.
3. [Update staging](/docs/api-reference/agents/update-staging-agent-configuration) with only approved
   writable settings.
4. Read staging again and compare the complete persisted result with the intended configuration.

Do not send calculated response fields, effective inherited values, or IDs from the live
configuration back as authored staging settings.

## 4. Resolve dependencies

Before testing:

* install and verify required apps
* configure functions and their destinations
* connect phone, SMS, SIP, email, or web channels as needed
* provision and verify a Computer Agent before adding Computer-only capabilities
* create reporting fields with stable keys

If a connection requires credentials, use its supported setup flow rather than adding credentials
to Agent instructions.

## 5. Test the prepared Agent

Test the successful path, missing information, refusal or unsupported work, escalation, and every
external side effect. Use a real representative channel when possible.

For an authorized outbound test, create a Task for the selected Agent and inspect its terminal
result, attempt history, log, and conversation. Verify any external action in the destination
system.

Optionally [review the Agent configuration](/docs/api-reference/agents/review-an-agent-configuration),
but do not treat automated review as a substitute for a representative test.

## 6. Save and publish

1. Optionally [save a named version](/docs/api-reference/agents/save-agent-version) for recovery or an
   experiment.
2. Obtain explicit approval for the production change.
3. [Publish staging](/docs/api-reference/agents/publish-an-agent).
4. [Read the live Agent](/docs/api-reference/agents/fetch-live-agent) independently.

## 7. Verify production

Run one production-path interaction and confirm:

* the request reached the intended Agent and channel
* the live configuration matches the approved staging result
* functions, apps, and transfers worked in their destination systems
* the log and complete conversation are available
* reporting fields contain defensible values

## Completion evidence

Report the organization and Agent account IDs, staging and live `agentConfigId` values, saved
version ID when created, publish result, representative Task or conversation reference, and the
external verification performed. Do not report completion from the publish response alone.