Using agentic AI with Weavy

Agents are customized AI chat bots tailored to your unique needs and preferences. By providing agents with detailed instructions and contextual data they can tailor their responses to help you save time on tedious, repetitive or difficult tasks.

Create agent

Before communicating with an AI through Weavy you need to create an agent user. You can create agents from your account dashboard or with a call to the Agents API.

When creating a agent, you should provide the following information:

uid: A unique user identifier for the agent.
name: Display name of the agent. This is the name your users will use when @mentioning the agent.
provider: Specifies the AI provider. Must be one of anthropic, gemini, kapa, openai or weavy.
model: Model that the agent should use, e.g. gpt-4o-mini for OpenAI.
instructions: Details about your goals, desired behaviors, and preferred format to help the agent personalize its response.

Additionally you need to make sure your Weavy environment is configured with an API key for the underlying AI platform ^[1]. This can also be done from the account dashboard.

For details on available models, and how to obtain API keys for authentication, we recommend visiting the developer docs for respective supported platform:

^[1] For agents with the weavy provider you don't need to provide an API key.

Configure tools

Agents can optionally be configured with tools that helps the underlying model access additional context and information from the web or your files.

Currently tools can only be configured from the account dashboard.

File search

The file_search tool allows your agent to access more context and reference specific docs (only available for openai and weavy agents). When configuring the file search tool you need to provide it with the id of a Weavy files app that contains the files you want the agent to reference.

Web function

Web functions allow your agent to interface with external services through standard HTTP requests. A function is defined by its definition, which informs the agent what it does and what input arguments it expects. It comprises the following fields:

field	description
`name`	The function's name, e.g. `get_weather`
`description`	Details on when and how to use the function
`url`	The external API endpoint to call, e.g. https://api.example.com/weather
`method`	The http method to use (defaults to `GET`)
`headers`	Headers to include in the request, e.g. `Authorization`, `Content-Type` etc.
`parameters`	JSON schema defining the function's input arguments

Based on the instructions and messages in the conversation, the agent may decide to call a function (make a request to the configured url with the specified arguments) and return the result. The agent will then incorporate the result in its final response.

Example function definition:

{
  "name": "get_weather",
  "description": "Get the current weather for a given city.",
  "url": "https://api.example.com/weather",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {API_KEY}",
    "Content-Type": "application/json"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The name of the city to get the weather for."
      }
    },
    "required": ["city"]
  }
}

Interact with an agent

To effectively utilize AI in Weavy, an agent must be notified that its presence is required. To engage the agent within a comment, post or message, users must mention the agent by typing @ followed by the agent's name.

The need to mention the agent for activation allows for a controlled use of the agent's capabilities, making it an efficient participant in discussions where its input is relevant.

One exception exists, in a private chat with a agent (for instance using the copilot component), a user can engage directly with the agent without mentioning it. This is akin to chatting with another person, where messages are exchanged seamlessly between the user and the agent. The direct nature of this interaction allows for a more personalized experience, enabling the agent to provide tailored responses, support, and assistance based on the user's immediate needs and queries.

Troubleshooting

If your interactions with the agent is not working it usually comes down to one of these things:

Weavy has not been configured with an API key for the AI provider.
The agent was configured with an invalid or unsupported model.
The agent does not have permission to respond. This can happen if the agent user does not have write access in the app where you interacted. See apps and permissions.