Skip to main content

Agents API ⚠️ Alpha Software

IMPORTANT

Be aware, the Agents API is in active development and is highly subject to change. We recommend developers use this page as a general guide to understanding the overarching concepts of the API, which will be publicly available in beta soon.

Please build at your own risk.

Create, chat with, and stream messages from intelligent vehicle agents.

Overview

The DIMO Agents API enables developers to create intelligent AI agents that can interact with vehicle data through natural language. These agents can query vehicle information, real-time telemetry, perform web searches to answer questions about vehicles and nearby services, and more.

Key Features

  • Create AI agents with vehicle-specific access
  • Query vehicle identity data (make, model, year, owner)
  • Access real-time telemetry data (speed, fuel, location, battery)
  • Perform location-based web searches ("Find replacement parts near me")
  • Stream responses in real-time using Server-Sent Events
  • Maintain conversation history and context

Base URL

https://agents.dimo.zone

Endpoints

Create an agent

Creates a new conversational AI agent with the specified configuration. The agent can access vehicle data through the DIMO API and interact with users via natural language.

Parameters

typestringRequired
The type of agent to create (e.g., "driver_agent_v1").
personalitystringOptional
Personality preset for the agent. Defaults to "uncle_mechanic".
secretsobjectRequired
Secret credentials for the agent. Must include DIMO_API_KEY for vehicle data access.
variablesobjectRequired
Configuration variables including USER_WALLET (required) and optionally VEHICLE_IDS (JSON array string of vehicle token IDs).
POST/agents
const agent = await dimo.agents.createAgent({
    type: "driver_agent_v1",
    personality: "uncle_mechanic",
    secrets: {
      DIMO_API_KEY: "<YOUR_API_KEY>"
    },
    variables: {
      USER_WALLET: "0x1234567890abcdef1234567890abcdef12345678",
      VEHICLE_IDS: "[872, 1234]"
    }
})
Response
{
  "agentId": "agent-abc123def456",
  "type": "driver_agent_v1",
  "personality": "uncle_mechanic",
  "variables": {
    "USER_WALLET": "0x1234567890abcdef1234567890abcdef12345678",
    "VEHICLE_IDS": "[872, 1234]"
  },
  "createdAt": "2025-12-06T10:30:00Z"
}

Send a message

Sends a message to an agent and receives the complete response synchronously. The agent will automatically delegate to specialized subagents to query vehicle identity, telemetry, or perform web searches as needed.

Parameters

agentIdstringRequired
The unique identifier of the agent. This is provided in the URL path.
messagestringRequired
The message or question to send to the agent.
vehicleIdsarrayOptional
Optional override to limit vehicle access for this specific message.
userstringOptional
Optional override for the user context of this message.
POST/agents/:agentId/message
const response = await dimo.agents.sendMessage({
agentId: "agent-abc123def456",
message: "What's the make and model of my vehicle?"
})
Response
{
  "agentId": "agent-abc123def456",
  "message": "What's the make and model of my vehicle?",
  "response": "Your vehicle is a 2020 Tesla Model 3.",
  "vehiclesQueried": [872],
  "timestamp": "2025-12-06T10:35:00Z"
}

Stream a message

Sends a message and receives a real-time token-by-token streaming response using Server-Sent Events (SSE). This provides a better user experience with immediate feedback as the agent generates its response.

Parameters

agentIdstringRequired
The unique identifier of the agent. This is provided in the URL path.
messagestringRequired
The message or question to send to the agent.
vehicleIdsarrayOptional
Optional override to limit vehicle access for this specific message.
userstringOptional
Optional override for the user context of this message.

Response Headers

  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive
POST/agents/:agentId/stream
const stream = dimo.agents.streamMessage({
agentId: "agent-abc123def456",
message: "What's my current speed?"
});


stream.on('token', (chunk) => {
console.log(chunk.content);
});


stream.on('done', (metadata) => {
console.log('Vehicles queried:', metadata.vehiclesQueried);
});


stream.on('error', (error) => {
console.error('Stream error:', error);
});
Response
data: {"content": "Your"}
data: {"content": " vehicle"}
data: {"content": " is"}
data: {"content": " currently"}
data: {"content": " traveling"}
data: {"content": " at"}
data: {"content": " 65"}
data: {"content": " mph"}
data: {"content": "."}
data: {"done": true, "agentId": "agent-abc123def456", "vehiclesQueried": [872]}

Get conversation history

Retrieves the complete conversation history for an agent, including all messages exchanged between the user and the agent.

Parameters

agentIdstringRequired
The unique identifier of the agent. This is provided in the URL path.
limitintegerOptional
Maximum number of messages to return. Default: 100.
GET/agents/:agentId/history?limit=50
const history = await dimo.agents.getHistory({
agentId: "agent-abc123def456",
limit: 50
})
Response
{
  "agentId": "agent-abc123def456",
  "messages": [
    {
      "role": "user",
      "content": "What's the make and model?",
      "timestamp": "2025-12-06T10:35:00Z"
    },
    {
      "role": "agent",
      "content": "Your vehicle is a 2020 Tesla Model 3.",
      "timestamp": "2025-12-06T10:35:05Z"
    },
    {
      "role": "user",
      "content": "What's my current speed?",
      "timestamp": "2025-12-06T10:36:00Z"
    },
    {
      "role": "agent",
      "content": "Your vehicle is currently traveling at 65 mph.",
      "timestamp": "2025-12-06T10:36:03Z"
    }
  ],
  "total": 4
}

Delete an agent

Permanently deletes an agent and all associated resources, including conversation history and subagents.

Parameters

agentIdstringRequired
The unique identifier of the agent to delete. This is provided in the URL path.
DELETE/agents/:agentId
await dimo.agents.deleteAgent({
agentId: "agent-abc123def456"
})
Response
{
  "message": "Agent deleted successfully"
}