Agent Development
Learn how to build, containerize, and register agents that can be orchestrated by Consonant.
Consonant is framework-agnostic. Your agents can be Python scripts, Node.js servers, or compiled Go binaries. The only requirement is that they expose an HTTP endpoint that accepts JSON input and returns JSON output.
1. The Agent Interface
Every agent must expose a POST /execute endpoint. Consonant sends the task context and parameters to this endpoint.
# Example: Simple Flask Agent
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/health', methods=['GET'])
def health():
return jsonify({"status": "ok"})
@app.route('/execute', methods=['POST'])
def execute():
data = request.json
task = data.get('task')
# ... Your agent logic here ...
result = perform_task(task)
return jsonify({
"status": "success",
"result": result,
"metadata": {"cost": 0.002}
})2. Defining Capabilities
To make your agent discoverable by the planner, you must define its capabilities in a Kubernetes manifest.
apiVersion: consonant.dev/v1
kind: Agent
metadata:
name: data-analyzer
spec:
image: my-registry/data-analyzer:v1
description: "Analyzes CSV and JSON datasets to extract insights"
capabilities:
- name: analyze_csv
description: "Analyze a CSV file URL and return statistical summary"
parameters:
properties:
url:
type: string
description: "URL to the CSV file"
- name: generate_chart
description: "Create a visualization from data"
resources:
cpu: "1"
memory: "2Gi"Prompt Engineering Tips
Thedescription fields are critical. The Planner uses these descriptions to match user goals to your agent. Be descriptive and specific about what the tool does.3. Handling State
Consonant agents should ideally be stateless. Any context needed for the task is passed in the request. If you need to persist state across invocations, use an external database or the Consonant State Store API.
4. Error Handling
If your agent fails, return a non-200 status code or a JSON payload withstatus: "error". Consonant will automatically handle retries based on your agent's configuration.
// Error Response Example
{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Upstream API rate limit hit",
"retryable": true
}
}