curl

[jmikedupont2]

Here's a comprehensive analysis of the API routes and corresponding curl commands for the elizaOS/eliza agent management system:

Core API Endpoints & curl Examples

1. Base Endpoint

curl http://localhost:3000/
# Response: "Welcome, this is the REST API!"

2. List All Agents

curl http://localhost:3000/agents
# Returns JSON with agent IDs, names, and connected clients

3. Get Agent Details

curl http://localhost:3000/agents/AGENT_UUID
# Replace AGENT_UUID with actual agent ID

4. Update Agent Configuration

curl -X POST -H "Content-Type: application/json" -d '{
    "name": "Updated Agent",
    "settings": {
        "model": "gpt-4",
        "temperature": 0.7
    }
}' http://localhost:3000/agents/AGENT_UUID/set

5. Get Discord Channels

curl http://localhost:3000/agents/AGENT_UUID/channels
# Requires valid DISCORD_API_TOKEN in agent settings

6. Retrieve Memories

curl http://localhost:3000/agents/AGENT_UUID/ROOM_UUID/memories
# Room ID must be valid UUID format

Key Implementation Details

1. Security Considerations

# Recommended authentication header format
curl -H "Authorization: Bearer API_KEY" http://localhost:3000/agents

2. Memory Retrieval Structure

{
    "agentId": "uuid",
    "roomId": "uuid",
    "memories": [{
        "id": "memory_id",
        "content": {
            "text": "Message content",
            "attachments": [{
                "url": "https://example.com/file.txt",
                "contentType": "text/plain"
            }]
        }
    }]
}

3. Error Handling

• 400 Bad Request: Invalid character configuration
• 404 Not Found: Agent/Room doesn't exist
• 500 Server Error: Discord API failures

Best Practices

1. Use agent name lookup as fallback:

curl http://localhost:3000/agents/AgentName/channels
# Works if agent ID not found but name matches

2. Memory pagination example:

curl http://localhost:3000/agents/AGENT_UUID/ROOM_UUID/memories?limit=50&offset=100

3. Recommended headers for development:

curl -v -H "Content-Type: application/json" -H "X-Debug-Mode: true" http://localhost:3000/agents

This API structure demonstrates a robust agent management system with Discord integration and memory persistence capabilities. The design allows for dynamic agent reconfiguration and cross-platform client management.

---

Answer from Perplexity: pplx.ai/share

[jmikedupont2]

Okay, I've analyzed the DirectClient class and its associated routes from the provided paste.txt file. Here's a breakdown of the API endpoints, how they work, and example curl commands to interact with them.

API Endpoints Defined in DirectClient

1. /media/uploads and /media/generated (GET - Static File Serving)

• Purpose: Serves uploaded files and generated images.
• Method: GET
• URL:
  • /media/uploads/:filename (e.g., /media/uploads/1678886400000-123456789-image.jpg)
  • /media/generated/:filename (e.g., /media/generated/agent_image.png)
• Request: GET request to the specific file path.
• Response: The file itself (image, document, etc.).
• curl Example:

curl http://localhost:3000/media/uploads/1678886400000-123456789-image.jpg -o downloaded_image.jpg

2. /:agentId/whisper (POST - Audio Transcription)

• Purpose: Transcribes an audio file using OpenAI's Whisper API.
• Method: POST
• URL: /:agentId/whisper (e.g., /agent123/whisper)
• Request:
  • multipart/form-data with a file field named "file".
• Body: Form data containing the audio file.
• Response: JSON containing the transcription from OpenAI.
• Authentication: Requires the agent to be registered, and OPENAI_API_KEY needs to be set for the agent.
• curl Example:

curl -X POST -F "file=@/path/to/audio.mp3" http://localhost:3000/agent123/whisper

3. /:agentId/message (POST - Send a Message to an Agent)

• Purpose: Sends a text message to an agent and receives a response. It also handles file uploads as attachments.

• Method: POST

• URL: /:agentId/message (e.g., /agent123/message)

• Request:

  • multipart/form-data

