Comment by _pdp_

2 hours ago

I had to deal with exactly this issue with one of my recent oss projects so I can share a few things on the topic.

1. Text is the default interface

i.e. the api must be text based first but it should allow to fallback to structured output by using the accept header.

That being said, it is not wrong to introduce other means to return json by using ?format=json etc.

2. Make it grepable

Basically surface as much useful information in a single line so that the agent can grep and slice.

3. Identifiers must be short

i.e. short enough to describe in 5 tokens but not too short to introduce collisions or confusion.

Otherwise you could be wasting a lot of token for nothing. However, adding prefixes helps like cus_abc123, token_xxx, etc. The prefix can help with lookup, error correction and deduplication.

4. Surface information that is likely to be used by the agent

i.e. if the agent is asking for a list of resources, don't just return the list but also some additional information that might help the agent understand better the context around the resource.

Without this a single task could take a lot more steps simply because the agent needs to run its own loop - it is slow and expensive.

5. Add bulk operations

It is a lot easier to insert 10 records in one request then performing 10 separate requests.

6. Error messages should be descriptive

Ensure that error message point to actual docs and manuals that can be read by the agent so that it can troubleshoot on its own. Also return hints.

I've added most of these at https://github.com/crmkit/crmkit which is highly experimental CRM I tried to specifically design for AI agents. We use it internally for a few projects and it is not perfect but I think it might be on the right direction.