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: [email protected])

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., MISTRALAPIKEY, GROQAPIKEY, 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 NODETLSREJECT_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](docs/provider-guide.md)
• Lingue Protocol
• hyperdata-clients

Examples

See [mistral-minimal/README.md](mistral-minimal/README.md) for the complete reference implementation.