Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Asana integration enables your agents to discover, search, and manage work across an Asana workspace — tasks (and subtasks), projects, sections, and comments. Agents can read your custom fields, file new work in the right project and section, comment on existing tasks, and manage relationships like dependencies, followers, and tags.

​
Features

  • Schema Discovery: Discover workspaces, teams, projects, users, tags, sections in a project, and the custom fields applied to a project — agents look up gids at runtime instead of hard-coding them
  • Powerful Task Search: Filter tasks across an entire workspace by text, assignee, project, section, tag, follower, completion, due/start/completed/created/modified date ranges, blocked/blocking state, and any custom field value (8 operator types)
  • Full CRUD on Tasks, Projects, Sections, and Comments: One manage_records tool with an action enum covering create, read, update, delete, and duplicate
  • Task Relationships in the Same Tool: Add/remove tasks from projects (with section placement), move between sections, manage tags, followers, dependencies/dependents, and parent (subtask) relationships — all as actions on asana_manage_records so agents don’t need to juggle multiple tools
  • Custom Field Aware: Read and write task custom fields by gid, including enum, multi_enum, number, date, and text types

​
Prerequisites

  • Active Asana account with access to the workspace you want to connect
  • A Personal Access Token (PAT) — or, for org-wide access, a Service Account token (Asana Enterprise only)

​
Setup Guide

1

Create a Personal Access Token

In Asana, navigate to My Settings > Apps > Manage Developer Apps (or open https://app.asana.com/0/my-apps directly).Click Create new token, give it a descriptive name (e.g., “Aster Agents”), agree to the API terms, and copy the generated token.The token has the same permissions as the user who created it — so the agent will be able to do whatever that user can do in Asana, and nothing more.
For org-wide access: Asana Enterprise customers can create a Service Account instead. Service Account tokens are not tied to an individual user, so they continue working when teammates leave the organization.
2

Enable Asana Integration

In Aster Agents, navigate to Control Hub > Integrations and locate the Asana card. Click Connect to begin setup.
3

Configure Connection

Provide your Asana access token:
  • Personal Access Token: The token from Step 1
4

Add Tools to Your Agent

Edit your agent and enable the Asana tools you need:
  • Get Asana Schema — discover workspaces, teams, projects, sections, custom fields
  • Search Asana — filter tasks across a workspace
  • Manage Asana Records — CRUD on tasks/projects/sections/comments + manage task relationships
We recommend enabling all three — agents call Get Schema first to learn your workspace’s structure (gids, custom field names) before searching or writing.

​
Available Tools

​
Get Asana Schema

Discover the gids and structure your agent needs at runtime:
  • workspaces — top-level orgs the token can access
  • teams — within a workspace
  • projects — within a workspace, optionally filtered by team
  • users — workspace members
  • tags — workspace tags
  • sections — within a project
  • custom_fields — fields applied to a project, including enum option gids
  • task_fields — static reference of standard task fields you can read/write (helpful for agents to know what’s settable on create/update)

​
Search Asana

Search tasks across a workspace using Asana’s tasks/search endpoint:
  • Free-text search across name and notes
  • Membership filters: assignee any/not, projects any/not/all, sections any/not, tags any/not, followers any/not
  • Engagement filters: commentedOnByAny, likedByAny
  • State filters: completed, isSubtask, hasAttachment, isBlocked, isBlocking
  • Date filters: due, start, completed, modified, and created — with before, after, and is_set variants where applicable
  • Custom field filters: 8 operators (is_set, value, starts_with, contains, greater_than, less_than, between, any, not) on any custom field gid
  • Sort: by due_date, created_at, modified_at, completed_at, or likes
  • Field selection via fields (Asana opt_fields)
  • rawParams escape hatch for any Asana search parameter not covered first-class
Pagination caveat: Asana’s search endpoint does not paginate — it returns up to 100 results in a single call with no cursor. To retrieve more, narrow your filters. The tool returns hasMore: false to make this explicit.

​
Manage Asana Records

One tool, two action families. CRUD actions (work on task, subtask, project, section, comment):
  • get — fetch a record by gid with optional field selection
  • create — create a new record (custom fields supplied as {custom_fields: {<gid>: <value>}} for tasks)
  • update — modify fields on an existing record
  • delete — remove a record
  • duplicate — duplicate a task or project (returns an Asana job)
Task relationship actions (only valid for resource='task' or 'subtask'):
  • list_projects / add_project / remove_project — manage which projects a task belongs to; add_project accepts a sectionGid to land it directly in a section
  • move_to_section — reposition within a project
  • list_tags / add_tag / remove_tag — manage tags
  • list_followers / add_followers / remove_followers — manage followers
  • list_dependencies / add_dependencies / remove_dependencies — manage tasks this one depends on
  • list_dependents / add_dependents / remove_dependents — manage tasks that depend on this one
  • list_subtasks — list direct subtasks
  • set_parent — make this task a subtask of another (or detach with newParentGid: null)

​
Security Considerations

  • Use a dedicated PAT per integration — easier to rotate and revoke without affecting other tools
  • Token = user permissions — a PAT has exactly the access the creating user has. Create the PAT under a service account or a user whose access matches what the agent should be able to do
  • Rotate periodically — generate a fresh PAT and update it under Control Hub > Integrations; the old one keeps working until you delete it in Asana
  • Audit in Asana — recent activity for a PAT is visible under My Settings > Apps

​
Troubleshooting

  • Verify the PAT was copied completely (Asana tokens have multiple : and / characters — easy to truncate)
  • Confirm the user who issued the token still has access to the workspace
  • Reconnect under Control Hub > Integrations > Asana with a fresh token if the previous one was deleted in Asana
  • PATs respect Asana’s per-project privacy. If a project is private and the issuing user isn’t a member, the agent can’t see or modify its tasks
  • Add the user (or service account) as a project member in Asana
  • Asana’s standard rate limit is 1500 requests per minute per token; search has its own lower limit
  • The tool surfaces the retry-after duration on 429 responses
  • For high-volume reads, prefer asana_get_schema (lists) over many individual get calls
  • Asana’s search endpoint returns at most 100 results in a single call with no pagination cursor — narrow your filters to drill down
  • Search is eventually consistent — recently created/modified tasks may not appear immediately
  • Custom field filters require the field’s gid (not its name); look it up via asana_get_schema(resource=custom_fields, projectGid=...)
  • Custom field values must be sent under data.custom_fields keyed by the field gid (e.g. {"1234567890": "Approved"})
  • Enum custom fields take an enum option gid, not the option’s display name
  • Multi-enum custom fields take an array of enum option gids
  • Discover the gids and option gids with asana_get_schema(resource=custom_fields, projectGid=...)