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

# Quickstart

Configure a model, create an agent, and execute a conversation with `Runner` to see the model's answer in your terminal

## Prerequisites

* Complete the [installation](/productions/veadk/preview/en/get-started/installation) and activate the Python environment containing VeADK
* Obtain a Volcengine Ark or BytePlus ModelArk API key with permission to call your chosen model
* The environment variable examples use Bash or zsh. Configure and run the example in the same terminal

## Configure a model

Select the platform hosting your model. Use an API key issued by that platform and replace the model name with one available to your account

<Tabs>
  <Tab title="Volcengine">
    Prepare an API key and an available model in the [Ark console](https://console.volcengine.com/ark), then set:

    ```bash lines theme={null}
    export CLOUD_PROVIDER="volcengine"
    export MODEL_AGENT_PROVIDER="openai"
    export MODEL_AGENT_NAME="doubao-seed-2-1-pro-260628"
    export MODEL_AGENT_API_BASE="https://ark.cn-beijing.volces.com/api/v3/"
    export MODEL_AGENT_API_KEY="your-ark-api-key"
    ```
  </Tab>

  <Tab title="BytePlus">
    Prepare an API key and an available model in the BytePlus ModelArk console, then set:

    ```bash lines theme={null}
    export CLOUD_PROVIDER="byteplus"
    export MODEL_AGENT_PROVIDER="openai"
    export MODEL_AGENT_NAME="seed-2-0-lite-260228"
    export MODEL_AGENT_API_BASE="https://ark.ap-southeast.bytepluses.com/api/v3"
    export MODEL_AGENT_API_KEY="your-modelark-api-key"
    ```
  </Tab>
</Tabs>

`MODEL_AGENT_PROVIDER=openai` selects the OpenAI-compatible protocol. Requests go to the platform address in `MODEL_AGENT_API_BASE`. This example sets the model, address, and credentials explicitly so it does not depend on version-specific defaults

<Warning>
  Running the example sends the prompt to the selected model service and may incur model charges. Use test content and keep real API keys out of example files and version control
</Warning>

## Create and run an agent

Create `main.py` in your project directory:

```python main.py lines theme={null}
import asyncio

from veadk import Agent, Runner

agent = Agent()
runner = Runner(agent=agent)

res = asyncio.run(runner.run(messages="Introduce Volcengine in one sentence."))
print(res)
```

`Agent` defines the model, instructions, and tools. `Runner` executes the conversation. Here, `Agent()` uses the model configuration set earlier, and `runner.run(...)` returns the response text

Run the script from the directory containing `main.py`:

```bash lines theme={null}
python main.py
```

The terminal displays execution logs and the model's answer. A nonempty answer indicates that the call completed. The model generates the answer, so its wording can vary

## Optional: Use a configuration file

To reuse nonsensitive model settings, create `config.yaml` beside `main.py`. This example configures Volcengine Ark; continue supplying the API key through the environment:

```yaml config.yaml lines theme={null}
model:
  agent:
    provider: openai
    name: doubao-seed-2-1-pro-260628
    api_base: https://ark.cn-beijing.volces.com/api/v3/
```

VeADK searches for `config.yaml` from the current working directory upward. Existing environment variables take precedence over matching file settings. Editing the file does not override model settings exported earlier. See [Models](/productions/veadk/preview/en/components/agent/model) for additional options

## Troubleshoot the first run

| Symptom | Check and action |
| - | - |
| Python cannot find the `veadk` module | Activate the environment used for installation and run the installation page's version check with the current Python interpreter |
| Model authentication or authorization fails | Confirm that the API key is exported in this terminal and matches the service address and required model permissions |
| The model is missing or unavailable | Check the model name and availability in the platform, then update `MODEL_AGENT_NAME` |
| Editing `config.yaml` does not change the model | Check for matching environment variables; remove stale values or update them before rerunning |