Skip to Content
ToolsGraphQL tools

GraphQL tools

GraphQL is a way many modern systems let you ask for exactly the data you want in one request. Connect a system’s GraphQL API and every query (a question, such as “find a customer by email”) and every mutation (a change, such as “close a deal”) becomes a tool your assistants can use.

Connect a GraphQL API

  1. Open APIs and click Connect an API.
  2. Pick GraphQL.
  3. Give almyty the API’s description: a link, a file or the text. The GraphQL address itself works too, because most GraphQL APIs describe themselves when asked.
  4. Click Connect API. almyty imports it in the background, and the next page asks only for what is missing, usually the key, which you pick from Credentials or create right there.
  5. Open Tools: each query and mutation is now a tool, as a draft. Test the ones you want on their Test tool tab, then activate them.

The API keeps its key, and every tool made from it signs in with it. A call that comes back with GraphQL errors is reported to the assistant as a failed call, with the API’s own error messages.

Make one by hand

When you need a single query and there is nothing to connect, write the tool yourself.

  1. Open Tools and click Create tool.
  2. Under Execution method, pick GraphQL.
  3. Give it a Tool name and a Description that says plainly what it does.
  4. Under GraphQL:
    • GraphQL endpoint: the address the query is sent to, such as https://api.example.com/graphql.
    • Query or mutation: the one query the tool runs, for example query GetUser($id: Int!) { user(id: $id) { name email } }.
    • Variables (optional): which tool input fills which query variable, such as { "id": "{userId}" }. Leave it empty and the tool’s inputs are sent as the variables, by name.
  5. Under Authentication, pick how it signs in and the key from Credentials.
  6. Under Parameters, list the tool’s inputs (userId in the example).
  7. Click Create tool, then try it on Test tool.

The tool answers with the data the query asked for. If the API answers with GraphQL errors, the assistant sees a failed call with those messages.

For developers

Results and errors

A GraphQL tool returns the response’s data. A response whose errors list is not empty is a failed result, with the messages joined into the error (GraphQL errors: ...). This holds for tools made from a connected API and for tools with their own query.

A tool with its own query

A hand-made tool is stored as its graphqlConfig, which is what Create tool sends to the Tools API:

{
  "name": "get_user",
  "description": "Look up a user by id",
  "type": "query",
  "executionMethod": "graphql",
  "parameters": {
    "type": "object",
    "properties": { "userId": { "type": "integer" } },
    "required": ["userId"]
  },
  "graphqlConfig": {
    "endpoint": "https://api.example.com/graphql",
    "query": "query GetUser($id: Int!) { user(id: $id) { name email } }",
    "variables": { "id": "{userId}" }
  },
  "authConfig": { "type": "bearer", "config": { "credentialId": "<credential id>" } }
}
FieldTypeDescription
graphqlConfig.endpointstringGraphQL URL (https:// or http://). Required unless the tool is linked to an API with apiId, whose base URL is used
graphqlConfig.querystringThe query or mutation. Required
graphqlConfig.variablesobjectOptional map of variable name to a template. A value that is exactly {name} passes the input unchanged, so numbers and booleans keep their type; {name} inside longer text is inserted as text. Without the map, all inputs are sent as variables
graphqlConfig.headersobjectExtra request headers
graphqlConfig.responseMapping.dataPathstringDot path into the whole response (data.user) to return instead of data
configuration.timeoutnumberTimeout in milliseconds, default 30000

The tool signs in with authConfig (a credential it points at), or with the linked API’s key when it has an apiId. A create with executionMethod: "graphql" and no graphqlConfig, or with code, is refused with a 400: the tool is stored in one shape, the one that runs.

Tips

  • Pass values as variables; don’t build them into the query text.
  • Name your operations, which helps when reading the API’s logs.
  • Ask only for the fields you need, so the assistant reads less.
ToolsgRPC tools