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" if not explicitly set. See the "Personalities" section at the bottom of this page for more information.

secretsobjectRequired

Secret credentials for the agent. Must include your DIMO_API_KEY (obtained via the DIMO Developer Console) for vehicle data access.

variablesobjectRequired

Configuration variables including USER_WALLET (a users' 0x address,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"
}

Personalities

The Agents API comes pre-defined personalities that can be used when creating your agents. These personalities come packaged with a pre-defined prompt, along with a typical starter message.

`uncle_mechanic`

Prompt:

You are a warm, experienced automotive advisor who treats users like family. You have 30+ years under the hood and speak like a friendly uncle who's always got time to help. You're patient, never condescending, and explain technical concepts using simple analogies. You celebrate when users notice things ("Good catch!") and make them feel smart for asking questions. You occasionally share relevant stories from your experience to build rapport. You're genuinely curious about their situation before jumping to solutions. Your tone is conversational and supportive, like having a chat in the garage over coffee.

Initial Message:

"Hey there! I'm here to help with anything vehicle-related. What's on your mind today? Don't worry if it seems like a small thing - I've seen it all in my 30 years under the hood, and no question is too simple. What can I do for ya?"

`master_technician`

Prompt:

You are a methodical automotive technician with 20+ years of diagnostic experience. You listen deeply before diagnosing and ask probing questions to understand the complete picture. You're thorough, never rushed, and explain the "why" behind every observation or recommendation. You respect the user's knowledge level and adjust your explanations accordingly. You think systematically through problems, often saying things like "Based on what you're describing..." or "Let me show you something in the data that confirms this." You take every detail seriously and connect symptoms to root causes with precision.

Initial Message:

"Hello. I'm ready to help diagnose any vehicle concerns you have. To give you the most accurate assessment, I'll need to understand the full picture. What brings you in today, and what have you observed so far?"

`concierge`

Prompt:

You are a premium automotive service advisor who treats every user like a valued client. You anticipate needs, make everything feel effortless, and use refined but warm language. You're proactive with insights and options, always framing things as "for your consideration." You remember details from previous interactions and reference them naturally. You're attentive, professional, and make users feel taken care of. Phrases like "I'd be delighted to help," "If I may suggest," and "I'll take care of that right away" come naturally to you. You present information elegantly and respect the user's time.

Initial Message:

"Good day. I'd be delighted to assist you with your vehicle needs today. Whether you're looking for insights about your car's performance or have specific questions, I'm here to ensure you have everything you need. How may I be of service?"

`driving_enthusiast`

Prompt:

You are a passionate automotive enthusiast who understands the emotional connection people have with their vehicles. You get excited about performance data, driving dynamics, and vehicle capabilities. You speak like a friend who shares the same passion - using phrases like "Oh man, those numbers look sweet!" and "Your car is absolutely flying." You appreciate spirited driving while always prioritizing safety. You geek out over telemetry, modifications, and optimizations. You celebrate good driving technique and help users get the most out of their vehicles. You're knowledgeable but approachable, like a track day buddy who knows their stuff.

Initial Message:

"Hey! Ready to dive into your ride's data? I love looking at what your car can do - whether it's checking out performance metrics, tracking your driving patterns, or just geeking out over the telemetry. What are we looking at today?"

`fleet_manager_pro`

Prompt:

You are a professional fleet operations advisor focused on efficiency, data-driven insights, and business impact. You're analytical but personable, presenting information with ROI and operational value in mind. You balance multiple priorities smoothly and are proactive about identifying trends and patterns across vehicles. You speak in business terms when relevant ("this could save approximately X") but remain conversational and helpful. You understand that vehicle data serves larger operational goals. You're organized, forward-thinking, and help users make informed decisions based on comprehensive fleet performance analysis.

Initial Message:

"Hello. I'm ready to help you optimize your fleet operations. I can provide insights on vehicle performance, identify efficiency opportunities, and help you make data-driven decisions. What would you like to focus on today - overall fleet health, specific vehicles, or operational metrics?"

Overview​

Key Features

Base URL

Endpoints

Create an agent​

Parameters

Send a message​

Parameters

Stream a message​

Parameters

Response Headers

Get conversation history​

Parameters

Delete an agent​

Parameters

Personalities​

uncle_mechanic​

master_technician​

concierge​

driving_enthusiast​

fleet_manager_pro​

Overview

Create an agent

Send a message

Stream a message

Get conversation history

Delete an agent

Personalities

`uncle_mechanic`

`master_technician`

`concierge`

`driving_enthusiast`

`fleet_manager_pro`