Xero Agent Toolkit

https://github.com/xeroapi/xero-agent-toolkit
Admin
A collection of examples demonstrating how to build AI agents that integrate with the Xero API using...
Tokens:7,492
Snippets:142
Trust Score:9.9
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Local Development Setup

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Steps to install dependencies, configure environment variables, and run the application locally.

```bash
pip install -r requirements.txt
```

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

```bash
python main.py
```

--------------------------------

### Install Dependencies

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/openai-agents/README.md

Install the necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Start the Application

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/openai-agents/README.md

Commands to launch the application in production or via ts-node.

```bash
npm start
# or
npx ts-node index.ts
```

--------------------------------

### Installation Commands

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Commands to install necessary Python dependencies and the Xero MCP server.

```bash
pip install -r requirements.txt
```

```bash
npm install -g @xeroapi/xero-mcp-server@latest
```

--------------------------------

### Install Xero MCP Server

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Command to install the required Xero MCP server.

```bash
npm install -g @xeroapi/xero-mcp-server@latest
```

--------------------------------

### Custom Workflow Example

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Demonstrates iterating through a list of tasks using the Xero MCP agent.

```python
async def custom_workflow():
    agent, client = await create_xero_mcp_agent()
    
    workflow_steps = [
        "List all customers",
        "Find overdue invoices",
        "Calculate total outstanding amount"
    ]
    
    for step in workflow_steps:
        response = await agent.ainvoke({
            "messages": [HumanMessage(content=step)]
        })
        # Process each step...
```

--------------------------------

### Verify Node.js and npm installation

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/README.md

Check the installed versions of Node.js and npm to ensure the Xero MCP Server requirements are met.

```bash
# Install Node.js from https://nodejs.org/
node --version
npm --version
```

--------------------------------

### Install Python dependencies

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/README.md

Install the necessary Python packages required for the integration.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install dependencies

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Run this command to resolve module not found errors by installing required project dependencies.

```bash
# Ensure you're in the correct directory and have installed dependencies
pip install -r requirements.txt
```

--------------------------------

### Create Customer Workflow

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Example natural language prompt for creating a new customer.

```text
"Create a new customer named 'Demo Corp' with email billing@democorp.com"
```

--------------------------------

### Natural Language Prompts for Customers and Invoices

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Examples of natural language commands for creating customers and invoices via the agent.

```python
# The agent can understand natural language requests:
"Create a new customer named 'Tech Solutions Inc' with email tech@solutions.com"

# Find customers to get contact IDs:
"Find customers with 'Tech' in their name and show me their contact IDs"

# Create an invoice using the contact ID:
"Create an invoice for contact ID 12345678-1234-1234-1234-123456789abc with line item: Consulting for $1000"
```

--------------------------------

### Install openai-agents dependency

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Use this command to resolve missing dependency errors.

```bash
pip install openai-agents
```

--------------------------------

### Natural Language Prompts for Invoice Management

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Examples of natural language commands for searching and filtering invoices.

```python
# Find invoices by status:
"Find all draft invoices"
"Find all invoices with status AUTHORISED"

# Search by date:
"Find invoices from the last 30 days"
```

--------------------------------

### Development Scripts for Xero Agent Toolkit

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Commands for managing the development lifecycle, including starting the application, building, and type checking.

```bash
# Start with development mode
npm start

# Build TypeScript
npm run build

# Type checking
npx tsc --noEmit
```

--------------------------------

### Common Error Messages

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Lists common error messages encountered during development and setup.

```text
Error: OPENAI_API_KEY not set in environment
```

```text
Error: Xero credentials not set in environment
```

```text
Error connecting to MCP server
```

--------------------------------

### Find Customer ID Workflow

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Example natural language prompt for retrieving contact IDs.

```text
"Find customers with 'Demo' in their name and show their contact IDs"
```

--------------------------------

