# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gaming.skillfulai.io/unity-gaming-sdk/services/skillful-agents/service-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.