🔌 Connecting LLMs to External Systems: The Mechanics of API Orchestration & Tool Calling
While large language models possess immense generative and reasoning capabilities, they are isolated text processors unable to query live databases, execute financial transactions, or interact with cloud APIs. Function Calling and API Orchestration bridge this gap by allowing LLMs to inspect user intent, select appropriate external tools from a registered catalog, extract correctly typed arguments into strict JSON schemas, and orchestrate multi-step API execution loops until the user's objective is fully satisfied.
import json
import boto3
from openai import OpenAI
client = OpenAI()
# Define tools available to the LLM
tools = [
{
"type": "function",
"function": {
"name": "provision_ec2_instance",
"description": "Provisions an AWS EC2 instance with specified instance type and AMI.",
"parameters": {
"type": "object",
"properties": {
"instance_type": {"type": "string", "enum": ["t3.micro", "t3.medium", "m5.large"]},
"ami_id": {"type": "string", "description": "AMI ID e.g. ami-0abcdef1234567890"},
"key_name": {"type": "string"}
},
"required": ["instance_type", "ami_id"]
}
}
}
]
def provision_ec2_instance(instance_type: str, ami_id: str, key_name: str = "default-key"):
ec2 = boto3.client('ec2', region_name='us-east-1')
response = ec2.run_instances(
ImageId=ami_id,
InstanceType=instance_type,
KeyName=key_name,
MinCount=1,
MaxCount=1
)
return json.dumps({"instance_id": response['Instances'][0]['InstanceId'], "status": "pending"})
# Orchestration dispatch loop
def run_assistant(user_prompt: str):
messages = [{"role": "user", "content": user_prompt}]
response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
response_message = response.choices.message
tool_calls = response_message.tool_calls
if tool_calls:
available_functions = {"provision_ec2_instance": provision_ec2_instance}
messages.append(response_message)
for tool_call in tool_calls:
function_name = tool_call.function.name
function_to_call = available_functions[function_name]
function_args = json.loads(tool_call.function.arguments)
function_response = function_to_call(**function_args)
messages.append({
"tool_call_id": tool_call.id,
"role": "tool",
"name": function_name,
"content": function_response,
})
second_response = client.chat.completions.create(model="gpt-4o", messages=messages)
return second_response.choices.message.content
return response_message.content
# User Prompt: "Rebalance my portfolio by selling all tech stock holdings and buying S&P 500 index funds."
# Step 1: LLM invokes `get_portfolio_holdings(account_id="ACC-992")`
# Tool Output: {"holdings": [{"ticker": "AAPL", "shares": 50}, {"ticker": "NVDA", "shares": 20}]}
# Step 2: LLM processes holdings and invokes `execute_trade(ticker="AAPL", action="SELL", qty=50)`
# Step 3: LLM invokes `execute_trade(ticker="NVDA", action="SELL", qty=20)`
# Step 4: LLM invokes `execute_trade(ticker="SPY", action="BUY", amount_usd=total_liquidated_cash)`
# User Prompt: "Check stock availability for SKU-99201 across US-East, US-West, EU-Central, and APAC warehouses."
# LLM emits 4 concurrent tool calls in a single response turn:
# 1. check_warehouse(sku="SKU-99201", region="US-East")
# 2. check_warehouse(sku="SKU-99201", region="US-West")
# 3. check_warehouse(sku="SKU-99201", region="EU-Central")
# 4. check_warehouse(sku="SKU-99201", region="APAC")
# -> Results are gathered asynchronously and fed back to the LLM for consolidated reporting.
tools_support = [
{
"type": "function",
"function": {
"name": "lookup_customer_by_email",
"parameters": {"type": "object", "properties": {"email": {"type": "string"}}}
}
},
{
"type": "function",
"function": {
"name": "track_fedex_shipment",
"parameters": {"type": "object", "properties": {"tracking_number": {"type": "string"}}}
}
}
]
# User Prompt: "Investigate suspicious login spikes from IP 198.51.100.42 and block if malicious."
# Step 1: query_siem_logs(ip="198.51.100.42", timespan="24h")
# Step 2: lookup_geoip(ip="198.51.100.42")
# Step 3: block_ip_firewall(ip="198.51.100.42", reason="Brute-force credential stuffing")
tools_fhir = [
{
"type": "function",
"function": {
"name": "fetch_patient_lab_results",
"description": "Retrieves HL7 FHIR Observation lab records for patient ID.",
"parameters": {
"type": "object",
"properties": {
"patient_id": {"type": "string"},
"lab_panel": {"type": "string", "enum": ["CBC", "Metabolic", "Lipid"]}
},
"required": ["patient_id"]
}
}
}
]
# User Prompt: "Deploy release v2.4.0 to production environment."
# LLM invokes: trigger_github_workflow(repo="core-api", workflow_file="deploy.yml", ref="v2.4.0", env="production")
def execute_readonly_sql(query: str):
if not query.strip().upper().startswith("SELECT"):
raise ValueError("Security Violation: Only SELECT queries are permitted.")
# Execute query against Snowflake / BigQuery reporting replica
return snowflake_client.execute(query)
# User Prompt: "Book roundtrip flights from NYC to London for next weekend and reserve a 4-star hotel."
# Step 1: search_flights(origin="NYC", destination="LON", dates="...")
# Step 2: search_hotels(city="London", rating=4, checkin="...", checkout="...")
# Step 3: process_payment(amount=1450.00, currency="USD")
# Step 4: issue_booking_confirmation_email()
try:
api_result = external_api_call(**args)
except APIConnectionError as e:
# Feed error message back into LLM context as tool response so model can retry or explain
api_result = json.dumps({"error": "API Gateway timeout. Please retry with smaller batch size."})