create-tia-agent

danja's avatarfrom danja

Guides users through creating a new TIA XMPP agent based on mistral-minimal. Use when the user wants to create, build, set up, or scaffold a new agent, bot, or when they ask how to get started with TIA.

⭐2stars🔀1forks📁View on GitHub🕐Updated Dec 29, 2025

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for scaffolding and deploying TIA XMPP agents. It streamlines the development process by automating project initialization, LLM provider configuration (supporting Mistral, Groq, Claude, and more), and XMPP server integration, allowing developers to quickly move from concept to a functional, connected AI agent.

Use Cases

  • Rapidly scaffolding a new AI agent project by cloning and customizing the mistral-minimal template.
  • Configuring multi-provider LLM support to switch between different AI models like Llama 3, Mistral, or Claude for specific agent tasks.
  • Automating the setup of XMPP communication parameters, including MUC room joining and server authentication.
  • Customizing agent behavior and system prompts through structured Turtle (.ttl) configuration files for specialized use cases.
  • Troubleshooting connectivity and deployment issues for decentralized AI agents within the TIA ecosystem.
namecreate-tia-agent
descriptionGuides users through creating a new TIA XMPP agent based on mistral-minimal. Use when the user wants to create, build, set up, or scaffold a new agent, bot, or when they ask how to get started with TIA.
allowed-toolsRead, Write, Edit, Bash, Glob

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

Examples

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