AI-assisted development (optional)

AI-assisted development (optional)#

You do not need anything in this section. The complete Vitis AI flow, from quantization through compilation to deployment, is fully documented and fully usable without an AI coding assistant, without a large language model, and without any of the material that follows. Nothing here is part of installing or using Vitis AI.

This section explains how to set up a coding assistant and a language model so you can run the Vitis AI AI-assisted workflows, which automate tasks such as custom operator development and compiler configuration tuning. The workflows themselves, what each one does and the manual procedure it corresponds to, are described in AI-Assisted Workflows Reference.

Note

AI Analyzer includes a separate chat box that answers questions about your profiling results. It is documented in AI Analyzer. It uses a language model, configured as described in Configure model access, but involves no coding assistant and none of the setup that follows.

Vitis AI Workflows#

Vitis AI does not bundle a coding assistant or a language model, and does not prefer one. The workflows are plain files that run inside whichever assistant you already use, against whichever model provider your organization permits. You supply:

  • A coding assistant. Any assistant that supports the skill and agent file conventions. See Coding Assistant for ones AMD has tried.

  • A model endpoint and credentials. Any provider, your organization’s internal gateway, or a self-hosted model. See Configure model access.

  • A Vitis AI installation that includes the flexml_extras package, which is where the workflow files ship.

  • Access to a board. The workflows steer themselves using measurements taken on hardware. Without one they fall back on simulation and host-side results, which degrades every workflow.

A sandboxed environment and version control are strongly recommended rather than required; see Example: Claude Code in the Vitis AI Docker container.

Note

On disk, each workflow is a skill, which may delegate sub-tasks to helper agents that ship alongside it. You never invoke the skills or the helper agents individually. This distinction matters only when copying the files into your assistant, where both the skills and agents directories need to go across. See Copy workflow files.

Read the following three notices before running any workflow.

Warning

Your data is sent to your model provider. To do their work, the workflows transmit content from your working directory to the model endpoint you configure. This can include source code, ONNX models, tensor shapes and layer names, compiler configuration files, and build logs. The same applies to the AI Analyzer chat box, which sends your profiling data.

AMD does not operate the endpoint, does not receive this data, and cannot control its retention or use. Before enabling these features on confidential or third-party material, confirm that your chosen provider and its data retention terms are approved by your organization. If your organization operates an internal LLM gateway, route requests through it.

Important

These workflows run as autonomous agents. They create and modify files in your working directory, run compilation and simulation commands, and can iterate for extended periods without further input. Always:

  • Run them in a sandboxed environment, such as the container described in Example: Claude Code in the Vitis AI Docker container.

  • Keep your work under version control, so that you can review and revert every change made on your behalf.

  • Review generated kernels, tilers, and configuration files before using them in production.

Note

Model usage is billed by your provider. Agentic workflows consume substantially more tokens than interactive chat, because the assistant reads files, runs tools, and iterates on the results. A single custom operator session can run for an hour or more. Check your provider’s pricing and set spending limits before starting long runs.

Workflow Setup#

This is the only setup in the guide that involves a coding assistant, and it applies to nothing else. Skip it entirely unless you have decided to use the workflows.

There are three parts: choosing an assistant, giving it access to a model, and copying the workflow files into it.

Coding Assistant#

The workflows are ordinary skill and agent files, so any assistant that reads those conventions can run them. AMD tests them with Claude Code, and has tested them minimally with VS Code with GitHub Copilot and Cursor. The procedures here assume Claude Code.

If you already use a different assistant, keep it. Consult its documentation for the directories it scans, and copy the workflow files there.

Tip

The tested configuration is Claude Code with agent teams enabled:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

AMD recommends Opus 5. In assistants that pick a model automatically, such as Cursor or VS Code, select the model by hand; relying on automatic selection materially degrades results.

The workflows go faster with sub-agent support, because they delegate sub-tasks to helper agents that can run in parallel. Assistants without it run the same work sequentially in a single context, which also makes long sessions more likely to lose state; ask for periodic summaries if you are using one.

Note

Two practical points about long sessions:

  • The assistant frequently asks for approval to execute commands, which becomes tedious over a long run. Running it inside a sandbox with the permissions granted in advance avoids this. See Example: Claude Code in the Vitis AI Docker container.

  • Run CLI assistants under tmux, or another terminal multiplexer, so that a dropped connection does not lose an hour of work.

Configure model access#

Your assistant needs a credential, an endpoint, and a model identifier. The AI Analyzer chat box uses the same three values, which is why this subsection is also the reference for AI Analyzer.

Where you set them depends on what is consuming them. AI Analyzer reads them from the environment when it launches. A coding assistant reads them according to its own documentation, which is usually the environment as well. Treat the following as the checklist, and your provider’s and assistant’s documentation as the authority.

What you supply

Always

Notes

