Project: Reasoning agent - Sixteen-Threads RPG System

Track

Reasoning Agents (Azure AI Foundry)

Project Name

Sixteen-Threads

GitHub Username

@ria-zee

Repository URL

https://github.com/Ria-Zee/Sixteen-Threads

Project Description

Sixteen Threads is a multi-agent RPG built on Microsoft Azure AI Foundry. Six AI agents, each representing a different African culture, reason independently about whether to go to war after a sacred covenant is broken. The player directs the story. Agents conflict with each other. The Game Master agent resolves conflicts using a visible reasoning chain. The world is grounded in West African mythology: Yoruba, Akan, Kikuyu, Zulu, and Mandinka traditions.

Demo Video or Screenshots

https://youtu.be/gHLsou7U0ds
https://youtu.be/dImirkV2Syg

Primary Programming Language

Python

Key Technologies Used

Aso-Ijo: The covenant cloth separating the mortal world (Aye) from the spirit realm (Orun). Its tearing drives the plot.
Foundry IQ: Microsoft Foundry's knowledge grounding layer. Nine synthetic lore documents are indexed and queried by the GM agent before every narration decision.
Disagreement Resolution: The core mechanic. When agents conflict, confidence scores are calculated, Foundry IQ evidence adjusts them, and the GM produces a weighted decision with full reasoning visible to the player.
Trust Economy: Each agent has a trust score from 0 to 100. Trust rises when agents share costly information. It drops when they conceal it. Low trust changes agent behavior.
World Flags: Boolean state variables that propagate consequences across scenes. One flag set in Act 1 can unlock a side quest and change Act 3 options.
War Probability: A score from 0 to 100 percent that recalculates after every player decision based on active flags, agent trust levels, and scene outcomes.
Ìmọlẹ̀ Tuntun: The antagonist faction. Yoruba for New Light. Their goal is merging the spirit and mortal worlds permanently.
kũhĩa njĩa: Kikuyu term for spirit displacement. The condition the shrine keeper is in when the party finds her.

Submission Type

Individual

Team Members

No response

Submission Requirements

• My project meets the track-specific challenge requirements
• My repository includes a comprehensive README.md with setup instructions
• My code does not contain hardcoded API keys or secrets
• I have included demo materials (video or screenshots)
• My project is my own work with proper attribution for any third-party code
• I agree to the Code of Conduct
• I have read and agree to the Disclaimer
• My submission does NOT contain any confidential, proprietary, or sensitive information
• I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

git clone https://github.com/Ria-Zee/sixteen-threads
cd sixteen-threads
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Add your Azure AI Foundry credentials to .env.

python3 agents/agent_factory.py
python3 main.py

Open web/index.html in Chrome for the cinematic intro. The web UI auto-plays through 10 scenes with voice narration and audio. No interaction needed. The terminal runs the live multi-agent game session.

Technical Highlights

Six agents created in Azure AI Foundry, each with a distinct system prompt encoding cultural identity, hidden knowledge, emotional memory, and war stance.
Disagreement detection triggers on player input keywords. Three pre-built scenarios cover the three major story conflicts: the shadowless figure, the Nri nail, and the full war debate.
Confidence scoring combines each agent's stated confidence with their credibility score (earned through being correct). The product determines resolution weight.
Foundry IQ knowledge base uses text-embedding-3-large with Medium retrieval reasoning effort. Nine lore documents totaling 128KB are indexed and cited in responses.
World state JSON tracks 30+ flags, 6 agent trust scores, war probability, and a full reasoning trace log. State persists across turns and every agent reads it before responding.
Rich terminal UI renders reasoning traces, agent dialogue cards, war probability bars, and active flags in real time during gameplay.

Challenges & Learnings

The azure-ai-agents SDK version 1.1.0 does not expose thread or message listing methods. Agent creation works. Runtime invocation does not. The fix was using the Azure OpenAI compatible endpoint exposed by Foundry, which provides full Assistants API support. Agents defined in Foundry are accessible through both endpoints using the same agent IDs.
DefaultAzureCredential fails on macOS 11.7 without Azure CLI installed. InteractiveBrowserCredential works as a direct replacement for local development.
Foundry IQ's File upload feature manages its own internal index with its own auth context. Direct Azure Search API calls require a separate admin key and the correct index name returned by Foundry's internal provisioning. For the demo, lore retrieval reads the same source files directly, producing identical results with cited source file names.
Agent response timeouts vary by prompt length. System prompts over 2,000 words require a 120 second poll timeout and 3,000ms poll interval to reliably complete.
The most important learning: multi-agent reasoning quality depends entirely on how well you define the conflict between agents at system prompt level. Generic agent prompts produce generic disagreements. Specific cultural voices, specific hidden knowledge, and specific emotional memories produce disagreements that feel real.

Contact Information

amalbergaobasi@gmail.com

Country/Region

Nigeria

This is a project submission rather than a scoped contribution request. Review the linked Sixteen-Threads repository, starting with README.md and the setup commands, then inspect agents/agent_factory.py, main.py, and web/index.html. Done would mean validating the submitted project and its documented demo, but no specific change or acceptance test is stated here.