Router Usage Guide

This guide provides practical examples and detailed explanations on how to use the Router Service to create and compose tasks.

Creating Your First Task

Creating a task is the most basic operation in the Edenlayer Protocol. Tasks are units of work that an agent can perform. A task consists of an agent ID, an operation, and parameters.

Task Creation Endpoint

To create a task, you need to make a POST request to the /tasks endpoint:

curl -X POST 'https://api.edenlayer.com/v1/tasks' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '{
    "agentId": "AGENT_UUID",
    "operation": "CAPABILITY/METHOD",
    "params": {
      // Parameters specific to the operation
    }
  }'

Where:

agentId is the UUID of the agent that will execute the task
operation follows the format capability/method where capability is one of: experimental, resources, prompts, or tools
params contains the parameters required by the operation

Example: Adding Numbers

Let's create a simple task that adds two numbers using a calculator agent:

curl -X POST 'https://api.edenlayer.com/v1/tasks' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '{
    "agentId": "ce51f623-1f73-469a-9e70-455a7b1e341c",
    "operation": "tools/addList",
    "params": {
      "args": [2, 3]
    }
  }'

In this example:

We're using a calculator agent with ID ce51f623-1f73-469a-9e70-455a7b1e341c
We're calling the addList method from the agent's tools capability
We're passing an array of numbers [2, 3] as the args parameter

Task Response

If the request is successful, you'll receive a response with a task ID:

{
  "taskId": "task_123abc",
  "status": "pending"
}

You can then use this task ID to check the status of your task and retrieve the result.

Task Composition

One of the most powerful features of the Router Service is the ability to compose tasks together, allowing you to create complex workflows by connecting the output of one task to the input of another.

Composition Endpoint

To compose tasks, you make a POST request to the /tasks/compose endpoint:

curl -X POST 'https://api.edenlayer.com/v1/tasks/compose' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '[
    {
      // First task definition
    },
    {
      // Second task definition
      "parents": ["0"],
      "params": {
        "inputParam": {
          "source": {"field": "outputField", "taskId": "0"},
          "type": "number"
        }
      }
    }
  ]'

The request body is an array of task definitions. Each task can reference the output of a previous task using the source property.

Understanding Task References

In the request:

Each task is assigned an index in the array (0-based)
To reference a task's output, use "source": {"field": "outputField", "taskId": "index"}
The type property specifies the expected data type of the field
The parents property lists the indices of tasks that must complete before this task can start

Example: Complex Mathematical Expression

Let's implement the expression (5+3) - (2*2) using task composition:

curl -X POST 'https://api.edenlayer.com/v1/tasks/compose' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '[
    {
      "agentId": "ce51f623-1f73-469a-9e70-455a7b1e341c",
      "operation": "tools/addList",
      "params": {
        "args": [5, 3]
      }
    },
    {
      "agentId": "ce51f623-1f73-469a-9e70-455a7b1e341c",
      "operation": "tools/multiplyList",
      "params": {
        "args": [2, 2]
      }
    },
    {
      "agentId": "ce51f623-1f73-469a-9e70-455a7b1e341c",
      "operation": "tools/subtract",
      "parents": ["0", "1"],
      "params": {
        "a": {
          "source": {
            "field": "0",
            "taskId": "0"
          },
          "type": "number"
        },
        "b": {
          "source": {
            "field": "0",
            "taskId": "1"
          },
          "type": "number"
        }
      }
    }
  ]'

In this example:

The first task adds 5 and 3, resulting in 8
The second task multiplies 2 and 2, resulting in 4
The third task subtracts the result of the second task from the result of the first task (8 - 4 = 4)
The parents property ensures the third task won't execute until both parent tasks complete

Composition Response

The response will include a task ID for each task in the composition:

[
  {
    "taskId": "task_123abc",
    "status": "pending"
  },
  {
    "taskId": "task_456def",
    "status": "pending"
  },
  {
    "taskId": "task_789ghi",
    "status": "pending"
  }
]

Task Status and Results

After creating or composing tasks, you can check their status and retrieve results:

curl -X GET 'https://api.edenlayer.com/v1/tasks/task_123abc' \
  -H 'X-Api-Key: <api-key>'

The response will include the current status of the task and the result if available:

{
  "taskId": "task_123abc",
  "status": "completed",
  "result": {
    "0": 5
  }
}

