Build an assistant that researches the web

Section: DOC-IN-tools-connections#give-your-agent-tools.

Give your users an assistant that can look up current information and answer with sources. This recipe adds web research to an existing conversation using Travila's available Tavily tools, then checks that an answer came from a successful lookup.

You need a working text conversation, a backend API key, an authenticated application user, and Tavily enabled in your Travila catalog. Keep the key on your backend. Use the same user and conversation throughout the recipe.

Choose the job your agent needs to do

Section: DOC-IN-tools-connections#start-here.

Start here for web research. For a different job, follow its recipe:

Customer task	Recipe
Answer a question using current web information	Continue below
Check the user's calendar or work in a connected app	Connect an account
Read a website using a service account you already own	Connect your own MCP server
Act in your application or ask before a sensitive change	Use and approve tools
Recall a user's preferences in later conversations	Build with memory

1. Check that web search is available

Section: DOC-IN-tools-connections#discovering-available-tools.

Find the server and inspect its tools before designing the assistant around them. A catalog entry alone does not prove that the service can answer a request now.

Find the available search service

Section: DOC-IN-tools-connections#list-mcp-servers.

curl -X POST https://api.travila.ai/api/v1/llm/mcp-list-available-servers \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Reference: List available MCP servers · Request fields.

Find the platform-provided Tavily service in the returned catalog and keep its server ID for the next step.

If the server is absent or paused, stop this setup and resolve its availability with your operator. Use your own registered server when you want to use your own vendor account.

Inspect the tools you will use

Section: DOC-IN-tools-connections#list-tools.

Call mcp-list-tools with servers containing the selected built-in:tavily reference. Read the returned tool names, descriptions and input schemas. Choose the search or extraction tools needed for your assistant's job.

Supply an explicit server list. Omitting it can discover unrelated registered servers; this operation does not infer a particular conversation's configuration.

2. Enable research for the conversation

Section: DOC-IN-tools-connections#platform-servers.

For a conversation without an active agent profile, read its current settings through conversation state, add the selected server to that complete settings object, and submit it below. The update replaces the whole settings object: preserve the interrupt policy, generation limit, prompt variables and other choices the conversation still needs.

The example is complete for a new conversation with no customized settings. For your existing conversation, replace thread_abc123 with its key and include the settings you read along with the server selection.

curl -X POST https://api.travila.ai/api/v1/llm/update-settings \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "thread_abc123",
  "settings": {
    "mcpServers": [
      {
        "serverId": "built-in:tavily"
      }
    ]
  }
}'

Reference: Update conversation settings · Request fields.

Select only the discovered search tools this assistant needs, then test the effective selection on the next turn.

3. Ask a question and check its sources

Section: DOC-IN-tools-connections#get-started.

Send a question that needs a fresh lookup, such as “Find the latest official React release notes, summarize the changes relevant to building a chat interface, and include links.” Use your existing send-message flow.

Inspect the tool-call record and the returned answer. The useful result is a successful lookup followed by an answer that cites the retrieved sources. A selected server reference in generationContext.resolvedMcpServers is not evidence that discovery or a tool call succeeded. If no lookup occurred, do not label the answer as freshly researched.

Treat retrieved pages as external content. Render text and links safely, and check that a cited source supports the claim before using the answer for an important decision. A search result does not authorize an action in another service.

Isolate a failing lookup

Section: DOC-IN-tools-connections#calling-tools-directly.

If the assistant cannot retrieve a page, test the discovered read-only tool through mcp-call-tool. Supply its exact server ID, tool name and schema-valid arguments; argumentsJson is a JSON object. Keep the returned requestId for correlation.

Check the tool's result as well as the outer HTTP status. A direct call helps distinguish an unavailable service or bad input from the assistant choosing not to call it. It executes outside the conversation's approval flow, so use it only for an operation your backend has independently authorized.

Keep each task focused

Section: DOC-IN-tools-connections#per-turn-servers.

For a turn that needs a different selection, supply overrideMcpServers on send-message or send-message-sync. Include the complete server list and its allow/block rules for that task: a non-empty override replaces the inherited list.

Add actions with approval

Section: DOC-IN-tools-connections#tool-approval-flow.

When your research assistant also sends messages or changes records, add the relevant connected app or custom server and configure approval rules before offering those actions. The default requires no approvals. Match the actual discovered names or full server IDs, then test an approved call and a denied call.

Follow Use and approve tools for the full pending-call, decision and recovery flow. An approval is about the displayed action and account; merely connecting an app does not approve everything it can do.

Apply the approval rules for this agent and turn

Section: DOC-IN-tools-connections#policy-precedence.

Put the approval rules on the configuration that owns this task. Test an approved and denied action for the actual profile and turn before enabling it for customers.

Let the assistant work inside your application

Section: DOC-IN-tools-connections#client-tools.

For a result such as opening a screen or looking up a record that only your backend can access, declare a client tool. Your application receives the call, validates and authorizes it, performs the action, and submits the result for that original call.

Use the client-tool recipe to build that round trip and recover interrupted responses. These tools need your execution handler; Travila does not perform the application action for you.

Schedule a summary while the app is closed

Section: DOC-IN-tools-connections#schedule-without-client-tools.

Send a weekly summary even when nobody has your app open. Your conversation may normally offer client tools such as opening a screen, but those actions need your application's execution handler. This recipe removes inherited client tools for the scheduled turn and preserves normal interactive behavior for the next turn.

1. Choose the conversation and summary message. Keep only connected-service tools that the unattended job can use; clearing client tools does not remove those tools or authorize their actions.
2. Follow the scheduled-agent recipe to send the summary request from your backend worker. Include overrideGenerationConfig: {"clearClientTools": true} next to userMessage in that send request, and keep this turn setting with the saved summary task. Omit clientTools or leave it empty. A nonempty replacement list wins over the clear directive. Put the directive on this turn, not on the stored conversation defaults or profile.
3. Follow the accepted run to its generation outcome. The scheduled run has no inherited client-tool definitions, including when it waits behind another run. Connected-service calls still follow their normal execution and approval rules. The next interactive turn inherits the original client tools.

For example, a conversation's normal client tool opens the account dashboard. Its Monday summary asks “Summarize last week's completed tasks” with the per-turn directive above. The summary does not ask the closed app to open a dashboard; a later interactive request can use that tool again. The directive changes tool selection, not earlier history or already completed actions.

What it does not do, and recovery: an empty clientTools list still inherits rather than clears, so send the directive above rather than an empty list. Clearing client tools does not remove connected-service tools or authorize their actions. If a run is already waiting for a client result, reconnect the original handler and reconcile that call before resending; changing a later turn's tools does not resolve an existing pending call.

Continue building

Section: DOC-IN-tools-connections#related.

• Connected apps: let the assistant use a customer's account.
• Custom MCP servers: connect a service you operate or pay for.
• Conversation API reference: exact tool discovery, invocation and configuration contracts.
• Agent profiles: reuse the selected tools and instructions across conversations.

MCP resource and prompt transport operations currently return empty responses and cannot supply content for this recipe. Their availability is documented in the reference: list resources, read resource, list prompts and get prompt. Use prompt fragments for reusable agent instructions.

Document ID: DOC-IN-tools-connections. Section identities and revisions.