API key or token

Yes

Issued by your model provider or your organization’s LLM gateway.

Endpoint URL

No

Needed when routing through an internal gateway, a proxy, or a self-hosted OpenAI-compatible server. Omit to use the provider’s public endpoint.

Model identifier

Yes

The provider’s name for the model, for example a specific Claude, GPT, or locally served model.

Additional headers

No

Some enterprise gateways expect a project, tenant, or cost-center header. Consult your internal guidance.

Example: the public Anthropic endpoint

export ANTHROPIC_API_KEY=<API_KEY>
export ANTHROPIC_MODEL="opus[1m]"

Example: an OpenAI-compatible endpoint, such as an internal gateway or a local server

export ANTHROPIC_BASE_URL=https://<your-gateway-host>/v1
export ANTHROPIC_AUTH_TOKEN=<GATEWAY_TOKEN>
export ANTHROPIC_MODEL=<model-id-served-by-your-gateway>

Self-hosted runtimes that expose an OpenAI-compatible API, such as vLLM or Ollama, can be configured the same way, by pointing the base URL at the local server. AMD has not validated the workflows against locally served models; quality of the generated artifacts depends heavily on model capability.

Caution

Protect your API key. Do not hard-code it into scripts, configuration files, container images, or anything under version control.

Prefer a permission-restricted file over shell exports, which persist in shell history and in world-readable dotfiles:

touch "$HOME/.vitis_ai_llm_env"
chmod 600 "$HOME/.vitis_ai_llm_env"
# add the export lines to that file, then source it
echo 'source "$HOME/.vitis_ai_llm_env"' >> "$HOME/.bashrc"

If you run inside the Vitis AI Docker container, see Example: Claude Code in the Vitis AI Docker container for how to persist this across container restarts, and note that the file lands on the host through the bind mount.

Copy workflow files#

The workflow files ship with the product installation, as part of the flexml_extras package, in a directory named ai_utils. Export its location:

export CUSTOMOP_SKILL=/usr/local/lib/python3.12/dist-packages/flexml/flexml_extras/ai_utils

Copy the whole directory. ai_utils contains two subdirectories, and both need to go across:

ai_utils/
  skills/    # Task definitions. One per workflow, plus supporting skills.
  agents/    # Helper agents that the task definitions delegate work to.

Copying only one of the two produces a workflow that starts and then fails partway through. For what each subdirectory contains, see Bundled examples and utilities.

Each assistant discovers these files from a different directory. Follow the tab for the assistant you use. For an assistant not listed here, consult its documentation for the directories it scans, and copy the contents of ai_utils there.

Claude Code discovers skills from .claude/skills/ and agents from .claude/agents/ in your project directory, or from the equivalent paths under ~/.claude/ for a personal installation available in every project.

Project level, convenient for team sharing:

