Integration Guide
Mental Model
Think of HUMA as an async, stateful API. You start by setting the parameters like HUMA personality, rules, and toolset.
Once HUMA is created, you can connect to it from your app. Usually your app has state - like conversation history in group chat, list of online users, or agent's hand in a card game.
These types of events are called Context Updates and consist of event description ("John sent message: Hello World!") and new state after this event happened (conversation history including John's message).
That's the primary way your app communicates with HUMA - via context updates.
HUMA communicates back via tool calls. Based on current context and recent events HUMA might decide to use one of the tools from its toolset.
When you receive a tool call event, you should process it, and when it's ready send back result to HUMA. The asynchronous nature of all tools allows you to process tools for many seconds or even minutes without sacrificing real-time behavior.
Example: Card Game with Group Chat
Imagine you want to implement a card game with group chat, with HUMA as one of the players.
1. Design Personality
Think about the personality you want HUMA to have. Is it competitive? Friendly? A trash-talker?
2. Describe the Rules
"You are playing Texas Poker. You can check, call, raise, or fold. The goal is to win chips..."
3. Design State
Design a state that contains all information a normal player would have - whose turn it is, what cards are visible on the table, what cards HUMA has in its hand, what is the stake, but also the conversation history of the group chat.
4. Send State Updates
Send state updates every time state changes - after every turn or player's action.
5. Design Tools (Actions)
Think about actions that agent needs to perform. In this case it might be "call", "check", "send_message", "pass". Your app is responsible for checking if it's agent's turn when these tools are called.
Process of Designing HUMA Integration
Where to use HUMA
Decide where do you want to use HUMA. Common use cases include:
NPCs, opponents, teammates
Support, coaching, facilitation
Chat participants, moderators
Design Personality
Think of the setting in which HUMA operates. Answer these questions:
Design Rules
This is how HUMA should behave in this specific scenario. It might include:
- •Description of the task
- •Rules of the game
- •Guidelines and constraints
- •Expected behaviors and responses
Design State
What information from your app should agent have? The easiest way to design the state is to imagine you put a human in the place of HUMA - what should be in the UI of human user?
This can include chat message history, presence status of users, game state available to agent, description of game scene.
Note the State Changes
Each update to state is passed to HUMA as Event. These events keep state up-to-date and potentially trigger response from HUMA.
Design the Tools
Tools correspond to actions agent can take. All tools are asynchronous, which means that running a tool doesn't stop HUMA from processing new events.
Example tools include:
send_messageweb_searchrun_programplay_cardmake_moveschedule_reminderPick the Right Router
Router is a component that guides HUMA's behavior. Available router types are:
| Router | Best For |
|---|---|
llm-judge | General purpose, context-aware responses (default) |
conversational | Chat-based apps with timeliness scoring |
turn-taking | Multi-agent voice conversations |
voice-game | Voice game scenarios |
random | Testing, fast (no LLM call) |
For example, if your app is primarily chat-based, use the conversational router. If it's a game bot, use llm-judge router.