### Querying Invoices via Natural Language

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Example interaction flow for retrieving specific invoice data based on user queries.

```text
User: "Show me all unpaid invoices from last month"

Agent: I'll retrieve your unpaid invoices from last month...

[Agent provides a formatted list of unpaid invoices with amounts and due dates]
```

--------------------------------

### Create Invoice Workflow

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Example natural language prompt for creating an invoice using a specific contact ID.

```text
"Create an invoice for contact ID [uuid-from-step-2] with line item: Consulting Services for $1500"
```

--------------------------------

### Creating an Invoice via Natural Language

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Example interaction flow for generating a new invoice using the agent's natural language processing capabilities.

```text
User: "Create an invoice for Acme Corp for 3 consulting hours at $150/hour"

Agent: I'll help you create that invoice. Let me first check for Acme Corp in your contacts and get the appropriate account codes...

[Agent proceeds to:]
1. Search for "Acme Corp" in contacts
2. Look up appropriate account codes for consulting services
3. Apply correct tax rates
4. Create the invoice with line items
5. Provide the invoice details and Xero link
```

--------------------------------

### Run the Xero Agent Demo

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Execute the main script to launch the available agent demonstrations.

```bash
python openai_agents.py
```

--------------------------------

### Initialize and Use XeroADKAgent

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/README.md

Demonstrates how to initialize the XeroADKAgent as an asynchronous context manager and process natural language queries.

```python
import asyncio
from google-adk import XeroADKAgent

async def example():
    async with XeroADKAgent() as agent:
        # Ask natural language questions
        result = await agent.process("Show me my recent invoices")
        print(result)
        
        # Create new contacts
        result = await agent.process("Create a new customer named ABC Corp")
        print(result)

# Run the example
asyncio.run(example())
```

--------------------------------

### Clone the Xero Agent Toolkit Repository

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/README.md

Initializes the local development environment by cloning the repository and entering the project directory.

```bash
git clone https://github.com/xeroapi/xero-agent-toolkit.git
cd xero-agent-toolkit
```

--------------------------------

### Configure environment variables

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/README.md

Set up the required Xero API credentials and Google AI configuration in a .env file.

```env
# Xero API Credentials
XERO_CLIENT_ID=your_xero_client_id
XERO_CLIENT_SECRET=your_xero_client_secret

# Google AI Configuration (choose one)
# Option 1: Google AI Studio
GOOGLE_API_KEY=your_google_ai_studio_api_key

# Option 2: Vertex AI
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your_project_id

# Optional: Specify model (defaults to gemini-2.0-flash)
DEFAULT_MODEL=gemini-2.0-flash
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Create a .env file with the required API keys and credentials for OpenAI and Xero.

```env
OPENAI_API_KEY=your_openai_api_key_here
XERO_CLIENT_ID=your_xero_client_id_here
XERO_CLIENT_SECRET=your_xero_client_secret_here
```

--------------------------------

### Creating a Basic Xero Agent

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Initializes a Xero MCP agent and invokes it to perform a query.

```python
from langchain.py import create_xero_mcp_agent
from langchain_core.messages import HumanMessage

async def example_usage():
    # Create the agent
    agent, client = await create_xero_mcp_agent()
    
    # Use the agent
    response = await agent.ainvoke({
        "messages": [HumanMessage(content="Find all draft invoices")]
    })
    
    # Process the response
    if response and "messages" in response:
        result = response["messages"][-1].content
        print(f"Agent response: {result}")
```

--------------------------------

### Deploy to Cloud Run

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Use the make command to deploy the agent to Google Cloud Run.

```bash
# Deploy with a single command
make deploy
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/openai-agents/README.md

Commands to initialize and edit the environment configuration file.

```bash
cp .env.template .env
```

```env
OPENAI_API_KEY=sk-your-openai-api-key-here
XERO_CLIENT_ID=your-xero-client-id-here
XERO_CLIENT_SECRET=your-xero-client-secret-here
```

