kintone is in a remarkable number of Japanese enterprises. Cybozu's no-code/low-code database platform has been adopted by businesses ranging from 10-person regional distributors to divisions inside large manufacturing groups, because it solved a real problem: custom business application development without requiring a dedicated engineering team. The result is that many Japanese companies have accumulated years of operational data inside kintone — customer records, project tracking, inventory logs, approval workflows — and this data is exactly the kind of knowledge an internal AI agent should be able to access.
We have completed more than ten kintone-to-agent integrations. This post documents what we actually found: the mechanics that work cleanly, the failure modes we hit, and the architectural decisions that separate a fragile demo connection from something that holds up under daily enterprise use.
The kintone API: What It Gives You and What It Does Not
kintone exposes a REST API that allows read access to app records, form field definitions, and file attachments. Authentication is token-based — each kintone app has its own API token with configurable permissions. For agent integrations, this is your primary access path.
What the API gives you cleanly: structured record retrieval with field filtering, query syntax for conditional fetches, attachment download via file key, and a space-level app list for discovery. What it does not give you out of the box: full-text search across multiple apps simultaneously, incremental change detection (webhooks exist but cover limited event types), and any awareness of cross-app relationships that were defined implicitly through form field naming rather than explicit lookup fields.
The last point causes the most friction. In a typical kintone environment built organically over several years, the "customer ID" in the Sales App is a text field that was typed manually by sales reps, while the "client code" in the Contract App is a lookup field pointing to a separate Master App. These may or may not be the same identifier. When your agent needs to answer a question like "what is the contract status for customer Nakamura Trading?", it needs to resolve this cross-app relationship — and the API alone will not tell you which fields are semantically equivalent.
What Breaks in the First Integration Attempt
Our first kintone integration, back in the earlier deployments, went into a data model assumption problem immediately. The target company had 23 kintone apps. We indexed all of them. The agent could retrieve records, but its answers to natural-language questions were inconsistent, because the same business concept appeared under four different field names across different apps, and our retrieval layer had no way to know they were related.
The naive approach — "dump all records into a vector index and let the LLM figure it out" — technically works for simple factual retrieval within a single app. It breaks down for anything that requires joining information across apps, because the embedding model has no knowledge of the organizational intent behind how kintone apps were named and structured.
The practical fix was to spend the first week of every new integration doing explicit data model mapping before writing a single retrieval query. This means sitting with the kintone administrator and walking through the app list, identifying: which apps are operational (actively updated), which are archival (rarely touched), which fields carry semantic identifiers versus free-text labels, and where the implicit cross-app relationships live. This mapping becomes the schema layer that guides both the retrieval logic and the context provided to the LLM.
Token Management and Rate Limiting in Production
kintone's API has rate limits that are generous enough for low-frequency use but become a design constraint when an agent is handling dozens of concurrent queries against a large record set. The default rate limit is 1 request per second per token per domain, with higher limits available on enterprise contracts. In a production deployment where 50 employees might be querying the agent simultaneously, naive per-query API calls will hit this ceiling.
Our solution is a caching layer between the Askhub retrieval engine and the kintone API. For record types that change infrequently — product catalogs, policy documents, master data — we maintain a refreshed local index that is updated on a schedule rather than queried live. For record types that change frequently — current project status, approval queue, recent customer interactions — we use live queries with appropriate batching and a small in-memory cache with a short TTL.
One practical nuance: kintone webhooks for real-time change notification work reliably for record additions but have historically been less consistent for field-level updates in apps with complex conditional fields. In our more recent implementations, we supplement webhooks with a scheduled full-refresh job that runs nightly for the most critical apps, so stale data is never more than 24 hours old even if a webhook delivery failed.
Handling Attachments and Rich Text Fields
Many kintone apps contain file attachments — typically PDF documents (product specs, contracts, compliance certificates) and Word files (meeting minutes, policy drafts). These are not accessible via standard record queries; they require a separate API call to download the binary file using the file key stored in the attachment field.
For agent integrations, attachment content is often the most valuable knowledge — the actual text of a manual or a policy document. Extracting this text requires a PDF parsing step after download. We process attachments at index time rather than at query time: during the scheduled refresh, new or updated attachment files are downloaded, parsed, chunked, and added to the vector store with metadata linking them back to the originating kintone record and app.
The failure mode here is large attachments. A company that stores 200-page product catalogs as single PDFs in a kintone app will create chunking challenges that a standard 512-token chunk size does not handle well. For these cases, we use a two-pass parsing strategy: a first pass to identify logical document sections (typically via heading detection), and a second pass to chunk within sections. This preserves context coherence in the chunks and meaningfully improves retrieval relevance for queries that reference specific sections of a long document.
Permission Inheritance and the Compliance Question
kintone has its own user and group permission model. Individual apps can be restricted to specific groups, and specific record-level viewing permissions can be configured. When an AI agent queries kintone on behalf of an end user, the question arises: should the agent respect the kintone permission boundaries, or does it query with a service account that has full read access?
This is not a technical question — it is a compliance and governance question, and the answer depends on what the data contains and who the agent users are. We are not saying service account access is always wrong; we are saying that for any kintone app containing personal information, confidential customer records, or HR data, querying with a broad service account and returning results to any authenticated user circumvents the access controls that the organization deliberately put in place. In those cases, the agent should either query using per-user credentials (which kintone supports via OAuth 2.0 for custom apps) or implement its own permission filter that mirrors the kintone access model.
In practice, most of our implementations use a tiered model: the majority of operational apps (non-sensitive data) are indexed under a service account token, while specific apps containing personal or confidential data are scoped to authenticated user queries only. The business stakeholder designates the tier at integration time, and that decision is documented in the project configuration record.
What Stability in Production Actually Looks Like
A kintone integration is stable in production when four things are true: the data model mapping is documented and updated when apps change, the caching and refresh logic handles the rate limit ceiling under peak concurrency, attachment parsing covers the document types actually used in the target apps, and permission boundaries have been explicitly decided for each app.
None of these are technically difficult. All of them require doing the discovery work upfront, before any agent flow is designed. The teams that skip the data model mapping phase because they want to see a demo faster consistently end up spending more time fixing retrieval quality problems after the demo than they would have spent mapping the data correctly before it.
kintone is genuinely a strong foundation for enterprise knowledge agent development in Japan — not because of API sophistication, but because the data is already there, organized by people who know the business domain. The integration challenge is respecting that organizational knowledge rather than trying to override it with a generic retrieval strategy.
