xybruceliu/thoughtful-agents

에이전트의 사고(thought)와 대화를 모델링하기 위한 프레임워크로, 여러 AI 에이전트와 인간 사이의 더욱 자연스럽고 인간과 유사한 상호작용을 가능하게 합니다.

• 개요 (Overview)
• 연구 배경 (Research Background)
• 설치 (Installation)
• 프로젝트 구조 (Project Structure)
• 배포 (Distribution)
• 핵심 구성 요소 (Key Components)
• 사용 예시 (Usage Examples)
• 라이선스 (License)
• 인용 (Citation)
• 연락처 (Contact)

Thoughtful Agents는 대화 중 AI 에이전트의 내부 사고 과정 (internal thought processes)을 모델링하는 구조화된 접근 방식을 제공합니다. 단순히 대화의 차례를 예측하는 것이 아니라, 이 프레임워크는 자체적인 내부 "사고 (thoughts)"에 의해 주도되는 능동적인 AI를 가능하게 합니다.

이 프레임워크는 CHI 2025에서 발표된 "Proactive Conversational Agents with Inner Thoughts" 논문을 기반으로 합니다.

인지 아키텍처 (cognitive architectures) 및 LLM 프롬프팅 기술 (prompting techniques)에서 영감을 받은 이 프레임워크는 다섯 가지 단계로 구성됩니다:

Trigger (트리거) - 사고 과정의 시작
Retrieval (검색) - 관련 기억 및 문맥 (context)에 접근
Thought Formation (사고 형성) - 잠재적 사고 생성
Evaluation (평가) - 사고를 표현하려는 내재적 동기 평가
Participation (참여) - 대화에 참여할 시점과 방식 결정

Python 구현체에는 다음이 포함됩니다:

• 사고 생성, 평가, 선택 및 표현을 위한 사고 엔진 (Thinking engine)
• 시스템 1 (System 1, 빠르고 자동적인 사고) 및 시스템 2 (System 2, 느리고 신중한 사고)
• 정신적 객체 관리 (Mental object management: 사고, 기억)
• 돌출도 (Saliency) 기반의 기억 및 사고 검색
• 대화 및 이벤트 추적
• 차례 주고받기 (Turn-taking) 예측 및 다음에 누가 언제 말해야 하는지를 결정하는 엔진
• 에이전트를 위한 능동성 (Proactivity) 설정

현재 대부분의 LLM 기반 시스템은 AI를 명시적인 인간의 프롬프트에만 반응하는 수동적인 응답자로 취급합니다. Inner Thoughts 프레임워크는 인간의 인지에서 영감을 얻은 대안적인 접근 방식을 취합니다. 인간은 타인의 말을 처리하고, 자신의 경험을 되돌아보며, 참여를 결정하기 전에 내부적인 사고의 흐름을 발전시킵니다.

이러한 접근 방식은 인간의 의사소통에서 나타나는 은밀한 반응 (covert responses) (내부적인 생각과 감정)과 명시적 반응 (overt responses) (언어적 발화) 사이의 구분을 모델링합니다. AI 참여자는 특정 순간에 특정 생각을 표현하고자 하는 내재적 동기 (intrinsic motivation)를 평가하여 참여 여부를 결정합니다.

pip install thoughtful-agents

• 저장소 복제 (Clone):

git clone https://github.com/xybruceliu/thoughtful-agents.git
cd thoughtful-agents

• 패키지 및 의존성 설치:

pip install -e .

설치 후, 필요한 spaCy 모델을 다운로드하세요:

python -m spacy download en_core_web_sm

또는 제공된 스크립트를 사용하세요:

python scripts/download_spacy_model.py

export OPENAI_API_KEY=your_api_key_here

# 완료 모델 (completion model) 설정 (기본값: gpt-4o)
export COMPLETION_MODEL=gpt-4-turbo
# 임베딩 모델 (embedding model) 설정 (기본값: text-embedding-3-small)
...

프로젝트 구조는 다음과 같습니다:

thoughtful_agents/models/

: 핵심 모델 클래스들
participant.py

: Participant, Human, 그리고 Agent 클래스들
thought.py

: Thought 관련 클래스들
memory.py

: Memory 관련 클래스들
conversation.py

: Conversation 및 Event 클래스들
mental_object.py

: Mental objects를 위한 베이스 클래스
enums.py

: 열거형 (Enumeration) 타입들

