Chat API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• server/routes/chat.py
• server/models/chat.py
• web/app/api/chat/route.ts
• web/app/api/chat/history/route.ts
• server/agents/interaction_agent/runtime.py
• server/services/conversation/log.py

The Chat API Endpoints provide the primary interface for communication between the user interface and the multi-agent orchestration backend. This system handles real-time message exchange, maintains persistent conversation history, and coordinates between the interaction agent and various execution agents to fulfill user requests.

The architecture follows a proxy pattern where the Next.js frontend sends requests to internal API routes, which then forward these requests to a FastAPI backend. This backend manages the "Interaction Agent" loop, which is responsible for reasoning, tool use, and generating human-like responses while maintaining a consistent personality.
Sources: README.md:9-11, web/app/api/chat/route.ts:28-40, server/agents/interaction_agent/runtime.py:48-75

API Architecture and Data Flow

The chat system operates through three primary layers: the Frontend UI, the Next.js API Proxy, and the FastAPI Backend.

Message Processing Flow

When a user sends a message, it is optimistically added to the UI before being sent through the proxy to the backend. The backend processes the message using an InteractionAgentRuntime, which may trigger multiple tool calls or delegate tasks to execution agents before returning a final response.

Endpoint Reference

1. Send Message

Route: POST /api/v1/chat/send (Backend) / POST /api/chat (Frontend Proxy)

This endpoint submits a user message to the interaction agent. The backend records the message in a persistent conversation log and initiates the agent logic loop.

Parameter	Type	Description
messages	List[ChatMessage]	A list of message objects containing role and content.
system	string	(Optional) Override for the system prompt.
stream	boolean	Whether to stream the response (defaults to true).

Data Models:

• ChatMessage: Contains role (str), content (str), and an optional timestamp (str).
• ChatRequest: Wraps the messages and optional configuration like model and stream.

Sources: server/routes/chat.py:11-16, server/models/chat.py:7-36, web/app/api/chat/route.ts:35-45

2. Get History

Route: GET /api/v1/chat/history (Backend) / GET /api/chat/history (Frontend Proxy)

Retrieves the full transcript of the conversation. The frontend polls this endpoint every 1500ms to detect updates from background processes (like email notifications or agent completions).

Response Structure:

{
  "messages": [
    {
      "role": "user",
      "content": "Hello",
      "timestamp": "2023-10-01 12:00:00"
    },
    {
      "role": "assistant",
      "content": "Hi there! How can I help?",
      "timestamp": "2023-10-01 12:00:05"
    }
  ]
}

Sources: server/routes/chat.py:20-24, web/app/page.tsx:16-18, server/models/chat.py:44-46

3. Clear History

Route: DELETE /api/v1/chat/history (Backend) / DELETE /api/chat/history (Frontend Proxy)

Performs a comprehensive reset of the assistant's state. This action clears:

• The main conversation log.
• All execution agent logs.
• The agent roster (active agent instances).
• All scheduled triggers and reminders.

Sources: server/routes/chat.py:27-46, web/app/api/chat/history/route.ts:25-27

Backend Orchestration Logic

The InteractionAgentRuntime class manages the core logic for the Chat API. It uses a "Conversation Log" for persistence and a "Working Memory Log" for summarized context when summarization is enabled.

Interaction Loop Details

1. Transcript Loading: Loads history from poke_conversation.log or the summarized working memory.
2. LLM Query: Calls OpenRouter with the system prompt and conversation history.
3. Tool Execution: If the LLM returns tool calls (e.g., send_message_to_agent, send_draft), the runtime executes them locally.
4. Finalization: The loop continues (up to 8 iterations) until the agent provides a final natural language response for the user.

Persistence Layer

Conversation data is stored in an append-only log format to ensure durability.

Component	File Path	Function
Conversation Log	server/data/conversation/poke_conversation.log	Stores raw message tags (<user_message>, <poke_reply>, <agent_message>) with timestamps.
Working Memory	server/data/conversation/poke_working_memory.log	Stores summarized briefings and recent unsummarized entries to stay within LLM context limits.

Sources: server/services/conversation/log.py:19-21, server/services/conversation/summarization/working_memory_log.py:19-21

The Chat API Endpoints serve as the gateway to the multi-agent system, abstracting complex background operations like email triage and reminder scheduling into a simple message-based interface. By combining synchronous message submission with asynchronous polling, the system maintains a responsive UI while handling long-running agent tasks.