azure-ai-agent-sdk-learning

Azure AI Agent SDK — Troubleshooting Guide

Authentication Issues

“DefaultAzureCredential failed to retrieve a token”

Cause: No valid credential found in the credential chain.

Fix:

  1. Ensure you are logged in via Azure CLI: 
    az login
az account set --subscription <your-subscription-id>
  2. Verify your account has access: 
    az account show
  3. If using a service principal, ensure environment variables are set:
    • AZURE_CLIENT_ID
    • AZURE_TENANT_ID
    • AZURE_CLIENT_SECRET

“Forbidden (403)” — Access Denied

Cause: The authenticated identity lacks the required RBAC role on the AI Foundry project.

Fix:

  1. Assign the Azure AI User role: 
    az role assignment create \
  --assignee <your-principal-id> \
  --role "Azure AI User" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.MachineLearningServices/workspaces/<project>
  2. Wait 1-2 minutes for role assignment propagation.
  3. Retry the operation.

“Unauthorized (401)” — Token Expired

Cause: The authentication token has expired.

Fix:

  1. Re-authenticate: 
    az login
  2. If using DefaultAzureCredential, it automatically refreshes tokens — ensure you are creating the credential once and reusing it.

Agent Issues

“Model not found” or “Deployment not found”

Cause: The model parameter does not match a deployed model name in your Foundry project.

Fix:

  1. Check your model deployment name in AI Foundry → your project → Deployments.
  2. Use the deployment name, not the model name. For example, if you deployed GPT-4o with the name gpt-4o-deploy, use that: 
    agent = agents_client.create_agent(
    model="gpt-4o-deploy",  # deployment name, not "gpt-4o"
    ...
)
  3. Verify via CLI: 
    az ml online-deployment list --endpoint-name <endpoint> --resource-group <rg> --workspace-name <project>

“Agent creation failed”

Cause: Quota limits, model not deployed, or project misconfiguration.

Fix:

  1. Check quota: Ensure your subscription has sufficient quota for the model.
  2. Check model deployment status: The deployment must be in a Succeeded state.
  3. Check the connection string format: <endpoint>;<subscription-id>;<resource-group>;<project-name>.
  4. Verify the project exists and is accessible.

“Run stuck in queued” or timeout

Cause: Service under load or infrastructure issue.

Fix:

  1. Implement a timeout when polling: 
    import time
   
run = agents_client.create_run(thread_id=thread.id, agent_id=agent.id)
timeout = 120  # seconds
start = time.time()
   
while run.status in ("queued", "in_progress"):
    if time.time() - start > timeout:
        agents_client.cancel_run(thread_id=thread.id, run_id=run.id)
        raise TimeoutError("Run timed out")
    time.sleep(2)
    run = agents_client.get_run(thread_id=thread.id, run_id=run.id)
  2. Use create_and_process_run() which handles polling automatically.
  3. Check Azure Status for service incidents.

Tool Issues

Code Interpreter timeout

Cause: Code execution exceeded the time limit (typically 60 seconds).

Fix:

File Search returns no results

Cause: File not processed, vector store not ready, or query not matching content.

Fix:

  1. Verify the file was uploaded successfully: 
    file = agents_client.upload_file_and_poll(
    file_path="data.pdf",
    purpose=FilePurpose.AGENTS
)
print(f"File ID: {file.id}, Status: {file.status}")
  2. Ensure the vector store finished processing: 
    vector_store = agents_client.create_vector_store_and_poll(
    file_ids=[file.id],
    name="my-store"
)
print(f"Vector store status: {vector_store.status}")
# Should be "completed"
  3. Try rephrasing the query — the search uses semantic matching, not exact keyword matching.
  4. Check that the file format is supported (PDF, DOCX, TXT, MD, etc.).

Function calling not invoked

Cause: Tool schema mismatch, or the agent determined the function was not needed.