# From your project root
mkdir -p .claude
cp -r "$CUSTOMOP_SKILL"/* .claude/

User level, available across all your projects:

mkdir -p ~/.claude
cp -r "$CUSTOMOP_SKILL"/* ~/.claude/

Copilot discovers these files from .agents/ at the root of your workspace:

# From your project root
mkdir -p .agents
cp -r "$CUSTOMOP_SKILL"/* .agents/

Cursor discovers these files from .agents/ or .cursor/:

# From your project root
mkdir -p .cursor
cp -r "$CUSTOMOP_SKILL"/* .cursor/

To see everything Cursor discovered, open Cursor Settings, then Rules, then Agent Decides. For more information, see https://cursor.com/docs/skills.

Verify#

Start your assistant from your project root, open its chat, and type /. The Vitis AI workflows appear in the list. Verify that the entry point skills appear as shown in the AI-assisted workflows table below.

A prompt, such as asking a workflow to describe what it would do, confirms that the model credentials work before you start a long session.

Troubleshooting#

Model access

Symptom

Action

Authentication or 401 errors

The credential is missing from the environment the assistant was launched from. Confirm the variable is exported in that shell, and that any gateway-specific base URL and headers are set.

Model not found, or 404 on the endpoint

The model identifier does not match one your endpoint serves. Check the exact identifier with your provider or gateway administrator.

Rate limit or quota errors during a long run

Expected on shared gateways under agentic load. Retry, reduce concurrency, or request a higher quota.

AI-assisted workflows

Symptom

Action

No workflows listed after typing /

Confirm that both the skills and agents subdirectories were copied, that they are in the directory your assistant scans, and that you started the assistant from your project root.

A workflow starts, then fails when delegating a sub-task

The helper agents under agents are missing, or your assistant does not support sub-agents. See the tip in Coding Assistant.

A workflow runs but produces poor artifacts

Check the model in use. Smaller or older models are markedly weaker at kernel and tiler authoring. See the validated configuration in Coding Assistant.

Example: Claude Code in the Vitis AI Docker container#

This is a worked example that combines the preceding subsections into a single validated setup, using Claude Code inside the Vitis AI Docker container. Running the assistant in the container gives you a sandboxed environment with the permissions granted in advance, which avoids repeated approval prompts and keeps execution isolated from the host.

Adapt these steps for a different assistant or provider. The container setup, HOME persistence, and file copying apply regardless of which assistant you choose; only the assistant installation and the model environment variables are Claude-specific.

This example covers the AI-assisted workflows. The container setup and model configuration in Steps 1, 2, and 4 also apply if you run AI Analyzer in the container; see AI Analyzer.

Placeholders#

Replace each placeholder with a value appropriate for your setup.

Placeholder

Meaning

WORKDIR

Host directory for your development work, including models, outputs, and scratch files. Bind-mounted into the container at the same path and used as both HOME and the working directory.

CONTAINER_NAME

Any unique name for the running container.

LICENSE_DIR

Host directory containing your license files.

IMAGE_TAG

Vitis AI Docker image name and tag, as printed by docker load.

API_KEY

Your API subscription key for your chosen model provider.

Caution

WORKDIR holds your assistant’s configuration, including its credential file. Choose a directory with appropriate permissions, and avoid shared or automatically backed-up locations if your organization’s policy prohibits storing API keys there.

Export these values on the host:

export WORKDIR=/path/to/your/work
export CONTAINER_NAME=vitis_ai_2ve_$USER
export LICENSE_DIR=/path/to/your/licenses

Step 1: Load the image#

docker load -i <path-to-image-archive>

docker load prints the image name and tag. Use that value as IMAGE_TAG:

export IMAGE_TAG=<image-name-and-tag-printed-by-docker-load>

Step 2: Start the container#

mkdir -p "$WORKDIR/homedir"

docker run -it --rm \
  --name "$CONTAINER_NAME" \
  --net=host \
  --ulimit stack=-1:-1 \
  -v "$WORKDIR":"$WORKDIR" \
  -v "$LICENSE_DIR":/usr/licenses \
  -w "$WORKDIR" \
  -u $(id -u):$(id -g) \
  -e USER="$USER" \
  -e HOME="$WORKDIR/homedir" \
  "$IMAGE_TAG" \
  bash

Note

  • WORKDIR is bind-mounted at the same path inside the container, so commands and configuration files that reference absolute paths behave identically inside and outside the container.

  • The homedir subdirectory under WORKDIR is used as HOME, so assistant configuration and installed binaries persist between container runs and survive the --rm flag.

  • --net=host gives the container direct access to your host network, which the assistant uses to reach the model endpoint.

Step 3: Install the assistant#

For Claude Code, run the following inside the container:

curl -fsSL https://claude.ai/install.sh | bash

This installs Claude Code under ~/.local/bin/, which persists on the host through the homedir bind mount. For a different assistant, install it inside the container so that it can invoke the Vitis AI tools directly.

Step 4: Configure model access#

Set the variables your assistant expects, as described in Configure model access. For Claude Code:

touch "$HOME/.llm_env" && chmod 600 "$HOME/.llm_env"
cat >> "$HOME/.llm_env" <<'EOF'
export ANTHROPIC_API_KEY=<API_KEY>
export ANTHROPIC_MODEL="opus[1m]"
EOF
echo 'source "$HOME/.llm_env"' >> "$HOME/.bashrc"
source "$HOME/.llm_env"

Because HOME is bind-mounted, these files are under $WORKDIR/homedir on the host and survive container removal. Exclude homedir from version control.

Step 5: Copy workflow files#

From inside the container, in the project directory where you plan to run the assistant, which is typically $WORKDIR or a subdirectory of it:

export CUSTOMOP_SKILL=/usr/local/lib/python3.12/dist-packages/flexml/flexml_extras/ai_utils

mkdir -p .claude
cp -r "$CUSTOMOP_SKILL"/skills "$CUSTOMOP_SKILL"/agents .claude/

Both subdirectories are needed.

Step 6: Skip the onboarding and trust dialogs#

Pre-seed ~/.claude.json so that Claude Code does not prompt for onboarding or project trust on first launch. Run this from the directory where you plan to run Claude Code:

PROJECT_DIR="$PWD"
cat > ~/.claude.json <<EOF
{
  "hasCompletedOnboarding": true,
  "projects": {
    "$PROJECT_DIR": {
      "hasTrustDialogAccepted": true,
      "hasCompletedProjectOnboarding": true
    }
  }
}
EOF

Note

This accepts the project trust prompt on your behalf. Only do this for directories whose contents you trust, and only in the sandboxed container.

Step 7: Launch the assistant#

~/.local/bin/claude

If ~/.local/bin is on your PATH, run claude instead. Type / to confirm that the workflows are available. If they are not, see Troubleshooting.

Contents