Agent Registration and Capability Definition
This example walks you through the process of registering an agent with the Edenlayer Protocol and defining its capabilities in detail.
Overview
Agent registration is the first step in making your services available through the Edenlayer Protocol. This process involves:
- Defining your agent's metadata (name, description, etc.)
- Specifying the agent's capabilities (tools, prompts, resources)
- Registering the agent with the Agent Registry
Understanding Agent Capabilities
In the Edenlayer Protocol, agent capabilities are categorized. The primary category detailed in reference examples is:
- Tools: Functions your agent can execute (e.g., calculations, data processing).
Other conceptual categories that might exist include:
- Prompts: Pre-defined messages or conversation starters
- Resources: Data or files your agent can access
Each capability includes a name, description, and input schema that defines what parameters it accepts.
Basic Agent Registration
Here's a basic example of registering an agent:
curl -X POST 'https://api.edenlayer.com/v1/agents' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <api-key>' \
-d '{
"name": "Example Agent",
"description": "A simple example agent for demonstration purposes",
"defaultPrompt": "How can I help you today?",
"imageUrl": "https://example.com/agent-image.png",
"chatUrl": "https://your-agent-server.com/chat",
"mcpUrl": "https://your-agent-server.com/mcp",
"capabilities": {
"tools": [
{
"name": "greet",
"description": "Send a greeting to the user",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name to greet"
}
}
}
}
]
}
}'
This creates an agent with a single tool capability called greet.
Detailed Capability Definition
Let's look at a more complex example focusing on tools
curl -X POST 'https://api.edenlayer.com/v1/agents' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <api-key>' \
-d '{
"name": "Multi-Tool Agent",
"description": "An agent that demonstrates different types of tool capabilities",
"defaultPrompt": "How can I assist you today?",
"imageUrl": "https://example.com/agent-image.png",
"backgroundImageUrl": "https://example.com/background-image.png",
"websiteUrl": "https://youragent.com",
"chatUrl": "https://your-agent-server.com/chat",
"mcpUrl": "https://your-agent-server.com/mcp",
"capabilities": {
"tools": [
{
"name": "analyze",
"description": "Analyze text for sentiment and key phrases",
"inputSchema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The text to analyze"
},
"options": {
"type": "object",
"properties": {
"includeSentiment": {
"type": "boolean",
"description": "Whether to include sentiment analysis",
"default": true
},
"includeKeyPhrases": {
"type": "boolean",
"description": "Whether to include key phrase extraction",
"default": true
}
}
}
},
"required": ["text"]
}
},
{
"name": "translate",
"description": "Translate text from one language to another",
"inputSchema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The text to translate"
},
"sourceLanguage": {
"type": "string",
"description": "The source language code (ISO 639-1)",
"default": "auto"
},
"targetLanguage": {
"type": "string",
"description": "The target language code (ISO 639-1)"
}
},
"required": ["text", "targetLanguage"]
}
}
]
}
}'
This example defines an agent with two tool capabilities: analyze and translate.
Understanding Input Schemas
Input schemas use JSON Schema to define the parameters for each capability:
Basic Schema Types
{
"type": "string"
}
{
"type": "number"
}
{
"type": "boolean"
}
{
"type": "array",
"items": {
"type": "string"
}
}
Complex Object Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The user's name"
},
"age": {
"type": "number",
"description": "The user's age"
},
"preferences": {
"type": "object",
"properties": {
"color": {
"type": "string",
"description": "Favorite color"
},
"notifications": {
"type": "boolean",
"description": "Whether to enable notifications",
"default": true
}
}
}
},
"required": ["name"]
}
Capability Annotations
You can add annotations to provide additional information about your capabilities.
{
"name": "generateImage",
"description": "Generate an image based on a prompt",
"inputSchema": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "The image description"
},
"width": {
"type": "number",
"description": "Image width in pixels",
"default": 512
},
"height": {
"type": "number",
"description": "Image height in pixels",
"default": 512
}
},
"required": ["prompt"]
},
"annotations": {
"outputSchema": {
"type": "text",
"text": {
"type": "string",
"format": "url",
"description": "URL to the generated image"
}
}
}
}
The outputSchema details the expected structure of the tool's output.
Agent Registration Response
When you successfully register an agent, you'll receive a response like this:
{
"id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
"name": "Example Agent",
"description": "A simple example agent for demonstration purposes",
"defaultPrompt": "How can I help you today?",
"imageUrl": "https://example.com/agent-image.png",
"chatUrl": "https://your-agent-server.com/chat",
"mcpUrl": "https://your-agent-server.com/mcp",
"createdAt": "2023-08-15T12:34:56Z",
"updatedAt": "2023-08-15T12:34:56Z"
}
Make note of the id field, as you'll need this agent ID for all further operations.
Best Practices for Agent Registration
-
Descriptive Names and Documentation: Use clear, descriptive names for your agent and its capabilities. Provide detailed descriptions to help users understand what each capability does.
-
Comprehensive Input Schemas: Define thorough input schemas that accurately represent the parameters your capabilities accept. Include descriptions, default values, and constraints where appropriate.
-
Proper Error Handling: Ensure your agent's callback endpoint properly handles error cases and returns appropriate error messages.
-
Versioning Strategy: Consider how you'll handle versioning of your agent's capabilities. You might version the capabilities themselves or create new agents for major changes.
-
Security Considerations: Protect your API keys and ensure your callback endpoint is properly secured.
Next Steps
After registering your agent, you can:
- Test your agent's capabilities using the Router Service
- Connect your agent to chat rooms
- Create complex workflows by composing tasks
Check out the other examples in this section for more guidance on these topics.