HTTP tools for voice agents: how to integrate APIs

Define a small, verifiable action

Start with the outcome your team needs: checking an order, looking up availability or recording a request. Define what information the caller must provide and what proves the task is complete. Looking up an address and changing it are different tasks and may require different permissions.

HTTP is the communication method used by many of these connections; an API is the interface through which a system receives a request and returns a response. In Tigy, the tool needs an access address, action type and required information. Obtain those settings from the external system owner; you do not need to invent them or write a program to define the service requirement.

Explain when to call the tool

A name such as lookup_order helps, but the description should say that the caller must confirm an order number first. Agent instructions should explain how to request that value and present the returned information.

Do not supply invented values. If the caller corrects a number, the next lookup should use the correction rather than the first value heard.

Plan for failures and repetition

Distinguish an empty result, an error and a completed action. An unavailable API should lead to an honest explanation and a defined alternative rather than a fictional status.

For record creation, the API team should handle repeated attempts to prevent duplicates. An interrupted call can leave the conversation without confirmation even when the system already performed the action.

Check both the conversation and destination system

Ask the team for a test connection with fictional information for actions that create or change records. Test missing information, slow responses, missing records and corrections during the conversation. Check the result received by the agent and open the destination system to verify the record.

Publish a limited scope after these situations work. Add further actions based on service needs, with the same clarity about inputs and confirmation.

Test an order lookup with your team

Imagine a fictional store. A caller supplies an order number and asks when it will arrive. The lookup may find an order being prepared, find no record or fail because the system is unavailable. Prepare a different response for each case without turning an estimate into a guarantee.

Ask the integration team to set up these three cases in a test environment. You can review the conversation and check the order in the store’s system. The technical team checks that information was sent correctly and that the agent received the expected result.

HTTP success does not establish task completion

A connection may acknowledge receiving a request without completing the task. Agree with the team on possible outcomes: a found record, missing information, pending processing or a rejected request. For record creation, ask for a reference and status that let staff check what actually happened.

Test partial responses. A status without an estimate should not produce an invented delivery date. Human approval should be described as pending. A missing response also does not prove that a write never happened.

To prevent a repeated attempt from creating two bookings or tickets, the integration team must identify when it is the same request and provide a way to look up the result. Agree on how to test that protection. It must be set up for the connected system; it is not automatic protection for every Tigy integration.

Verify behavior, parameters and effects

Use fictional-data cases covering valid retrieval, missing records, invalid fields, refused access and outages. Record utterances, selected tools, parameters and destination outcomes. Writes also need corrections and repetitions.

Verify when no tool should run. General policies can use documents without accessing personal records. Mentioning cancellation as an example does not necessarily authorize cancelling a purchase.

In Tigy, configure the tool, select it in the agent and save before testing. Check that instructions match the actions and outcomes agreed with the team. When the connected system changes, request a configuration review and repeat affected cases. A connection that still responds may now return information with a different meaning.

Design a tool around a recognizable task

A tool should represent an action the agent can distinguish during conversation. “Retrieve order status” communicates purpose better than “Execute API.” Names, descriptions and parameters help the model decide when to invoke a tool. Tigy documentation emphasizes that relationship: selection depends on agent instructions and the tool definition.

Start with the service contract. When is retrieval allowed? What must be collected beforehand? Which value identifies an order and which verifies access? The model can collect parameters, but the responsible server must validate authorization and input. A caller mentioning an identifier does not establish permission to read the record.

Avoid exposing a universal tool accepting any path or method requested in conversation. Narrowly scoped tools are easier to evaluate and constrain possible effects. If retrieval and modification are available, use definitions making that distinction explicit. “Read address” and “Change address” need different conditions and should not be confused through vague descriptions.

Explain the meaning of the information requested by the tool. A field called “code” might identify a customer, contract or order. Its description should say which number to use, how to confirm it and what to do when it is missing. Also agree on how optional fields are handled: leaving information blank must not cause it to be interpreted as a different value.

Imagine a fictional company allowing order lookup using a confirmed code. The caller corrects the final digit before submission. Testing should show the corrected parameter in the invocation and a response matching the retrieved record. Pleasant wording does not prove that the tool received the right value. Integration evidence belongs to review.

Return responses explaining the operation's state

Tool responses should distinguish success, missing records, insufficient permission and unavailability. If every state appears simply as “error,” the conversation loses the ability to explain the next step. The API contract should provide consistent interpretation without exposing unnecessary internal details or sensitive information.

For retrieval, distinguish “Order not found” from “Service did not respond.” The first may justify checking the code. The second may require waiting or using another channel. Asking someone to repeat an identifier when the server is unavailable attributes the problem to the caller and unnecessarily extends the call.

For writes, the response should indicate whether the operation is confirmed or needs investigation. Conversation should announce “created” or “updated” only with sufficient evidence. An acceptance response may mean receipt for later processing. If that is the system's rule, the agent should explain that the request was received rather than claim the final outcome already occurred.

Plan for uncertainty when a request receives no response. An operation may have completed before connectivity failed. Immediately repeating creation can generate duplicates. The server needs a mechanism recognizing the same request or allowing outcome retrieval. Conversational instructions should follow that contract, including appropriate wording when confirmation is unavailable.

Limit response size and relevance. An agent explaining delivery status does not need the customer's entire order history. Besides increasing exposure, irrelevant information makes results harder to interpret. Design responses containing what the task requires and retain authorization decisions in the integrated system.

Test responses containing unexpected text as well. Information from an integration is data, not new instructions to ignore scope. An order description containing an imperative sentence must not change agent permissions. Any following operation remains subject to instructions and server controls.

Investigate integration by layer

When a tool fails, check four things: did the agent choose the right action, send the confirmed information, receive the expected result and explain it correctly? This sequence separates a conversation problem from a connection problem. A rejected access key, for example, will not be fixed simply by changing instructions.

In Tigy, check that the tool is attached to the agent being tested. Ask the integration owner to review the address, action type and access key used by the connection. Use a test environment, especially when the action creates records or sends messages. Saving a tool is not enough if the agent has not selected it.

Maintain cases for success, missing input, user correction, denied access and temporary failure. Readiness means the permitted operation works and other conditions produce honest explanations. Repeat the collection after contract changes: a field change can keep requests technically valid while altering the business meaning of saved records.

Assign someone to maintain the connection and someone to review the wording callers hear. When the integration team changes a result, check that the agent explains its new meaning correctly. A connection that works must not produce a customer promise the system cannot support.