Real Tool Calling & Agent Loops for
Apple Foundation Models

import OpenAppleModelsGame

let world = WorldState(["player": ["name": "Aria", "gold": 60], "time_of_day": "evening"])

let smith = try NPC(
    persona: Persona(
        name: "Gorm", role: "the village blacksmith",
        personality: "Gruff and proud, but fair", speakingStyle: "Short, blunt sentences. Calls people 'lad'."),
    tools: [inventory],                                     // any AgentTool, local or external
    world: world,                                           // adds a read_world_state tool
    options: NPCOptions(
        groundingTool: "check_inventory",                   // look up stock on every turn
        worldContextPaths: ["player.name", "player.gold", "time_of_day"]))

let turn = try await smith.talk("Evening! Got any iron swords? How much?")
print(turn.emotion, turn.line, turn.playerOptions)
// Live run of a similar setup (docs/GAMES.md): called check_inventory, then
// "Aria, I've got three iron swords for 45 gold. Take one if you're keen." in 4.4-5.2 s.

# Start the server first: oam serve   (127.0.0.1:1976)
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:1976/v1", api_key="unused")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather for a city.",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    },
}]

response = client.chat.completions.create(
    model="system",
    messages=[{"role": "user", "content": "What is the weather in Paris?"}],
    tools=tools,
    tool_choice="required",
)

for tool_call in response.choices[0].message.tool_calls:
    print(tool_call.function.name, tool_call.function.arguments)

# Force a tool call with an inline tool. A tool without a command is external:
# oam exits with code 10 and prints the pending calls and a transcript path.
oam respond 'How many potions do I have?' --tool-choice required \
  --tool-json '{"name":"get_potions","description":"Count potions in the inventory","parameters":{"type":"object","properties":{}}}'

# OpenAI-compatible local server (127.0.0.1:1976)
oam serve

# Talk to Mira, an NPC innkeeper with a menu tool and a till
oam demo tavern

# JSON-RPC bridge over stdin/stdout for game engines
oam stdio

// A client tool call over oam stdio, after initialize (id 1); some session/event notifications left out
→ {"jsonrpc":"2.0","id":2,"method":"session/create","params":{"session":"guard","instructions":"You are a castle guard. Use tools to act.","tools":[{"name":"open_gate","description":"Open a named gate.","parameters":{"type":"object","properties":{"gate":{"type":"string"}}}}],"options":{"toolChoice":"required"}}}
→ {"jsonrpc":"2.0","id":3,"method":"session/respond","params":{"session":"guard","prompt":"Please open the north gate.","stream":true}}
← {"jsonrpc":"2.0","id":"t-1","method":"tool/call","params":{"session":"guard","requestId":3,"call":{"id":"call_NYH7…","name":"open_gate","arguments":{"gate":"north"}}}}
→ {"jsonrpc":"2.0","id":"t-1","result":{"output":{"opened":false,"reason":"the portcullis chain is jammed"}}}
← {"jsonrpc":"2.0","id":3,"result":{"session":"guard","text":"The north gate remains shut because the portcullis chain is jammed.",…}}