Getting started with Avalara Avi Agent

View as markdown

Learn how to set up and connect to Avalara Avi Agent for AI-powered tax compliance integration.

How to access Avalara Avi Agent

You need an Avalara account before you can start integrating with Avalara Avi Agent.

Avalara Avi Agent capabilities depend on the products that you are subscribed to.

Currently supported products are:

Avatax

If you are new to Avalara, you can start your free trial today.

Returns
E-invoicing and Live Reporting

If you are not subscribed to any of the above products, Avalara Avi Agent capabilities would be limited to knowledge center documentation..

Usage Instructions

Once you get the username and password the next step is to generate the Avalara Identity token. Below is the process to generate the token.

Authentication

To interact with Avalara Avi Agent you will need to acquire access tokens. This token identifies your account to Avalara Avi Agent and allows it to respond to questions related to your specific account. Below we describe the common way to register a client with Avalara Identity and obtain access tokens.

1. Obtaining Access - Dynamic Client Registration

You can refer to the avi_dcr_flow.py script for an implementation that registers a client and does the client authentication flow for you.

A2A Client Setup - Using Dynamic Client Registration

Download the script avi_dcr_flow.py
The default product in the script is avatax, you can leave it unchanged if you have avatax. The same token will work against all your products, the service will manage entitlements internally.
- If you don't have Avatax, these are the following values you can change to:
  - elr - E-Invoicing and Live Reporting
  - ecm - Exemption Certificate Management

Install required libraries:

#> uv init
#> uv add fastmcp a2a-sdk
Activate your virtual env
#> python avi_dcr_flow.py

See RFC 7591 to learn more about how Authentication is done in the script.
Learn more about A2A and A2A clients.

2. Manually Register Clients and Get Access Token

These are the manual steps in case you need to implement DCR in a different language or stack other than the Python script mentioned above.

Please refer to instructions in the OAuth DCR PKCE README.

Test the Avalara Avi Agent

Once you obtain the token from any of the steps above, you can test the agent.

A2A Server Details:

Use any of the A2A server URLs below:

Option 1: Once you get the token by using above steps you can test the agent using the curl command below:

curl -X POST "https://avi.avalara.com/a2a/avi" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test",
    "method": "message/stream",
    "params": {
      "message": {
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "what agents do you have?"
          }
        ],
        "messageId": "some-uuid"
      }
    }
  }'

Option 2: Users who want to communicate within their A2A client

Download the Agent Card

Use any of the agent card URLs below:

Agent 2 Agent (A2A) Client:

This is standard A2A client, an A2A client will take in the agent card and start working from there. In each request the A2A client sends, it needs to pass the JWT token in the header.

Note: Token generation & refresh need to be handled by the system that is implementing the A2A client.

Troubleshooting common issues

Error: 401 - Authentication required now

What it means: Your request did not include a valid OAuth token.

How to fix:

Re-authenticate and generate a new token
Ensure all required scopes are granted
Verify the Authorization header is correctly formatted