4.2.3. Run Management

Runs execute assistant logic on threads. Monitor run status and handle required actions for tool outputs.

🔧 Implementation Reference: Azure OpenAI Assistants

Agents can use built-in tools to perform actions. The following tools are available without custom development.

Built-in Tools:

Testable Pattern:

# Create assistant with tools
assistant = client.beta.assistants.create(
    name="Helper",
    instructions="You are a helpful assistant.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4o"
)

# Create thread and run
thread = client.beta.threads.create()
message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Solve x^2 + 5x + 6 = 0")
run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=assistant.id)

Assistants API Workflow:

Handling Tool Calls:

When run.status == "requires_action", execute tools and submit results:

tool_outputs = [{"tool_call_id": call.id, "output": result} for call in run.required_action.submit_tool_outputs.tool_calls]
client.beta.threads.runs.submit_tool_outputs(thread_id=thread.id, run_id=run.id, tool_outputs=tool_outputs)

Error Handling Pattern:

from openai import AzureOpenAI, APIError
import time

def run_agent_with_error_handling(thread_id: str, assistant_id: str, max_retries: int = 3):
    """Execute agent run with comprehensive error handling."""
    run = client.beta.threads.runs.create(thread_id=thread_id, assistant_id=assistant_id)
    
    while True:
        try:
            run = client.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
        except APIError as e:
            logging.error(f"Failed to retrieve run status: {e}")
            raise
        
        if run.status == "completed":
            return client.beta.threads.messages.list(thread_id=thread_id)
        
        elif run.status == "requires_action":
            tool_outputs = []
            for call in run.required_action.submit_tool_outputs.tool_calls:
                try:
                    result = execute_tool(call.function.name, call.function.arguments)
                    tool_outputs.append({"tool_call_id": call.id, "output": result})
                except Exception as e:
                    # Return error message as tool output - let agent handle gracefully
                    tool_outputs.append({
                        "tool_call_id": call.id, 
                        "output": f"Error executing tool: {str(e)}"
                    })
            
            client.beta.threads.runs.submit_tool_outputs(
                thread_id=thread_id, run_id=run.id, tool_outputs=tool_outputs
            )
        
        elif run.status == "failed":
            logging.error(f"Run failed: {run.last_error}")
            raise RuntimeError(f"Agent run failed: {run.last_error.message}")
        
        elif run.status == "expired":
            logging.warning("Run expired - timeout exceeded")
            raise TimeoutError("Agent run expired")
        
        else:
            time.sleep(1)  # in_progress, queued, cancelling

⚠️ Exam Trap: When run.status == "failed", check run.last_error for the failure reason—this is testable.

CLI Equivalent (REST):

# Create a run
curl -X POST "https://{resource}.openai.azure.com/openai/threads/{thread_id}/runs?api-version=2024-08-01-preview" \
  -H "Content-Type: application/json" \
  -H "api-key: {key}" \
  -d '{"assistant_id": "{assistant_id}"}'

# Check run status
curl "https://{resource}.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-08-01-preview" \
  -H "api-key: {key}"

# Submit tool outputs
curl -X POST "https://{resource}.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2024-08-01-preview" \
  -H "Content-Type: application/json" \
  -H "api-key: {key}" \
  -d '{"tool_outputs": [{"tool_call_id": "{call_id}", "output": "result"}]}'

The following diagram shows the agent execution loop. Understanding this flow is critical for handling tool calls correctly.

Azure OpenAI Assistants