[Upcoming] AI Teammates and Agent API Support

English Forum Developers & API Changelog
,
1

Summary

You can now discover agents in a workspace, look up individual agent records, and assign tasks directly to an AI Teammate through both the REST API and the Asana MCP server.

These changes are in Early Access and require an opt-in header (Asana-Enable: ai_teammate_actors).

This is the first in a phased rollout. Future phases will expand agent support to attribution fields (created_by, completed_by, etc.), membership and follower arrays, webhook event payloads, and write operations across more resource types.

Who Is Affected

This initial release is additive. No existing behavior changes with this announcement.

Developers who should take note now:

  • Integration and app builders who want to discover, reference, or assign AI Teammates programmatically.
  • Developers building assignee-picker or @-mention UIs who need to surface AI Teammates alongside human users in typeahead results.
  • Developers consuming actor-type fields (created_by, assignee, followers[], etc.) — a future phase will expand these to return Agent objects. You are not required to act now, but reviewing your parsing logic early is recommended.

What’s New

New: List agents in a workspace

GET /workspaces/{workspace_gid}/agents

Returns a compact list of all agents configured in the specified workspace, including AI Teammates and other agent subtypes. Use this endpoint to discover which agents are available before referencing or assigning them.

Also available via MCP: The get_workspace_agents tool on the Asana MCP server provides equivalent functionality for AI assistant workflows.

Response fields:

Field Type Description
gid string Globally unique identifier of the agent.
resource_type string Always "agent".
resource_subtype string Subtype of the agent: "asana_teammate"
name string Display name of the agent (e.g., "Developer Blog Writer").

Example response:

// GET /workspaces/67890/agents
{
  "data": [
    {
      "gid": "8888",
      "resource_type": "agent",
      "resource_subtype": "asana_teammate",
      "name": "Developer Blog Writer"
    },
    {
      "gid": "9999",
      "resource_type": "agent",
      "resource_subtype": "asana_teammate",
      "name": "Quality Assurance Bot"
    }
  ]
}

New: Get a single agent

GET /agents/{agent_gid}

Returns the full agent record for a specific agent. Fields returned vary based on resource_subtype.

Also available via MCP: The get_agent tool on the Asana MCP server provides equivalent functionality for AI assistant workflows.

Request parameters:

Parameter Type Required Description
agent_gid string Yes The GID of the agent to retrieve.
opt_fields string No Comma-separated list of fields to include in the response.

Response fields:

Field Type Optional Description
gid string No Globally unique identifier.
resource_type string No Always "agent".
resource_subtype string No "asana_teammate"
name string No Display name of the agent.
description string Yes A brief description of what the agent does.
behavior_guidance string Yes The AI Teammate’s behavior prompt. Only returned for resource_subtype: "asana_teammate".
workspace object No The workspace this agent is instantiated within.
created_by object Yes The user who configured this agent. Primarily populated for asana_teammate subtypes.
photo object Yes Avatar image URLs. Mirrors the structure of the user photo object. May be null.

Example response:

// GET /agents/8888
{
  "data": {
    "gid": "8888",
    "resource_type": "agent",
    "resource_subtype": "asana_teammate",
    "name": "Developer Blog Writer",
    "description": "Drafts and reviews developer-facing content.",
    "workspace": {
      "gid": "67890",
      "resource_type": "workspace",
      "name": "My Company Workspace"
    },
    "created_by": {
      "gid": "1111",
      "resource_type": "user",
      "name": "Prathmesh Patel"
    },
    "photo": null
  }
}

Updated: Typeahead now supports type=actor and type=agent

GET /workspaces/{workspace_gid}/typeahead?type=actor&query={query} 
GET /workspaces/{workspace_gid}/typeahead?type=agent&query={query}

The type parameter now accepts two new enum values for agent-aware queries:

  • actor: Returns a blended, relevance-ranked list of both user and agent objects. Use this for assignee pickers or @-mention inputs that should surface AI Teammates alongside human users.
  • agent: Returns only agent objects (currently AI Teammates). Use this when you want to query agents exclusively, without including human users in the results.

Also available via MCP: The search_objects tool on the Asana MCP server provides equivalent search functionality, including agents, for AI assistant workflows.

Response shape when type=actor:

Field Type Description
data[].gid string GID of the user or agent.
data[].resource_type string "user" or "agent".
data[].name string Display name.
data[].resource_subtype string Only present when resource_type is "agent". Defines the agent subtype (e.g., "asana_teammate").

Example response:

// GET /workspaces/67890/typeahead?type=actor&query=dev
{
  "data": [
    {
      "gid": "1111",
      "resource_type": "user",
      "name": "Devon Liang"
    },
    {
      "gid": "8888",
      "resource_type": "agent",
      "resource_subtype": "asana_teammate",
      "name": "Developer Blog Writer"
    }
  ]
}

Updated: Assign an agent to a task

PUT /tasks/{task_gid}
POST /tasks/{task_gid}

The assignee field now accepts Agent GIDs in addition to User GIDs. Pass an Agent’s GID to assign a task to an AI Teammate. Pass null to remove the assignee.

Updated field:

Field Type Description
assignee string GID of the user or agent to assign. Now accepts both User GIDs and Agent GIDs. Pass null to unassign.

Example — assigning a task to an AI Teammate:

// PUT /tasks/12345
{
  "data": {
    "assignee": "8888"
  }
}

What’s Coming Next

A future release will expand agent support across the API through a phased, opt-in deprecation process. That work includes:

  • Attribution fields: Fields like created_by, completed_by, author, and likes[].user on Task, Story, Project, Goal, Portfolio, StatusUpdate, and Time Tracking resources will be updated to return either a User or an Agent.
  • Membership and followers: We plan to expand membership and follower fields to support agents alongside users.
  • Team Membership: We plan to update the Team Membership object to support agents as members. This will involve a deprecation; details will be announced when finalized.
  • Webhook events: We plan to introduce agent attribution in webhook event payloads. The exact field names and schema will be shared in a follow-on announcement.

These changes will be introduced behind an opt-in header (Asana-Enable: ai_teammate_actors) and will follow Asana’s standard 6-month deprecation cycle before becoming the default.

If your application assumes attribution fields or membership arrays will always return a resource_type: "user", we recommend reviewing that logic.

Why We’re Making This Change

AI Teammates in Asana can be assigned work, join projects and teams, author comments, and collaborate alongside human users.

This release makes Agents queryable and assignable through the API, giving developers the foundation to build integrations that accurately reflect how work gets done in Asana.

Timeline

Phase Status Details
New agent endpoints + typeahead + task assignment Live GET /workspaces/{workspace_gid}/agents, GET /agents/{agent_gid}, type=actor typeahead, agent assignee on tasks
Polymorphic actor fields (attribution, membership, webhooks) Upcoming Announced separately with opt-in deprecation period

Early access / opt-in required: These endpoints are live but require opting in using the Asana-Enable: ai_teammate_actors header on each request. Review this guide for more information on Asana-Enable headers.

During early access, agent GIDs returned from these endpoints can only be used as input on the create task and update task endpoints, specifically to set the assignee field to an AI Teammate. Support for agent GIDs in other fields and endpoints will be added in subsequent releases.

Resources

Questions and Feedback

We’d love to hear from developers building agentic integrations that involve task assignment, project membership, or workflow automation, share your questions and feedback below.

4 Likes