The agent object
Shape of the Agent resource as returned by the Macha API.
The Agent resource represents one AI copilot in your organization. Agents have instructions, a model, a set of tools (from connectors or custom HTTP endpoints), optional sub-agents to delegate to, and an active/inactive flag.
Object shape
{
"id": "agent_64f1c0ef2ec711ef6dc1dcf",
"handle": "ticketTriage",
"name": "Triage",
"description": "Routes incoming Zendesk tickets to the right downstream agent.",
"model": "gpt-5.4",
"is_active": true,
"color": "#000000",
"avatar": "🚦",
"tools_count": 2,
"sub_agents_count": 4,
"created_at": "2026-06-10T04:07:44.871Z",
"updated_at": "2026-06-17T07:29:29.408Z"
}Attributes
| Field | Type | Notes |
|---|---|---|
id | string | Prefixed identifier agent_<24 hex>. Treat as opaque. |
handle | string | camelCase alphanumeric (^[a-zA-Z][a-zA-Z0-9]*$). Used in @mentions. Unique within the org, case-insensitive. |
name | string | Display name shown in the dashboard. |
description | string | null | Short summary. Surfaced in the agent list. |
model | string | null | Model identifier, e.g. gpt-5.4, gpt-5-mini. null means org default. |
is_active | boolean | Whether the agent can be chatted with or fired by triggers. |
color | string | null | Hex color used for the agent avatar background. Default #6366f1. |
avatar | string | null | Emoji or URL. |
tools_count | integer | Number of tools assigned. Use the detail endpoint to enumerate. |
sub_agents_count | integer | Number of agents this one can hand off to. |
created_at | ISO 8601 | Always UTC. |
updated_at | ISO 8601 | Bumped on every PATCH. |
Why tools_count instead of tools[]?
List endpoints return the count, not the full array, because most agents have 5-30 tools and including them inflates list payloads by 10x without much benefit. The full tools array is documented but not yet returned by v1 read endpoints, you set it on create/update via the tools field but get back a count on read. If you need the full enumeration, request it (we'll add a ?expand=tools parameter).
Related
- List agents, pull every agent in the org
- Create an agent, full create request body
- Connectors, what tools can be assigned to an agent
© 2026 AGZ Technologies Private Limited