> For the complete documentation index, see [llms.txt](https://docs.gaming.skillfulai.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gaming.skillfulai.io/unity-gaming-sdk/services/skillful-agents/service-reference.md).

# Service Reference

## `Skillful Agents Service Reference`

This reference guide covers the essential components and usage patterns of the Skillful Agents service, focusing on practical implementation details.

### `Core Components`

#### `SkillfulAgent Component`

The primary component for integrating agents into your Unity game. This component handles:

* Agent selection and management
* Message sending and receiving
* Conversation history tracking
* Error handling and debugging

### `Basic Implementation Patterns`

#### Single Agent Pattern

Best for simple implementations with one agent:

```csharp
using SkillfulAI.Agents;
using UnityEngine;

public class BasicAgent : MonoBehaviour
{
    private SkillfulAgent agent;

    void Start()
    {
        // Basic setup
        agent = gameObject.AddComponent<SkillfulAgent>();
        agent.SelectAgentByName("YourAgentName");
    }

    public void SendQuestion(string question)
    {
        agent.SendMessage(question, HandleResponse);
    }

    private void HandleResponse(string response)
    {
        Debug.Log($"Agent Response: {response}");
    }
}
```

#### `Multi-Agent Pattern`

For games requiring multiple different agents:

```csharp
using SkillfulAI.Agents;
using UnityEngine;

public class AgentManager : MonoBehaviour
{
    private Dictionary<string, SkillfulAgent> agents = new Dictionary<string, SkillfulAgent>();

    void Start()
    {
        CreateAgent("Shopkeeper", "ShopkeeperAI");
        CreateAgent("QuestGiver", "QuestMasterAI");
        CreateAgent("Guard", "GuardianAI");
    }

    private void CreateAgent(string role, string agentName)
    {
        GameObject agentObj = new GameObject($"{role}Agent");
        SkillfulAgent agent = agentObj.AddComponent<SkillfulAgent>();
        agent.SelectAgentByName(agentName);
        agents[role] = agent;
    }

    public void InteractWithAgent(string role, string message)
    {
        if (agents.TryGetValue(role, out SkillfulAgent agent))
        {
            agent.SendMessage(message, response => {
                Debug.Log($"{role} says: {response}");
            });
        }
    }
}
```

#### `Conversation Manager Pattern`

For handling complex dialogue flows:

```csharp
using SkillfulAI.Agents;
using UnityEngine;

public class ConversationManager : MonoBehaviour
{
    private SkillfulAgent agent;
    private Queue<string> messageQueue = new Queue<string>();
    private bool isProcessing = false;

    void Start()
    {
        agent = gameObject.AddComponent<SkillfulAgent>();
        agent.SelectAgentByName("DialogueAgent");
    }

    public void QueueMessage(string message)
    {
        messageQueue.Enqueue(message);
        if (!isProcessing)
        {
            ProcessQueue();
        }
    }

    private void ProcessQueue()
    {
        if (messageQueue.Count == 0)
        {
            isProcessing = false;
            return;
        }

        isProcessing = true;
        string message = messageQueue.Dequeue();
        
        agent.SendMessage(message, response => {
            HandleResponse(response);
            ProcessQueue();
        });
    }

    private void HandleResponse(string response)
    {
        // Process response (e.g., update UI, trigger events)
        Debug.Log($"Response: {response}");
    }
}
```

#### `UI Integration Pattern`

For creating a chat interface:

```csharp
using SkillfulAI.Agents;
using UnityEngine;
using UnityEngine.UI;
using TMPro;

public class AgentChatUI : MonoBehaviour
{
    private SkillfulAgent agent;
    
    [SerializeField] private TMP_InputField inputField;
    [SerializeField] private TextMeshProUGUI chatHistory;
    [SerializeField] private Button sendButton;

    void Start()
    {
        // Setup agent
        agent = gameObject.AddComponent<SkillfulAgent>();
        agent.SelectAgentByName("ChatAgent");

        // Setup UI callbacks
        sendButton.onClick.AddListener(SendMessage);
        inputField.onSubmit.AddListener(_ => SendMessage());
    }

    void SendMessage()
    {
        if (string.IsNullOrEmpty(inputField.text)) return;

        string userMessage = inputField.text;
        AppendToChatHistory($"You: {userMessage}");
        
        agent.SendMessage(userMessage, response => {
            AppendToChatHistory($"Agent: {response}");
        });

        inputField.text = "";
    }

    void AppendToChatHistory(string message)
    {
        chatHistory.text += $"\n{message}";
    }
}
```

#### `Game Event Integration Pattern`

For creating event-driven agent interactions:

```csharp
using SkillfulAI.Agents;
using UnityEngine;

public class GameEventAgent : MonoBehaviour
{
    private SkillfulAgent agent;
    private PlayerState playerState;

    void Start()
    {
        agent = gameObject.AddComponent<SkillfulAgent>();
        agent.SelectAgentByName("GameMasterAI");
        playerState = FindObjectOfType<PlayerState>();
    }

    public void OnPlayerLevelUp(int newLevel)
    {
        string context = $"Player reached level {newLevel}. Current stats: Health={playerState.health}, Strength={playerState.strength}";
        
        agent.SendMessage($"Generate level up message: {context}", response => {
            DisplayMessage(response);
        });
    }

    public void OnQuestComplete(string questId)
    {
        string context = $"Player completed quest {questId}. Total quests completed: {playerState.completedQuests}";
        
        agent.SendMessage($"Generate quest completion dialogue: {context}", response => {
            DisplayMessage(response);
        });
    }

    private void DisplayMessage(string message)
    {
        // Implement your game's message display system
        Debug.Log($"Game Event Message: {message}");
    }
}
```

### `Best Practices`

1. **`Agent Selection`**
   * Select agents early in the game lifecycle
   * Keep agent names consistent with the dashboard
   * Implement fallback behavior for missing agents
2. **`Message Handling`**
   * Keep messages concise and context-aware
   * Implement proper error handling
   * Consider message queuing for multiple requests
3. **`Performance`**
   * Don't spam messages in Update loops
   * Cache agent references
   * Implement cooldowns if needed

{% hint style="info" %}
If you're stuck or need help, don't hesitate to reach out in our [Discord Community](https://discord.gg/WhAYqkXYkg)
{% endhint %}