--------------------------------

### Initialize Xero Agents

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Code snippets for creating different types of Xero agents using an MCP server instance.

```python
agent = create_basic_xero_agent(mcp_server)
# Has access to all Xero tools and operations
```

```python
agent = create_invoice_specialist_agent(mcp_server)
# Optimized for invoice creation and management
```

```python
agent = create_contact_manager_agent(mcp_server)
# Specialized in customer and supplier operations
```

--------------------------------

### Create a LangChain Agent with MCP Integration

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Initializes a MultiServerMCPClient to connect to the Xero MCP server and creates a LangGraph React agent with the discovered tools.

```typescript
// Agent creation with MCP integration
const client = new MultiServerMCPClient({
    xero: {
        transport: 'stdio',
        command: 'npx',
        args: ['-y', '@xeroapi/xero-mcp-server@latest'],
        env: { XERO_CLIENT_ID, XERO_CLIENT_SECRET }
    }
});

const tools = await client.getTools();
const agent = createReactAgent({ llm, tools });
```

--------------------------------

### Configure Google AI Service Credentials

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/SECURITY.md

Environment variables for Google AI Studio or Google Vertex AI authentication.

```bash
GOOGLE_API_KEY=your-google-ai-studio-api-key-here
```

```bash
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=TRUE
```

--------------------------------

### Run the Interactive Demo

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/README.md

Execute the interactive demo script to access various agent operations and chat interfaces.

```bash
python google-adk.py
```

--------------------------------

### Run Application Locally

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Execute the application locally to verify functionality before deployment.

```bash
# Run the application locally
python main.py

# Visit http://localhost:8000 to access the web interface
```

--------------------------------

### Deployment Commands

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Commands for deploying and removing the service from Google Cloud Run.

```bash
make deploy
```

```bash
make delete
```

--------------------------------

### Multi-Agent Coordination

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Demonstrates using separate agents for contact management and invoice creation.

```python
# Use Contact Manager to create customer
contact_agent = create_contact_manager_agent(mcp_server)
result = await Runner.run(contact_agent, "Create customer ABC Corp")

# Use Invoice Specialist to create invoice
invoice_agent = create_invoice_specialist_agent(mcp_server)
result = await Runner.run(invoice_agent, "Create invoice for ABC Corp")
```

--------------------------------

### create_basic_xero_agent(mcp_server)

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Creates a general-purpose Xero agent with access to all available Xero tools and operations.

```APIDOC
## create_basic_xero_agent

### Description
Creates a general-purpose Xero agent that has access to all Xero tools and operations.

### Parameters
- **mcp_server** (object) - Required - The MCP server instance to connect the agent to.

### Returns
- **agent** (object) - An instance of the basic Xero agent.
```

--------------------------------

### Configure Xero API Credentials

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/SECURITY.md

Required environment variables for Xero API authentication.

```bash
XERO_CLIENT_ID=your-xero-client-id-here
XERO_CLIENT_SECRET=your-xero-client-secret-here
```

--------------------------------

### Create a customer and invoice operations

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Natural language prompts for customer and invoice management.

```typescript
// Natural language examples the agent can understand:
"Create a new customer called 'Demo Corp' with email demo@demo.com"
"Find all active customers"
"Create an invoice for Demo Corp for 10 hours of consulting at $150 per hour"
```

--------------------------------

### Project Structure Overview

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Visual representation of the directory layout for the TypeScript LangChain integration.

```text
typescript/langchain/
├── index.ts          # Main application file
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
└── README.md         # This file
```

--------------------------------

### Project Structure

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Overview of the file and directory structure for the invoicing agent project.

```text
cloud-run-invoicing-agent/
├── main.py                 # FastAPI application entry point
├── Dockerfile             # Container configuration
├── requirements.txt       # Python dependencies
├── makefile              # Deployment commands
├── .env                  # Environment variables (create this)
└── xero_invoicing_agent/
    ├── __init__.py
    ├── agent.py          # Main agent configuration
    └── config.py         # Application settings
```

