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

Volcengine
BytePlus

Prepare an API key and an available model in the Ark console, then set:

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"

Prepare an API key and an available model in the BytePlus ModelArk console, then set:

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"

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

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

Create and run an agent

Create main.py in your project directory:

main.py

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:

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:

config.yaml

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

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Prerequisites

Configure a model

Create and run an agent

Optional: Use a configuration file

Troubleshoot the first run

​Prerequisites

​Configure a model

​Create and run an agent

​Optional: Use a configuration file

​Troubleshoot the first run

Prerequisites

Configure a model

Create and run an agent

Optional: Use a configuration file

Troubleshoot the first run