CameleerCameleer / Compare / AI agent tool calls
The action layer for AI agents
AI agent tool calls: direct function calling vs Cameleer
When an agent calls your APIs directly, retries, duplicate actions, half-done work and business rules are left to the model. Route each tool through Cameleer and the model decides what to do while tested code decides how.
Direct tool calls vs tool calls through Cameleer
The same agent, the same model, the same four APIs. The only difference is who executes the steps.
| concern | direct tool calls | through Cameleer |
|---|---|---|
| Who runs a multi-step job | the model, one tool call and one model turn per step | a route; the model makes one call |
| Wrong or invented arguments | reach the API unless glue code checks them | rejected by a JSON schema with every error listed (400) |
| The agent retries a call | the action runs again: a second refund, a second email | each requestId runs once; the repeat gets duplicate |
| A step fails after an earlier one succeeded | half-done work the model has to notice and undo | a saga runs the compensation (cancel the refund) |
| Flaky APIs | the model sees the error and may retry, give up or improvise | retries with back-off at the failing step, then a clear answer |
| Business rules (amounts, limits, approvals) | written in the prompt and trusted to the model | code in the route: the amount comes from the order |
| Credentials | the agent process holds every API key | the route holds them; the agent can only call the tool |
| Audit | whatever the agent framework logs | every accepted call appended to an audit log |
| Rate limits and outages | per agent, if at all | throttle and circuit breaker around any API |
| Tokens and latency | every step re-sends the conversation and tool results | one tool call, one final turn; steps run at code speed |
| Changing an API or vendor | change the tool, the prompt, maybe re-test the agent | change the route; the tool the model sees stays the same |
| Testing | needs the model in the loop | the route is tested without a model |
A real job: refund a damaged order across four systems
A customer writes: “My order EU-4411 arrived broken. I want my money back.” Resolving it means reading the order, refunding it, creating a return label and emailing the customer. Rules: delivered orders only, the refund is the order total, refunds over 200 need a person.
Direct: the model orchestrates
- Four tools:
get_order,issue_refund,create_return_label,send_email. - A good run is 4 tool calls and 5 model turns, each re-sending the whole conversation.
- The refund amount is whatever the model read or typed.
- A retry after a timeout refunds twice. A carrier outage after the refund leaves money gone and no label.
Through Cameleer: the model decides, a route executes
- One tool,
resolve_damaged_order, with only what the conversation knows: request id, order id, reason. - The route validates the arguments, runs each request once, reads the total from the order and checks the rules.
- Refund and label run as a saga: if the label fails, the refund is cancelled.
- Retries with back-off, an audit entry, one clear answer to the model.
What the tested route answers
| the agent sends | the route answers | what happened |
|---|---|---|
EU-4411, damaged | 200 resolved | amount 129.9 taken from the order; a failed payment call was retried; label created; customer emailed |
| the same call again | 200 duplicate | nothing executed a second time |
| a malformed id, a free-text reason and an invented amount | 400 | every bad field named; nothing executed |
| an order not yet delivered | 409 rejected | nothing executed |
| an order totalling 899 | 202 pending_approval | parked for a person, no refund |
| the carrier is down | 502 failed | refund issued once, label tried three times, refund cancelled, no email |
The route runs end to end in Cameleer's test suite against mock order, payment, shipping and email APIs. Read the full route and the walkthrough.
When a direct tool call is enough
Call the API directly when the call
- only reads, like a search or a lookup, and a repeat does no harm;
- is a single step with no other system to keep consistent;
- is a prototype you will move behind a route before real users touch it.
Use a route as soon as a call
- changes something: money, stock, messages, tickets;
- spans several systems that must stay consistent;
- needs a rule the model must not override, or an audit trail.
Common questions
Is Cameleer an AI agent framework?
No. The agent framework runs the model loop and decides which tool to call. Cameleer executes the tool: it is the action layer between the agent and your systems.
Does routing tool calls through Cameleer replace function calling?
No. The model still uses function calling; the tool it calls is a Cameleer route behind an HTTP endpoint, declared with the same JSON schema the route validates against.
Which models and agent frameworks does it work with?
Any that support function calling or tool use and can make an HTTP request: OpenAI, Anthropic, Google, AWS Bedrock and Azure OpenAI models, open models on Ollama or vLLM, and frameworks that let you define a tool as an HTTP call.
Does Cameleer speak MCP?
Not yet. Today a tool is an HTTP endpoint, which every framework with function calling can call; an MCP tool server that exposes routes as tools is on the roadmap. Apache Camel 4.22 ships an MCP server; Cameleer brings the reliability patterns now and the protocol next.
How is this different from a hosted tool catalog such as Composio or Arcade?
Those platforms give an agent many pre-built connectors with managed OAuth, hosted and priced per use. Cameleer is open source and self-hosted: a 20 MB container or a library, about 230 components, and the reliability around the call written as a tested route: schema validation, idempotency, retries, sagas, human approval, rate limits and an audit log. Use a catalog for breadth of SaaS actions; use Cameleer when the action changes money, stock or records and must run exactly once inside your own network.
What happens when an agent retries a tool call?
The route sees the same requestId and answers duplicate without executing anything again.
When is a direct tool call enough?
When the call only reads, is a single step with no other system to keep consistent, or is a prototype. Use a route as soon as a call changes something, spans several systems, needs a rule the model must not override, or must be audited.
Does an extra hop make tool calls slower?
A route adds microseconds to a call; a model turn takes hundreds of milliseconds to seconds. A multi-step job through one route saves model turns, so it is usually faster end to end.
Try it
Get the tested tool route from the guide and check it with cameleer validate. Then set the URLs of your order, payment, shipping and email APIs, run it, and point your agent's tool definition at it.
git clone https://github.com/pmsudhi/cameleer && cd cameleer/examples/agents docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer validate /routes/damaged-order-tool.camel.yaml