--------------------------------

### Configure OpenAI API Key

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/SECURITY.md

Environment variable for OpenAI service authentication.

```bash
OPENAI_API_KEY=sk-your-openai-api-key-here
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/README.md

Set the environment variable to enable verbose logging for troubleshooting.

```env
GOOGLE_GENAI_LOG_LEVEL=DEBUG
```

--------------------------------

### Development and Type Checking

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/openai-agents/README.md

Commands for development workflows including hot-reloading and static type analysis.

```bash
npm run dev
```

```bash
npm run type-check
```

--------------------------------

### Authenticate with gcloud

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Use this command to authenticate the gcloud CLI if deployment fails due to authorization issues.

```bash
gcloud auth login
```

--------------------------------

### Read Cloud Run logs

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Use these commands to inspect service logs for debugging deployment or agent responsiveness issues.

```bash
gcloud run services logs read xero-invoicing-agent
```

```bash
gcloud run services logs read xero-invoicing-agent \
  --region=us-central1 \
  --project=your-project-id \
  --limit=50
```

--------------------------------

### Development Workflow Security Commands

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/SECURITY.md

Standard commands for managing environment files and reviewing git changes before committing.

```bash
# ✅ GOOD: Copy example and fill with real values
cp .env.example .env
# Edit .env with your credentials

# ✅ GOOD: Check what you're committing
git status
git diff --cached

# ❌ BAD: Never do this
git add .env
```

--------------------------------

### Service Management Commands

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/google-adk/cloud-run-invoicing-agent/README.md

Commands for viewing logs and updating environment variables for the deployed service.

```bash
gcloud run services logs read xero-invoicing-agent \
  --region=us-central1 \
  --project=your-project-id
```

```bash
gcloud run services update xero-invoicing-agent \
  --region=us-central1 \
  --project=your-project-id \
  --set-env-vars="NEW_VAR=value"
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Command to enable debug mode via environment variables.

```bash
export DEBUG=1
```

--------------------------------

### create_contact_manager_agent(mcp_server)

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Creates an agent specialized in customer and supplier contact operations.

```APIDOC
## create_contact_manager_agent

### Description
Creates an agent specialized in customer and supplier operations.

### Parameters
- **mcp_server** (object) - Required - The MCP server instance to connect the agent to.

### Returns
- **agent** (object) - An instance of the contact manager agent.
```

--------------------------------

### create_invoice_specialist_agent(mcp_server)

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/openai/README.md

Creates an agent optimized specifically for invoice creation and management tasks.

```APIDOC
## create_invoice_specialist_agent

### Description
Creates an agent optimized for invoice creation and management.

### Parameters
- **mcp_server** (object) - Required - The MCP server instance to connect the agent to.

### Returns
- **agent** (object) - An instance of the invoice specialist agent.
```

--------------------------------

### Invoice management operations

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Natural language prompts for querying and analyzing invoices.

```typescript
"Find all draft invoices"
"Show me recent invoices that are overdue"
"Analyze invoice payment patterns"
```

--------------------------------

### Organization analysis operations

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/typescript/langchain/README.md

Natural language prompts for organization-level data analysis.

```typescript
"Get organization details and provide insights"
"Summarize my contact database"
"Analyze recent invoice trends"
```

--------------------------------

### Handle Agent Execution Errors

Source: https://github.com/xeroapi/xero-agent-toolkit/blob/main/python/langchain/README.md

Use this pattern to wrap agent invocations and catch exceptions during execution.

```python
try:
    response = await agent.ainvoke({"messages": [HumanMessage(content=query)]})
    # Process response...
except Exception as e:
    print(f"❌ Error: {e}")
    # Handle error appropriately...
```
Tokens:
Raw