Create TIA Agent

This Skill helps you create a new TIA XMPP agent by copying and customizing the mistral-minimal example.

Instructions

When a user wants to create a new agent, follow these steps:

1. Understand Requirements

Ask the user:

• •Agent name: What should the agent be called? (lowercase, no spaces)
• •LLM provider: Which LLM API? (Mistral, Groq, Claude, OpenAI, Ollama, etc.)
• •Location: Where should the new agent directory be created? (default: ../my-agent)
• •Server: Which XMPP server? (default: tensegrity.it)
• •Room: Which MUC room to join? (default: general@conference.tensegrity.it)

2. Copy mistral-minimal Template

cp -r mistral-minimal /path/to/new-agent
cd /path/to/new-agent

3. Update Configuration Files

package.json

• •Update name field to the agent name
• •Verify dependencies (tia-agents, hyperdata-clients, dotenv)

.env

• •Copy .env.example to .env
• •Add the required API key (e.g., MISTRAL_API_KEY, GROQ_API_KEY, etc.)
• •Optionally override XMPP settings

config/agents/*.ttl

• •Rename mistral2.ttl to <agent-name>.ttl
• •Update all occurrences of mistral2 to the new agent name
• •Update xmpp:service, xmpp:domain if using different server
• •Update agent:roomJid if joining different room
• •Update agent:nickname to desired display name

mistral-example.js

• •Rename to <agent-name>.js or keep as-is
• •Update PROFILE_NAME default to match your agent name
• •Update package.json main and start script if renamed

4. Customize the Provider

If using a different LLM provider, edit mistral-provider.js:

For Groq:

import { Groq } from "hyperdata-clients";

export class GroqProvider extends BaseLLMProvider {
  initializeClient(apiKey) {
    return new Groq({ apiKey });
  }

  async completeChatRequest({ messages, maxTokens, temperature }) {
    return await this.client.client.chat.completions.create({
      model: this.model,
      messages,
      max_tokens: maxTokens,
      temperature
    });
  }

  extractResponseText(response) {
    return response.choices[0]?.message?.content?.trim() || null;
  }
}

For Claude:

import { Claude } from "hyperdata-clients";

export class ClaudeProvider extends BaseLLMProvider {
  initializeClient(apiKey) {
    return new Claude({ apiKey });
  }

  async completeChatRequest({ messages, maxTokens, temperature }) {
    return await this.client.client.messages.create({
      model: this.model,
      messages,
      max_tokens: maxTokens,
      temperature
    });
  }

  extractResponseText(response) {
    return response.content[0]?.text?.trim() || null;
  }
}

Update the import and class name in the main agent file accordingly.

5. Install and Run

npm install
npm start

6. Verify Connection

The agent should:

1. •Auto-register with the XMPP server (if no password in secrets.json)
2. •Connect and join the specified room
3. •Respond when mentioned by name

Test by sending a message in the room: @agent-name hello

Common Customizations

Change System Prompt

Edit the agent's .ttl file:

agent:aiProvider [
  a agent:MistralProvider ;
  agent:model "mistral-small-latest" ;
  agent:systemPrompt "You are a helpful assistant specializing in..." ;
  agent:apiKeyEnv "MISTRAL_API_KEY"
] .

Enable Lingue Protocol Features

In the .ttl file:

agent:aiProvider [
  a agent:MistralProvider ;
  agent:lingueEnabled true ;
  agent:lingueConfidenceMin 0.7 ;
  agent:ibisSummaryEnabled true
] .

Change Model

Update the model in the .ttl file:

agent:aiProvider [
  a agent:MistralProvider ;
  agent:model "mistral-large-latest"
] .

Or for Groq:

agent:aiProvider [
  a agent:GroqProvider ;
  agent:model "llama-3.3-70b-versatile"
] .

Add Multiple Rooms

Agents can only join one room via the profile, but you can:

1. •Create multiple agent profiles (one per room)
2. •Run the same agent code with different AGENT_PROFILE env vars

Custom Message Handling

Extend the provider's handle method or create a custom provider by extending BaseProvider.

File Structure Reference

my-agent/
├── config/agents/
│   ├── my-agent.ttl           # Agent profile
│   ├── mistral-base.ttl       # Base profile (keep or customize)
│   └── secrets.json           # Auto-generated XMPP passwords
├── my-provider.js             # LLM provider implementation
├── my-agent.js                # Main agent runner
├── package.json               # Dependencies and scripts
├── .env                       # API keys and overrides
├── .env.example               # Template
└── README.md                  # Documentation

Troubleshooting

Agent won't connect

• •Check XMPP server settings in .ttl file
• •Verify NODE_TLS_REJECT_UNAUTHORIZED=0 if using self-signed certs
• •Check server is reachable: telnet tensegrity.it 5222

API errors

• •Verify API key is correct in .env
• •Check API key environment variable name matches agent:apiKeyEnv in profile
• •Ensure API key has necessary permissions

Agent doesn't respond

• •Check the agent joined the room (look for presence in XMPP client)
• •Try mentioning the agent: @agent-name hello
• •Check logs for errors

Profile loading errors

• •Verify .ttl syntax (common issue: missing dots at end of statements)
• •Check all prefixes are defined
• •Ensure agent resource identifier matches filename

Next Steps

After creating your agent:

1. •Customize behavior: Edit system prompts and model parameters
2. •Add features: Implement custom handlers in the provider
3. •Deploy: Run on a server with pm2 or systemd
4. •Monitor: Watch logs and chat activity
5. •Iterate: Adjust prompts and settings based on behavior

Additional Resources

• •TIA Documentation
• •Provider Guide
• •Lingue Protocol
• •hyperdata-clients

Examples

See mistral-minimal/README.md for the complete reference implementation.