Fix:

  1. Verify the function definition schema is valid JSON: 
    function = FunctionTool(
    name="get_weather",
    description="Get current weather for a city",  # Be descriptive!
    parameters={
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "City name, e.g. Seattle"
            }
        },
        "required": ["city"]
    }
)
  2. Ensure the function description clearly explains when to use it.
  3. Include the tool in the agent’s tool list during creation.
  4. Make the user’s prompt explicitly relevant to the function’s purpose.

SDK Issues

Package version conflicts

Cause: Incompatible versions of Azure SDK packages.

Fix (Python):

# Pin specific versions in requirements.txt
azure-ai-projects==1.0.0b7
azure-identity==1.21.0

# Reinstall cleanly
pip install -r requirements.txt --force-reinstall

Fix (.NET):

<!-- Pin versions in .csproj -->
<PackageReference Include="Azure.AI.Projects" Version="1.0.0-beta.7" />
<PackageReference Include="Azure.Identity" Version="1.13.2" />

Async/sync confusion (Python)

Cause: Mixing sync and async APIs or forgetting await.

Fix:

Streaming issues

Cause: Improper context manager usage or not handling all event types.

Fix (Python):

# Use as a context manager
with agents_client.create_stream(
    thread_id=thread.id, agent_id=agent.id
) as stream:
    for event_type, event_data, *_ in stream:
        if isinstance(event_data, MessageDeltaChunk):
            print(event_data.text, end="", flush=True)

Fix (.NET):

await foreach (var update in agentsClient.CreateRunStreamingAsync(
    threadId: thread.Id, agentId: agent.Id))
{
    if (update is MessageContentUpdate contentUpdate)
    {
        Console.Write(contentUpdate.Text);
    }
}

Common Error Codes

Code Meaning Typical Fix
400 Bad Request Check request format, invalid parameters, malformed JSON
401 Unauthorized Re-authenticate with az login or refresh tokens
403 Forbidden Assign Azure AI User role to your identity
404 Not Found Verify endpoint URL, agent/thread/run IDs exist
409 Conflict Resource already exists or concurrent modification
422 Unprocessable Entity Valid JSON but semantically incorrect (e.g., invalid model name)
429 Rate Limited Implement retry with exponential backoff
500 Internal Server Error Retry the request; check Azure Status
503 Service Unavailable Temporary overload; retry with backoff

Retry Strategy

For transient errors (429, 500, 503), implement exponential backoff:

import time

def retry_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + 1  # 1s, 3s, 5s
            print(f"Retry {attempt + 1}/{max_retries} in {wait}s: {e}")
            time.sleep(wait)

Useful Debugging Commands

Azure CLI

# Check Azure CLI login status
az account show

# List available subscriptions
az account list --output table

# Check AI Foundry project details
az ml workspace show --name <project-name> --resource-group <rg>

# List model deployments
az ml online-deployment list --endpoint-name <endpoint> --resource-group <rg>

# Check role assignments
az role assignment list --assignee <principal-id> --output table

Python — Enable Verbose Logging

import logging
import sys

# Enable detailed SDK logging
logging.basicConfig(
    level=logging.DEBUG,
    stream=sys.stdout,
    format="%(asctime)s %(name)s %(levelname)s: %(message)s"
)

# Or enable only HTTP request logging
logging.getLogger("azure.core.pipeline.policies.http_logging_policy").setLevel(logging.DEBUG)

.NET — Enable Verbose Logging

using Azure.Core.Diagnostics;

// Enable console logging
using var listener = AzureEventSourceListener.CreateConsoleLogger(
    level: System.Diagnostics.Tracing.EventLevel.Verbose
);

Verify Environment Setup

# Python: Check installed package versions
pip show azure-ai-projects azure-identity

# .NET: Check package versions
dotnet list package

# Verify environment variables
echo $PROJECT_CONNECTION_STRING   # Linux/Mac
echo %PROJECT_CONNECTION_STRING%  # Windows

Getting Help

Next Steps