Mock Agent¶

The Mock Agent is a simulated AI agent that implements the Unified Intent Mediator (UIM) Protocol. It serves as a reference implementation and testing tool for developers working with the protocol.

Overview¶

The Mock Agent demonstrates how AI agents can discover services, request Policy Adherence Tokens (PATs), and execute intents using the UIM Protocol. It provides a command-line interface for interacting with UIM-compatible web services.

Features¶

Service Discovery: Discovers web services using DNS TXT records and agents.json files.
Intent Discovery: Searches for intents based on various criteria.
Policy Retrieval: Retrieves and parses policies from web services.
Policy Signing: Signs policies using RSA key pairs.
PAT Acquisition: Requests and manages PATs from web services.
Intent Execution: Executes intents with the appropriate parameters and PATs.
Command-Line Interface: Provides a user-friendly CLI for interacting with the agent.

Architecture¶

The Mock Agent is built with a modular architecture that separates concerns and promotes maintainability:

+------------------+
|     CLI Layer    |
+------------------+
         |
+------------------+
|   Agent Core     |
+------------------+
         |
+------------------+     +------------------+     +------------------+
| Discovery Module |     |  Policy Module   |     | Execution Module |
+------------------+     +------------------+     +------------------+
         |                       |                        |
+------------------+     +------------------+     +------------------+
| Network Layer    |     | Crypto Layer     |     | Storage Layer    |
+------------------+     +------------------+     +------------------+

Components¶

CLI Layer: Provides the command-line interface for users to interact with the agent.
Agent Core: Coordinates the different modules and manages the agent's state.
Discovery Module: Handles service and intent discovery.
Policy Module: Manages policy retrieval, parsing, and signing.
Execution Module: Handles intent execution and result processing.
Network Layer: Manages HTTP requests and responses.
Crypto Layer: Handles cryptographic operations like key generation and signing.
Storage Layer: Manages persistent storage of keys, PATs, and other data.

Installation¶

Prerequisites¶

Python 3.8 or higher
pip (Python package manager)

Steps¶

Clone the repository:

git clone https://github.com/synaptiai/uim-protocol.git
cd uim-protocol/implementations/uim-mock-agent

Install dependencies:
```
pip install -r requirements.txt
```
Generate keys (if not already present):
```
python mock_agent.py generate-keys
```

Usage¶

Basic Commands¶

The Mock Agent provides several commands for interacting with UIM-compatible web services:

Discover a Service¶

python mock_agent.py discover --domain example.com

This command will: 1. Look up DNS TXT records for example.com 2. Fetch the agents.json file 3. Parse and display service information

Search for Intents¶

python mock_agent.py search-intents --service-url https://api.example.com --tags e-commerce,search

This command will: 1. Query the service's discovery endpoint 2. Filter intents based on the provided tags 3. Display the matching intents

Get a PAT¶

python mock_agent.py get-pat --service-url https://api.example.com

This command will: 1. Retrieve the service's policy 2. Sign the policy with the agent's private key 3. Request a PAT from the service 4. Store the PAT for future use

Execute an Intent¶

python mock_agent.py execute --service-url https://api.example.com --intent-uid example.com:searchProducts:v1 --parameters '{"query": "laptop", "category": "electronics"}'

This command will: 1. Retrieve the PAT for the service (or request a new one if needed) 2. Execute the intent with the provided parameters 3. Display the result

Advanced Usage¶

Interactive Mode¶

The Mock Agent also provides an interactive mode for more complex interactions:

python mock_agent.py interactive

This will start an interactive shell where you can enter commands and see the results in real-time.

Batch Mode¶

For automated testing, you can use batch mode to execute a series of commands from a file:

python mock_agent.py batch --file commands.txt

Where commands.txt contains one command per line.

Verbose Mode¶

To see more detailed information about what the agent is doing, use the --verbose flag:

python mock_agent.py discover --domain example.com --verbose

Configuration¶

The Mock Agent can be configured using a configuration file or environment variables.

Configuration File¶

Create a file named config.json in the agent's directory:

{
  "agent_id": "mock-agent-123",
  "keys_dir": "./keys",
  "pats_dir": "./pats",
  "log_level": "INFO",
  "timeout": 30,
  "verify_ssl": true
}

Environment Variables¶

You can also use environment variables to configure the agent:

UIM_AGENT_ID: The identifier for the agent
UIM_KEYS_DIR: Directory for storing keys
UIM_PATS_DIR: Directory for storing PATs
UIM_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
UIM_TIMEOUT: Request timeout in seconds
UIM_VERIFY_SSL: Whether to verify SSL certificates

Extending the Mock Agent¶

The Mock Agent is designed to be extensible. Here are some ways you can extend it:

Adding New Commands¶

To add a new command, create a new file in the commands directory:

# commands/my_command.py
from .base import BaseCommand

class MyCommand(BaseCommand):
    name = "my-command"
    description = "Description of my command"

    def add_arguments(self, parser):
        parser.add_argument("--my-arg", help="Description of my argument")

    def execute(self, args):
        # Implementation of the command
        print(f"Executing my command with arg: {args.my_arg}")

Then register the command in commands/__init__.py.

Adding New Modules¶

To add a new module, create a new file in the modules directory:

# modules/my_module.py
class MyModule:
    def __init__(self, agent):
        self.agent = agent

    def my_function(self, arg):
        # Implementation of the function
        return f"Result: {arg}"

Then initialize the module in agent.py.

Testing¶

The Mock Agent includes a comprehensive test suite to ensure its functionality:

pytest

For more detailed test output:

pytest -v

To run specific tests:

pytest tests/test_discovery.py

Troubleshooting¶

Common Issues¶

DNS Resolution Errors¶

If you're having trouble with DNS resolution:

Check that the domain exists and has TXT records
Try using the --dns-server flag to specify a different DNS server
Use the --verbose flag to see more detailed error information

PAT Acquisition Errors¶

If you're having trouble acquiring PATs:

Check that your keys are generated correctly
Verify that the service's policy is accessible
Ensure that your agent ID is valid
Use the --verbose flag to see more detailed error information

Intent Execution Errors¶

If you're having trouble executing intents:

Check that you have a valid PAT for the service
Verify that the intent UID is correct
Ensure that the parameters are valid for the intent
Use the --verbose flag to see more detailed error information

Logging¶

The Mock Agent logs information to the console and to a log file. To change the log level:

python mock_agent.py --log-level DEBUG discover --domain example.com

Log files are stored in the logs directory.

Contributing¶

We welcome contributions to the Mock Agent! Please see the Contributing Guide for more information.

License¶

The Mock Agent is licensed under the Apache License 2.0. See the LICENSE file for details.