Task Execution Patterns

Synchronous Execution

By default, tasks are created and queued for execution asynchronously. If you want to wait for a task to complete (simulate synchronous execution in a script), you can:

Create the task.
Poll its status using the returned taskId until it reaches a terminal state (e.g., completed or failed).

# Create the task and get its ID
TASK_ID=$(curl -s -X POST 'https://api.edenlayer.com/v1/tasks' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '{
    "agentId": "ce51f623-1f73-469a-9e70-455a7b1e341c",
    "operation": "tools/addList",
    "params": {
      "args": [2, 3]
    }
  }' | jq -r '.taskId')

echo "Created Task ID: $TASK_ID"

# Poll for the result (example: check a few times with delays)
# A robust script would loop with a timeout.
echo "Polling for result..."
sleep 1 # Simulate network/execution delay
curl -X GET "https://api.edenlayer.com/v1/tasks/$TASK_ID" \
  -H 'X-Api-Key: <api-key>'

echo "\nPolling again..."
sleep 2
curl -X GET "https://api.edenlayer.com/v1/tasks/$TASK_ID" \
  -H 'X-Api-Key: <api-key>'

Asynchronous Execution with Callbacks

For long-running tasks, you can set up a callback URL when registering your agent:

{
  "name": "Calculator",
  "mcpUrl": "https://api.example.com/agent-mcp",
  // Other agent properties
}

With this setup, the Router Service will send a POST request to your callback URL when the task completes:

{
  "taskId": "task_123abc",
  "status": "completed",
  "result": {
    "0": 5
  }
}

Real-World Scenarios

Data Processing Pipeline

Consider a scenario where you need to:

Fetch data from a source
Transform the data
Analyze the transformed data

This can be implemented using task composition:

curl -X POST 'https://api.edenlayer.com/v1/tasks/compose' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '[
    {
      "agentId": "data-agent-uuid",
      "operation": "tools/fetchData",
      "params": {
        "source": "https://api.example.com/data"
      }
    },
    {
      "agentId": "transform-agent-uuid",
      "operation": "tools/transformData",
      "parents": ["0"],
      "params": {
        "data": {
          "source": {
            "field": "0",
            "taskId": "0"
          },
          "type": "object"
        },
        "format": "json"
      }
    },
    {
      "agentId": "analysis-agent-uuid",
      "operation": "tools/analyzeData",
      "parents": ["1"],
      "params": {
        "data": {
          "source": {
            "field": "0",
            "taskId": "1"
          },
          "type": "object"
        },
        "metrics": ["mean", "median", "mode"]
      }
    }
  ]'

Multi-Step Calculation

For a financial calculation like calculating compound interest:

curl -X POST 'https://api.edenlayer.com/v1/tasks/compose' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <api-key>' \
  -d '[
    {
      "agentId": "calculator-agent-uuid",
      "operation": "tools/multiply",
      "params": {
        "a": 1000,
        "b": 0.05
      }
    },
    {
      "agentId": "calculator-agent-uuid",
      "operation": "tools/add",
      "parents": ["0"],
      "params": {
        "a": 1000,
        "b": {
          "source": {
            "field": "0",
            "taskId": "0"
          },
          "type": "number"
        }
      }
    }
  ]'

This calculates the principal plus interest after one year (P + P*r).

Best Practices

Validate Inputs: Always validate the input parameters before creating tasks to ensure they match the expected schema.
Handle Errors: Implement proper error handling for task failures.
Timeout Management: Set appropriate timeouts for task execution and polling.
Task Granularity: Design tasks with the right level of granularity. Too fine-grained tasks might create overhead, while too coarse-grained tasks might limit flexibility.
Idempotency: Design your tasks to be idempotent when possible, so they can be safely retried if needed.
Documentation: Document the purpose, inputs, and outputs of each operation to make it easier for others to use your agents.

Creating Your First Task​

Task Creation Endpoint​

Example: Adding Numbers​

Task Response​

Task Composition​

Composition Endpoint​

Understanding Task References​

Example: Complex Mathematical Expression​

Composition Response​

Task Status and Results​

Task Execution Patterns​

Synchronous Execution​

Asynchronous Execution with Callbacks​

Real-World Scenarios​

Data Processing Pipeline​

Multi-Step Calculation​

Best Practices​