thoughtful_agents/utils/

: 유틸리티 함수들
llm_api.py

: OpenAI API 상호작용
saliency.py

: 현저성 (Saliency) 계산
thinking_engine.py

: 사고 생성, 평가 및 명료화 (articulation)를 위한 함수들
turn_taking_engine.py

: 발화 순서 교대 (Turn-taking) 예측
text_splitter.py

: spaCy를 사용한 텍스트 분할

examples/

: 예제 구현
hello_world.py

: 두 에이전트 간의 대화를 보여주는 간단한 예제
ai_thought_process.py

: AI의 사고 과정을 보여주는 상세한 예제
lecture_practice.py

: 강의 연습 중 AI가 선제적인 피드백을 제공하는 예제
multiparty_conversation.py

: 세 명의 AI 에이전트 간의 다자간 대화 예제

이 프레임워크는 PyPI 패키지로 사용할 수 있습니다:

pip install thoughtful-agents

PyPI 패키지: https://pypi.org/project/thoughtful-agents/

이 프레임워크는 다양한 유형의 대화 참여자 (Participant)를 모델링합니다:

Participant
: 모든 대화 참여자를 위한 기본 클래스 (Base class)

Human
: 대화 내의 인간 참여자를 나타냄

Agent
: 생각을 생성하고, 이를 평가하며, 언제 참여할지 결정할 수 있는 AI 에이전트 (AI agents)

Thought (생각)와 Memory (기억)는 모두 MentalObject (정신적 객체)의 하위 클래스 (Subclasses)입니다.

프레임워크는 다음을 구분합니다:

Thought (생각): 현재의 사고를 나타내는 일시적인 정신적 객체
Memory (기억): 향후 검색을 위해 저장되는 장기적인 정신적 객체

이들은 각각 ThoughtReservoir와 MemoryStore 클래스를 통해 관리됩니다.

Conversation (대화) 클래스는 전체 대화 상태를 관리하며, Event (이벤트) 객체는 대화 내의 개별 발화 (Utterances) 또는 기타 모든 행동을 나타냅니다.

MentalObject 클래스는 시스템 내의 모든 정신적 엔티티 (Mental entities)를 위한 기반 역할을 합니다. 여기에는 주어진 문맥에서 해당 객체가 얼마나 중요하고 관련이 있는지를 결정하는 내용 (Content), 임베딩 (Embedding), 현저성 (Saliency), 가중치 (Weight)와 같은 속성이 포함됩니다.

thinking_engine.py의 주요 함수는 다음과 같습니다:

generate_system1_thought(): 즉각적인 문맥을 바탕으로 빠르고 직관적인 생각을 생성함
generate_system2_thoughts(): 더 깊은 추론을 동반한 신중하고 성찰적인 생각을 생성함
evaluate_thought(): 생각을 평가하고 내재적 동기 점수 (Intrinsic motivation scores, 1-5)를 할당함
articulate_thought(): 내부의 생각을 자연어 발화로 변환함

차례 주고받기 (Turn-taking) 엔진은 Sacks 등의 대화 분석 원칙 (Simplest Systematics)을 구현합니다:

차례 할당 (Turn-allocation): 화자가 다음 화자를 직접 지목할 때 (예: "Alice, 당신은 어떻게 생각하나요?")
자기 선택 (Self-selection): 특정 화자가 지목되지 않았을 때, 어떤 참여자든 발언권을 가질 수 있음

프레임워크는 두 가지 핵심 함수를 통해 이를 구현합니다:

predict_turn_taking_type

: 대화를 분석하여 특정 화자가 선택되었는지 또는 발언권이 누구에게나 열려 있는지(open floor)를 결정합니다.

decide_next_speaker_and_utterance

: 발언권 할당 유형(turn allocation type), 내재적 동기 점수(intrinsic motivation scores), 그리고 주도성 설정(proactivity settings)을 기반으로 다음 화자를 선택합니다.

Inner Thoughts는 세 가지 주도성 계층(proactivity layers)을 통해 AI의 대화 참여에 대한 세밀한 제어를 제공합니다:

명시적 주도성 (Overt Proactivity): system1_prob 파라미터(0-1)를 통해 대화 참여 성향을 제어합니다.

암묵적 주도성 (Covert Proactivity): im_threshold 파라미터(1-5)를 사용하여 표현을 위한 동기 임계값(motivation threshold)을 설정합니다.

