Troubleshooting Guide

This guide is intended to help you diagnose and resolve common issues you may encounter when using AgentKit. If you cannot find a solution here, feel free to contact us via GitHub Issues.

Installation Issues

1. agentkit command not found

• Symptom: When running the agentkit command in the terminal, the system reports command not found.
• Cause: This is usually because the executable path installed by pip has not been added to the system PATH environment variable.
• Solution:
  • Confirm install location: Run pip show agentkit-sdk-python or uv pip show agentkit-sdk-python and find the install path indicated by the Location field.
  • Locate the executable: Under the install path’s bin directory (for example .../site-packages/bin), you should be able to find the agentkit executable.
  • Add to PATH: Add the absolute path of this bin directory to your ~/.bashrc, ~/.zshrc, or other shell configuration files.

    export PATH="/path/to/your/python/bin:$PATH"

  • Reload configuration: Run source ~/.bashrc or restart the terminal to apply the changes.

2. Dependency conflicts

• Symptom: When installing agentkit-sdk-python, pip reports dependency version conflicts.
• Cause: Your Python environment may already contain library versions that are incompatible with AgentKit.
• Solution:
  • Use a virtual environment (recommended): We strongly recommend using uv or venv to create a clean virtual environment in your project to avoid conflicts with system-level Python packages.

    uv venv
    source .venv/bin/activate
    uv pip install agentkit-sdk-python

  • Clean and reinstall: If you must use the existing environment, uninstall and reinstall:

    pip uninstall agentkit-sdk-python
    pip install agentkit-sdk-python

Configuration Issues

1. Environment variables not taking effect

• Symptom: Prompts indicate it cannot connect to AgentKit Platform or authentication fails.
• Cause: Required environment variables may not have been passed in, or incorrect environment variable names were used.
• Solution:
  • Confirm required environment variables are set

  echo $VOLCENGINE_ACCESS_KEY
  echo $VOLCENGINE_SECRET_KEY

  • Ensure there are no extra spaces or quotes
  • Re-export the environment variables in the current shell session

2. Configuration file format error

• Symptom: When running agentkit launch, it reports configuration file parsing failure.
• Cause: File format issues
• Solution:
  • Check whether agentkit.yaml is formatted correctly (pay attention to indentation)
  • Re-run agentkit config to generate configuration

Deployment Issues

1. CR creation failed

• Symptom:

CreateRegistry: QuotaExceeded.Registry The quota of Registry is exceeded.

• Cause: Insufficient account quota
• Solution:
  • Number of CR instances exceeds the quota limit
  • In agentkit config, configure it to use an existing CR instance name
  • Or contact the administrator to increase quota

2. Image build failed

• Symptom: Pipeline build fails and reports dependency installation errors.
• Cause: Dependency installation failure
• Solution:
  • Check whether dependencies in requirements.txt are correct
  • Confirm dependency versions are compatible with Python 3.12
  • Check Pipeline logs for detailed error information (logs will be automatically downloaded to your local root directory; pay attention to prompts in the interactive UI and find a file named like pipeline_failed_****ff20ce223.log in the root directory)

3. Runtime deployment timeout

• Symptom: Runtime stays in Releasing state for a long time.
• Cause: The first deployment takes longer, or there may be insufficient resources.
• Solution:
  • The first deployment usually takes 2–3 minutes; please be patient
  • Use agentkit status to check status
  • If it is still not ready after 5 minutes, resources may be insufficient; try agentkit destroy and then redeploy

4. Runtime status abnormal

• Symptom: Runtime status is Failed or Error.
• Cause: Internal Runtime exception
• Solution:
  • Check whether environment variable configuration is correct (especially the model API Key)
  • Check logs in the AgentKit Platform console
  • Confirm the application code has no startup errors
  • Try cleaning up with agentkit destroy and redeploying

Invocation Issues

1. invoke failed

• Symptom: When running agentkit invoke, it reports connection failure or timeout.
• Cause: Network issues or incorrect Endpoint configuration
• Solution:
  • Use agentkit status to confirm Runtime status is Ready
  • Check network connectivity
  • Confirm the Endpoint address is correct
  • Check firewall or proxy settings

2. Model invocation failed

• Symptom: The Agent returns an error indicating model access failure.
• Cause: Incorrect model API Key configuration or exhausted model quota
• Solution:
  • Confirm the Ark model API Key configuration is correct
  • Check whether the endpoint ID is valid
  • Confirm whether model quota has been exhausted
  • Log in to the Ark platform to check API Key permissions

Permission Issues

1. AK/SK authentication failed

• Symptom: Reports InvalidAccessKeyId or SignatureDoesNotMatch.
• Cause: Incorrect AK/SK configuration or insufficient permissions
• Solution:
  • Confirm AK/SK is correct and valid
  • Check whether you have access permissions for the AgentKit service
  • Confirm AK/SK has not been disabled or expired
  • Contact the administrator to assign the required permissions

2. Resource access denied

• Symptom: Reports AccessDenied or insufficient permissions.
• Cause: The account does not have enough permissions to perform the operation
• Solution:
  • Confirm the account has the required permissions for the relevant resources
  • Check IAM role configuration
  • Contact the administrator to grant necessary permissions

Getting Help

If the above solutions cannot resolve your issue, please:

1. Check logs:

   • Local logs: Check command line output
   • Platform logs: Visit the AgentKit console to view detailed logs

2. Contact support:

   • Provide detailed error information and logs
   • Describe reproduction steps
   • Attach relevant configuration files (be sure to redact sensitive data)
   • Contact Volcengine technical support

3. Read the docs:

   • Volcengine Official Documentation
   • Official website FAQ