• Body: Form data with the following fields:

  • text: The message text.
  • roomId: (Optional) The room ID. Defaults to "default-room-" + agentId.
  • userId: (Optional) The user ID. Defaults to "user".
  • userName: (Optional) username
  • name: (Optional) userScreeName?
  • file: (Optional) An attachment file.

• Response: JSON array containing the agent's response.

• Logic:

  1. Retrieves the agent's runtime.
  2. Ensures a connection between the user and the room using runtime.ensureConnection().
  3. Creates a memory object for the user's message.
  4. Adds the memory to the agent's memory manager.
  5. Composes the context for the agent.
  6. Generates a response using generateMessageResponse().
  7. Saves the response to memory.
  8. Processes actions based on the response.
  9. Returns both the initial response and any messages generated by actions, unless the actions define suppressInitialMessage.

• curl Example (Text Message Only):

curl -X POST -d "text=Hello, agent!&roomId=room123&userId=user456&userName=User&name=User" http://localhost:3000/agent123/message -H "Content-Type: application/x-www-form-urlencoded"

• curl Example (With File Upload):

curl -X POST -F "text=Here's a file.&roomId=room123&userId=user456&userName=User&name=User" -F "file=@/path/to/document.pdf" http://localhost:3000/agent123/message

4. /agents/:agentIdOrName/hyperfi/v1 (POST - Hyperfi Interaction)

• Purpose: Handles interactions within a "Hyperfi" environment. It appears to be designed for a real-time, multi-user environment where agents can interact with the environment and other users.

• Method: POST

• URL: /agents/:agentIdOrName/hyperfi/v1 (e.g., /agents/agent123/hyperfi/v1 or /agents/AgentName/hyperfi/v1)

• Request:

  • application/json

• Body: JSON with the following fields:

  • roomId: (Optional) The room ID. Defaults to "hyperfi".
  • nearby: (Optional) An array of nearby entities (e.g., other users).
  • messages: (Optional) An array of messages from other users in the format "userId: message text".
  • availableEmotes: (Optional) An array of available emotes.

• Response: JSON object formatted for the Hyperfi environment based on the hyperfiHandlerTemplate. The JSON structure should conform to:

  { "lookAt": "{{nearby}}" or null, "emote": "{{emotes}}" or null, "say": "string" or null, "actions": (array of strings) or null }

• Logic:

  1. Retrieves the agent's runtime.
  2. Processes messages from other users, creating memory objects for each.
  3. Composes the context, including nearby entities and available emotes.
  4. Uses hyperfiHandlerTemplate to format the agent's response.

• curl Example:

curl -X POST -H "Content-Type: application/json" -d '{
  "roomId": "hyperfi_room",
  "nearby": ["user1", "user2"],
  "messages": ["user1: Hello!", "user2: How are you?"],
  "availableEmotes": ["smile", "wave"]
}' http://localhost:3000/agents/agent123/hyperfi/v1

Important Considerations

• Error Handling: The code includes basic error handling (e.g., 404 for agent not found), but more robust error handling might be needed.
• Agent Identification: The /:agentId/message and /agents/:agentIdOrName/hyperfi/v1 routes attempt to find the agent by ID first, and then fall back to searching by name (case-insensitive).
• File Paths: Be aware of the file paths used for uploads and generated images. These are currently hardcoded.
• Security: Ensure appropriate authentication and authorization mechanisms are in place, especially for the audio transcription endpoint, as it uses the OpenAI API key. The provided code doesn't appear to have any.
• Dependencies: The code relies on several dependencies, including express, body-parser, cors, multer, and openai. Make sure these are installed.
• Environment Variables: The code assumes you'll set environment variables like OPENAI_API_KEY to configure API keys.

This detailed breakdown should give you a solid understanding of how to interact with these API endpoints using curl. Remember to replace placeholder values (like agent123, /path/to/audio.mp3, etc.) with your actual values.

Citations:
[1] https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/1482581/53ac943f-0bf7-41e4-a876-78fbc74a3930/paste.txt
[2] https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/1482581/b3876afd-8276-43a9-a904-967ee8cff507/paste-2.txt

---

Answer from Perplexity: pplx.ai/share