어조 주도성 (Tonal Proactivity): proactive_tone 파라미터(true/false)로 언어의 확신성(assertiveness)을 조정합니다.

또한, 이 프레임워크는 interrupt_threshold 파라미터(1-5)를 통한 **끼어들기 (interruption)**를 지원하며, 이를 통해 AI가 높은 동기를 가질 때 발언권 할당을 무시하고 개입할 수 있도록 합니다.

AI가 언제, 어떻게 참여할지를 결정하는 방식은 다음과 같습니다:

• 열린 발언권 (open turns)의 경우: 동기가 임계값을 초과하면 AI가 발언합니다.
• 할당된 발언권 (allocated turns)의 경우: AI는 가장 높은 점수를 받은 생각(thought)을 사용합니다.
• 타인의 발언권 (others' turns)의 경우: AI는 충분한 동기가 있을 때만 끼어듭니다.

hello_world.py 예제는 두 AI 에이전트 간의 간단한 대화를 보여줍니다:

# 간단한 컨텍스트와 함께 대화 생성
conversation = Conversation(context="A friendly chat between Alice and Bob.")
# 특정 주도성 설정을 가진 에이전트 생성
...

에이전트의 최적의 동작을 위해, 이벤트 처리를 위한 다음 작업 순서를 따르십시오:

• participant.send_message()를 사용하여 이벤트를 생성합니다.
• predict_turn_taking_type(conversation)을 호출하여 발언권 할당 유형(특정 화자 이름 또는 "anyone")을 결정합니다.
• conversation.broadcast_event(event)를 호출하여 에이전트들이 이벤트를 처리하도록 합니다.
• decide_next_speaker_and_utterance(conversation)를 사용하여 실제 다음 화자를 가져옵니다.

이 순서를 통해 에이전트들이 broadcast_event 도중 이벤트를 처리할 때, 적절한 생각 선택(thought selection)에 필요한 발언권 할당 예측값(pred_next_turn)에 접근할 수 있도록 보장합니다.

참고: 이 프레임워크에는 broadcast_event 도중 필요할 경우 predict_turn_taking_type을 자동으로 호출하는 안전 장치(safety mechanism)가 포함되어 있지만, 명확성과 일관성을 위해 명시적으로 호출하는 것을 권장합니다.

ai_thought_process.py는 AI의 내부 사고 과정(internal thought process)을 더 자세히 보여줍니다:

# 인간과 AI 에이전트 생성
human = Human(name="Human")
ai_agent = Agent(name="AI Assistant", proactivity_config={
...

lecture_practice.py 예제는 AI 어시스턴트가 사용자의 요청 없이도 강의 연습(lecture practice) 중에 어떻게 선제적인 피드백(proactive feedback)을 제공할 수 있는지 보여줍니다:

# 강의 연습을 위한 컨텍스트가 포함된 대화 생성
conversation = Conversation(context="A user is practicing a lecture on artificial intelligence.")
# 인간 발표자와 AI 피드백 어시스턴트 생성
...

multiparty_conversation.py 예제는 세 명의 AI 에이전트가 주말 활동에 대해 나누는 일상적인 다자간 대화(multi-party conversation)를 보여줍니다. 각 에이전트는 서로 다른 "페르소나(persona)"와 선제성 설정(proactivity configuration)을 가지고 있습니다. 이들은 각 턴(turn)에서 말할지 여부를 결정하며, 자신의 내재적 동기 점수(intrinsic motivation scores)를 바탕으로 선제적으로 대화에 참여합니다.

# 간단한 컨텍스트를 가진 대화 생성
conversation = Conversation(context="A casual conversation between friends Alice, Bob, and Charlie about what they did last weekend.")
# 각각의 선제성 설정을 가진 세 명의 에이전트 생성
...

이 프로젝트는 Apache 2.0 라이선스(Apache 2.0 License) 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

연구에 이 프레임워크를 사용하신다면, 다음을 인용해 주세요:

@inproceedings{liu2025inner,
title={Proactive Conversational Agents with Inner Thoughts},
author={Liu, Xingyu Bruce and Fang, Shitao and Shi, Weiyan and Wu, Chien-Sheng and Igarashi, Takeo and Chen, Xiang Anthony},
...

질문이나 피드백이 있으시면 언제든지 Xingyu Bruce Liu에게 연락해 주세요!