diff --git a/docs/docs/documentation/developing/create-gateways.md b/docs/docs/documentation/developing/create-gateways.md index c8b5e4b9a..a91d4f98d 100644 --- a/docs/docs/documentation/developing/create-gateways.md +++ b/docs/docs/documentation/developing/create-gateways.md @@ -448,6 +448,7 @@ apps: app_config: # Required: namespace for A2A topics namespace: ${NAMESPACE} + gateway_id: my_gateway # Required: path to your adapter class gateway_adapter: my_package.adapters.MyAdapter @@ -477,6 +478,10 @@ apps: appropriately for the platform. ``` +:::info +If `gateway_id` is not provided, it defaults to the app name. Ensure `apps.name` is unique across all gateways or specify a unique `gateway_id` to prevent conflicts. +::: + ## Example: Slack Adapter The Slack gateway adapter demonstrates a complete implementation of the adapter pattern. It handles: diff --git a/docs/docs/documentation/developing/tutorials/mcp-gateway.md b/docs/docs/documentation/developing/tutorials/mcp-gateway.md index 6b0f1687d..c0278a7ed 100644 --- a/docs/docs/documentation/developing/tutorials/mcp-gateway.md +++ b/docs/docs/documentation/developing/tutorials/mcp-gateway.md @@ -5,7 +5,7 @@ sidebar_position: 17 # MCP Gateway -This tutorial walks you through setting up the MCP Gateway, which exposes Solace Agent Mesh agents as a Model Context Protocol (MCP) server. This allows any MCP-compatible client (such as Claude Desktop, MCP Inspector, or custom applications) to interact with Solace Agent Mesh agents through a standardized interface. +This tutorial walks you through setting up the MCP Gateway, which exposes Solace Agent Mesh agents as a Model Context Protocol (MCP) server. This allows MCP-compatible client (such as Claude Desktop, MCP Inspector, or custom applications) to interact with Solace Agent Mesh agents through a standardized interface. :::info[Learn about gateways] Read about [Gateways](../../components/gateways.md) before you start this tutorial. @@ -14,11 +14,11 @@ Read about [Gateways](../../components/gateways.md) before you start this tutori ## Overview The MCP Gateway adapter: -- **Dynamically discovers agents** from the Solace Agent Mesh agent registry -- **Creates MCP tools automatically** based on agent skills -- **Streams responses** in real-time back to MCP clients -- **Handles files intelligently** by returning inline content or resource links based on size -- **Maintains session isolation** ensuring secure multi-client access +- Dynamically discovers agents from the Solace Agent Mesh agent registry +- Creates MCP tools automatically based on agent skills +- Streams responses in real-time back to MCP clients +- Handles files intelligently by returning inline content or resource links based on size +- Maintains session isolation ensuring secure multi-client access ## Setting Up the Environment @@ -35,8 +35,8 @@ sam plugin add my-mcp-gateway --plugin sam-mcp-server-gateway-adapter You can use any name for your gateway. In this tutorial we use `my-mcp-gateway`. This command: -1. Installs the `sam-mcp-server-gateway-adapter` plugin -2. Creates a new gateway configuration named `my-mcp-gateway` in your `configs/gateways/` directory +1. Installs the `sam-mcp-server-gateway-adapter` plugin. +2. Creates a gateway configuration named `my-mcp-gateway` in your `configs/gateways/` directory. ## Configuration @@ -179,9 +179,9 @@ sam run configs/gateways/my-mcp-gateway.yaml ``` The gateway starts and automatically: -1. Queries the agent registry for available agents -2. Creates MCP tools for each agent skill -3. Starts listening for MCP client connections +1. Queries the agent registry for available agents. +2. Creates MCP tools for each agent skill. +3. Starts listening for MCP client connections. ## Connecting MCP Clients @@ -335,23 +335,25 @@ When a tool response includes both text and files, the MCP gateway returns a lis ## Troubleshooting -### No tools appearing in MCP client +### Issue: No tools appearing in MCP client +#### Possible Solutions: -- Check that agents are registered in the agent registry -- Verify agents have skills defined in their AgentCard -- Check gateway logs for tool registration messages -- Review tool filter configuration if using `include_tools` or `exclude_tools` +- Check that agents are registered in the agent registry. +- Verify agents have skills defined in their AgentCard. +- Check gateway logs for tool registration messages. +- Review tool filter configuration if using `include_tools` or `exclude_tools`. - If authentication is enabled, ensure RBAC permissions are set correctly. -### Connection refused +### Issue: Connection refused +#### Possible Solutions: -- Verify the MCP server is running (check logs) -- Ensure the configured port is not in use -- Check firewall settings (for HTTP transport) +- Verify the MCP server is running (check logs). +- Ensure the configured port is not in use. +- Check firewall settings (for HTTP transport). +### Issue: Files not appearing or timing out +#### Possible Solutions: -### Files not appearing or timing out - -- Check file size thresholds in configuration -- Verify artifact service is configured correctly -- Review session management in logs +- Check file size thresholds in configuration. +- Verify artifact service is configured correctly. +- Review session management in logs. diff --git a/docs/docs/documentation/developing/tutorials/rest-gateway.md b/docs/docs/documentation/developing/tutorials/rest-gateway.md index 3e6deaff0..b5f37480f 100644 --- a/docs/docs/documentation/developing/tutorials/rest-gateway.md +++ b/docs/docs/documentation/developing/tutorials/rest-gateway.md @@ -55,59 +55,228 @@ To run the REST Gateway, use the following command: sam run configs/gateways/my-http-rest.yaml ``` -## Sending a Request via REST API +## REST API Reference -You can also interact with Agent Mesh via the **REST API**. +This section provides detailed curl commands for interacting with the Solace Agent Mesh v2 REST API. -The REST API gateway runs on `http://localhost:8080` by default. You can use either the legacy v1 API or the modern async v2 API. +### Setup + +Set the required environment variables: -### Modern API (v2) - Asynchronous ```sh -# Submit task -curl --location 'http://localhost:8080/api/v2/tasks' \ ---header 'Authorization: Bearer token' \ ---form 'agent_name="OrchestratorAgent"' \ ---form 'prompt="Hi\!"' +export SAM_TOKEN="your-access-token" +export SAM_HOST="http://localhost:8000" # adjust for your environment +``` -# Poll for result using returned task ID -curl --location 'http://localhost:8080/api/v2/tasks/{taskId}' \ ---header 'Authorization: Bearer token' +:::note[Getting Your Access Token] +You can retrieve your access token from the WebUI gateway by opening the browser developer console and entering: + +```javascript +console.log(window.localStorage.access_token) ``` -:::warning -It might take a while for the system to respond. See the [observability](../../deploying/observability.md) page for more information about monitoring the system while it processes the request. +Copy the displayed token and use it as your `SAM_TOKEN` value. ::: -Sample output: +### API Operations + +#### 1. Create Task + +Create a new task with a prompt. + +```sh +curl -s -X POST "${SAM_HOST}/api/v2/tasks" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -F "agent_name=OrchestratorAgent" \ + -F "prompt=Hi!" +``` + +**Parameters:** +- `agent_name` - The agent to handle the task (e.g., OrchestratorAgent) +- `prompt` - The task prompt/question + +**Response:** -From `api/v2/tasks` ```json { - "taskId":"task-6a0e682f4f6c4927a5997e4fd06eea83" + "taskId": "abc123-def456", + ... } ``` -From `api/v2/tasks/{taskId}` +#### 2. Create Task with Artifact Generation + +Create a task that generates an artifact (file). + +```sh +curl -s -X POST "${SAM_HOST}/api/v2/tasks" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -F "agent_name=OrchestratorAgent" \ + -F "prompt=Create a csv file with 10 mock employees. Make sure to provide the created artifact." +``` + +#### 3. Create Task with File Input + +Create a task with a file attachment. + +```sh +curl -s -X POST "${SAM_HOST}/api/v2/tasks" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -F "agent_name=OrchestratorAgent" \ + -F "prompt=Give a summary of the attached file" \ + -F "files=@/path/to/your/file.pdf" +``` + +**Parameters:** +- `files` - File attachment (use @ prefix for file path) + +#### 4. Poll Task Status + +Poll the status of a task until completion. + +```sh +curl -s -X GET "${SAM_HOST}/api/v2/tasks/${TASK_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" +``` + +**Response includes:** +- `taskId` - The task identifier +- `contextId` - Context ID (use this value for the `session_id` parameter in artifact operations) +- `status` - Task status (e.g., `completed`, `in_progress`) + +:::warning +It might take a while for the system to respond. See the [observability](../../deploying/observability.md) page for more information about monitoring the system while it processes the request. +::: + +#### 5. List Artifacts + +List all artifacts for a context. + +```sh +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" +``` + +:::info +The query parameter is `session_id`, but the value comes from `contextId` in the poll response. +::: + +**Response:** + +```json +[ + { + "filename": "employees.csv", + ... + } +] +``` + +#### 6. Get Artifact + +Download a specific artifact and save to a file. + +```sh +# Save to file (works for binary files like images) +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/${FILENAME}?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -o "${FILENAME}" +``` + +**Examples:** + +```sh +# Download a CSV file +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/report.csv?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -o "report.csv" + +# Download a PNG image +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/chart.png?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -o "chart.png" + +# Output text file to stdout (for piping) +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/data.json?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" +``` + +#### 7. Refresh Token + +Refresh an access token. + +```sh +curl -s -X POST "${SAM_HOST}/refresh_token" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "provider": "azure", + "refresh_token": "your-refresh-token" + }' +``` + +**Response:** ```json { - "id": "task-6a0e682f4f6c4927a5997e4fd06eea83", - "sessionId": "rest-session-4df0c24fcecc45fcb69692db9876bc5c", - "status": { - "state": "completed", - "message": { - "role": "agent", - "parts": [{ "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today's Perfect Activities (13°C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." }] - }, - "timestamp": "2025-07-03T16:54:15.273085" - }, - "artifacts": [], - "metadata": { "agent_name": "OrchestratorAgent" } + "access_token": "new-access-token", + "refresh_token": "new-refresh-token" } ``` +### Typical Workflow + +```sh +# 1. Set your token +export SAM_TOKEN="your-token" +export SAM_HOST="http://localhost:8000" + +# 2. Create a task +RESPONSE=$(curl -s -X POST "${SAM_HOST}/api/v2/tasks" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -F "agent_name=OrchestratorAgent" \ + -F "prompt=Create a CSV with 5 products") + +TASK_ID=$(echo $RESPONSE | jq -r '.taskId') +echo "Task ID: $TASK_ID" + +# 3. Poll until complete +POLL_RESPONSE=$(curl -s -X GET "${SAM_HOST}/api/v2/tasks/${TASK_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}") + +echo $POLL_RESPONSE | jq . + +# 4. Get context ID from poll response, then list artifacts +CONTEXT_ID=$(echo $POLL_RESPONSE | jq -r '.contextId') + +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" | jq . + +# 5. Download artifact +FILENAME="products.csv" +curl -s -X GET "${SAM_HOST}/api/v2/artifacts/${FILENAME}?session_id=${CONTEXT_ID}" \ + -H "Authorization: Bearer ${SAM_TOKEN}" \ + -o "${FILENAME}" + +echo "Saved to: ${FILENAME}" +``` + +### API Endpoints Summary + +| Operation | Method | Endpoint | +|-----------|--------|----------| +| Create Task | POST | `/api/v2/tasks` | +| Poll Task | GET | `/api/v2/tasks/{taskId}` | +| List Artifacts | GET | `/api/v2/artifacts/?session_id={contextId}` | +| Get Artifact | GET | `/api/v2/artifacts/{filename}?session_id={contextId}` | +| Refresh Token | POST | `/refresh_token` | + +## Legacy API (v1) - Synchronous + +:::warning[Deprecated] +The v1 API is deprecated. Please use the v2 API for new integrations. +::: -### Legacy API (v1) - Synchronous ```sh curl --location 'http://localhost:8080/api/v1/invoke' \ --header 'Authorization: Bearer None' \ @@ -116,7 +285,7 @@ curl --location 'http://localhost:8080/api/v1/invoke' \ --form 'stream="false"' ``` -Sample output: +**Sample output:** ```json {