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, 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.

Functions

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`	Describes the purpose of the function to the agent.
`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"]
  }
}

MCP servers

Agents can be configured with remote MCP (Model Context Protocol) servers, giving them access to the tools the server exposes. An MCP server is defined by the following fields:

field	description
`name`	A unique identifier for the server, e.g. `crm_data`.
`url`	The url of the remote MCP server, e.g. https://example.com/mcp.
`description`	Describes the server to the agent (optional).
`allowed_tools`	Tool names the agent is allowed to use (optional, defaults to all tools).
`approval_mode`	`always` or `never`, indicating whether tool calls require approval (optional).
`headers`	Headers to include when calling the server, e.g. an `Authorization` header with an API key (optional).

The AI provider connects to the MCP server directly, so the server must be publicly reachable over HTTPS. MCP servers are currently only available for agents using the openai provider.

Context placeholders

Tool urls and header values (for both functions and MCP servers) can contain placeholders that are resolved each time the agent generates a response. This lets a shared agent's tools identify who the agent is acting for, so the receiving endpoint can tailor or restrict its response per user, app or agent:

placeholder	resolves to
`{{weavy_user_uid}}`, `{{weavy_user_id}}`	The `uid`/`id` of the user the agent is responding to.
`{{weavy_app_uid}}`, `{{weavy_app_id}}`	The `uid`/`id` of the app where the interaction takes place.
`{{weavy_agent_uid}}`, `{{weavy_agent_id}}`	The `uid`/`id` of the agent itself.

Example MCP server definition with placeholders:

{
  "name": "crm_data",
  "url": "https://example.com/mcp?user={{weavy_user_uid}}&app={{weavy_app_uid}}",
  "headers": {
    "Authorization": "Bearer <your-api-key>"
  }
}

Placeholders that cannot be resolved (for example {{weavy_user_uid}} when no user is involved) become empty strings, allowing the receiving server to fail closed. Only {{weavy_*}} placeholders are resolved — any other {{...}} syntax in urls or headers is passed through unchanged.

Knowledge

The knowledge tool allows your agent to access more context and reference specific docs (only available for openai and weavy agents). When configuring the knowledge tool you need to provide it with the id of one (or more) files apps that contain the files you want the agent to reference.

Web search

The web_search tool allows your agent to access the web and retrieve information from the internet.

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.