opero-odoo-agent-tools 0.1.0

Framework-neutral Odoo connector tools for AI agent runtimes

Odoo Agent Tools SDK

A small, framework-neutral connector layer for exposing Odoo operations as safe, predictable tools for AI agents.

The goal is to keep agent developers away from raw Odoo RPC details. They should call typed tool functions with JSON-compatible arguments and receive consistent results that are easy to pass back into an agent runtime.

Design Principles

1. Agent-safe by default: validate inputs, bound result sizes, and avoid destructive operations unless the tool explicitly opts in.
2. Framework-neutral: expose plain Python callables and JSON schemas so the tools can be adapted to OpenAI, LangChain, Semantic Kernel, AutoGen, or a custom runner.
3. Odoo-native underneath: preserve Odoo concepts such as models, domains, fields, and record IDs without leaking XML-RPC ceremony into agent code.
4. Predictable outputs: every tool returns a ToolResult with ok, data, and error fields.
5. Extensible connector standards: new connectors should follow the same tool definition and error contract used here.

Quick Start

Install the package:

pip install opero-odoo-agent-tools

from odoo_agent_tools import OdooClient, OdooConfig, build_odoo_business_tools

config = OdooConfig(
    url="https://example.odoo.com",
    database="my-db",
    username="[e-mail]",
    password="api-key-or-password",
)

client = OdooClient(config)
tools = build_odoo_business_tools(client)

result = tools["odoo_find_customer"].call({"query": "Acme", "limit": 10})

print(result.to_dict())

The low-level model tools are also available through build_odoo_tools.

Included Tools

Low-Level Odoo Tools

• odoo_search_read: search and read records from an Odoo model.
• odoo_read: read records by ID.
• odoo_create: create a record, opt-in write tool.
• odoo_write: update records, opt-in write tool.
• odoo_unlink: delete records, opt-in destructive tool.
• odoo_call_method: call an allowlisted model method.

Business Tools

• odoo_find_customer: find contacts by name, email, or phone.
• odoo_create_crm_lead: create a CRM lead or opportunity.
• odoo_get_invoice_status: get invoice status and payment details.
• odoo_find_product: find products by name, SKU, or barcode.
• odoo_create_project_task: create a project task.
• odoo_get_sale_order_status: get sales order state, invoice status, and delivery status.

Connector Standard

Every connector tool should provide:

• A stable name using the {system}_{verb} pattern.
• A short description written for an agent planner.
• A JSON Schema object for arguments.
• A plain Python call(arguments: dict) -> ToolResult method.
• A conservative default limit for list operations.
• Explicit is_write and is_destructive flags.
• Structured errors using ToolError.

See docs/CONNECTOR_STANDARD.md for the full standard.

Development

$env:PYTHONPATH='src'
python -m unittest discover -s tests

Testing Against Odoo

Create a .env file from .env.example and fill in your Odoo details:

Copy-Item .env.example .env

Then edit .env:

ODOO_URL=https://your-company.odoo.com
ODOO_DATABASE=your-database
ODOO_USERNAME=[e-mail]
ODOO_PASSWORD=your-api-key-or-password

Run the smoke test:

$env:PYTHONPATH='src'
python examples/smoke_test_odoo.py

The smoke test calls odoo_search_read against res.partner and prints a standard ToolResult. Existing environment variables override values loaded from .env.

You can also test the higher-level business tools:

$env:PYTHONPATH='src'
python examples/smoke_test_business_tools.py

The package uses only Python standard library modules at runtime.