Asana SWE Agent

An automated Software Engineering Agent that executes tasks assigned from Asana using OpenHands SDK.

Overview

This project integrates Asana with OpenHands SDK to create an autonomous SWE agent that:

1. Listens for Asana task assignments via webhooks
2. Spins up a Docker-sandboxed OpenHands agent runtime
3. Executes the task (e.g., "update dependencies", "fix bug #123")
4. Reports back to Asana with results and marks the task complete

Requirements

• Docker
• Asana account with API access
• LLM API key (Anthropic, OpenAI, etc.)
• Public URL for webhooks (or ngrok for development)

Quick Start

1. Configure Environment

cp .env.example .env
# Edit .env with your credentials

Required environment variables:

• ASANA_ACCESS_TOKEN - Your Asana Personal Access Token
• ASANA_AGENT_USER_GID - The GID of the "agent" user in Asana
• ASANA_WORKSPACE_GID - Your Asana workspace GID
• ASANA_PROJECT_GID - The GID of the Asana project to watch
• LLM_API_KEY - Your LLM provider API key
• LLM_MODEL - Model to use (e.g., anthropic/claude-sonnet-4-5-20250929)
• WEBHOOK_SECRET - Secret for webhook verification
• GITHUB_TOKEN - (Optional) For repository access

2. Run the Development Server

cd docker && docker compose up

3. Register Webhook

With the dev server running, register the Asana webhook:

docker exec -it asana-swe-agent-dev uv run python scripts/setup_webhooks.py

Production Deployment

docker run -d \
  --name asana-swe-agent \
  --restart unless-stopped \
  -p 8000:8000 \
  -p 25000-25029:25000-25029 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/asana-swe-workspaces:/tmp/asana-swe-workspaces \
  --env-file .env \
  <docker-image-path>:latest

Project Structure

asana-swe/
├── app/
│   ├── main.py              # FastAPI application
│   ├── config.py            # Configuration management
│   ├── asana/
│   │   ├── client.py        # Asana API client
│   │   ├── webhooks.py      # Webhook handlers
│   │   └── models.py        # Pydantic models
│   ├── agent/
│   │   ├── executor.py      # OpenHands agent executor
│   │   ├── task_parser.py   # Parse Asana tasks into agent prompts
│   │   └── reporter.py      # Report results back to Asana
│   └── utils/
│       └── logging.py       # Logging configuration
├── scripts/
│   ├── setup_webhooks.py    # Register Asana webhooks
│   └── find_asana_ids.py    # Helper to find Asana GIDs
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── .env.example
└── requirements.txt

Troubleshooting

Webhook not receiving events

• Ensure your server is publicly accessible
• Verify the webhook was registered successfully

Agent execution fails

• Check Docker is running and accessible
• Verify LLM API key is valid
• Check container logs: docker logs asana-swe-agent-dev

Task not processing

• Verify the task is assigned to the correct agent user
• Check that the task is in the configured project
• Review server logs for errors

License

MIT License