Linear

Linear organization を Squid に接続して、issue のクエリおよび更新を行う

Linear personal API key の作成

Linear GraphQL API へのリクエストには Authorization header が必要です。OAuth2 access token または personal API key を使用してリクエストを認証できます。詳細は、Linear API documentation を参照してください。

以下の手順では personal API key を使用します。ただし、OAuth2 access token を作成することで同等の機能を実現することも可能です。personal API key を使用すると、Squid の injection 機能によってすべてのリクエストに API key を自動で追加できます。

integration の追加

Squid Console の Integrations タブに移動します。
Available Integrations をクリックします。
GraphQL integration を見つけて、Add Integration を選択します。
以下の詳細を入力します。

Integration ID: コード内で integration を一意に識別するために任意で指定する文字列。

Base URL: https://api.linear.app/graphql

Inject Request Headers: on に切り替えます。

Field name: Authorization

Location: Header

Secret: on に切り替えます。新しい secret を作成し、値として Linear personal API key を設定します。Secrets は Squid に安全に保存されます。Squid Secrets の詳細は、Secrets documentation を参照してください。

新しく作成した secret を保存します。
Add field をクリックして injection を保存します。
Test Connection をクリックして API への接続をテストします。接続に失敗する場合は、endpoint の値を確認し、console の Secrets タブで secret の値を再入力してみてください。
接続が成功したら、Add Integration をクリックします。

integration の使用

次の import をアプリケーションに追加します。Squid backend から GraphQLClient を実行する場合、Squid を import する必要はありません。代わりに、this.squid を使って提供されている Squid instance にアクセスできます。

import { Squid } from '@squidcloud/client';
import { GraphQLClient } from '@squidcloud/graphql';

Squid instance と integration の ID を渡して GraphQL client を作成します。

const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');

クエリを実行するには、GraphQLClient の query メソッドを使用し、クエリと必要な variables を含むオブジェクトを渡します。

const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');
const query = `
    query(id: String!) {
        issue(id: $id) {
            id
            title
            description
            url
        }
    }
`;
const variables = {
  id: 'some_id',
};

const result = await graphQLClient.query({
  query: query,
  variables: variables,
});

mutation を実行するには、GraphQLClient の mutate メソッドを使用し、クエリと必要な variables を渡します。

const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');

const graphQlRequest = `
    mutation ($title: String!, $description: String!, $teamId: String!, $stateId: String!) {
    issueCreate(
        input: {
        title: $title,
        description: $description,
        teamId: $teamId,
        stateId: $stateId
        }
    ) {
        success
        issue {
        id
        title
        description
        }
    }
    }
`;
const variables = {
  title: 'Example Title',
  description: 'Example description.',
  teamId: 'someTeamId',
  stateId: 'someStateId',
};

const result = await graphQLClient.mutate({
  query: graphQlRequest,
  variables: variables,
});

AI agent で integration を使用する

AI agent で Linear integration を使用する主な方法は 2 つあります。

AI function を使用して必要な variables を取得し、実行したい特定のクエリに渡します。
Linear の GraphQL schema を AI agent に提供し、agent がクエリを作成できるようにします。

AI function で Linear を使用する

Squid backend で、目的のアクションを実行する AI function を実装します。AI functions を使うと、agent が prompt を理解した上で、指定された TypeScript 関数を実行できます。

AI function を作成する際は、関数に @aiFunction decorator を付与し、AI agent がいつその関数を呼び出すべきか、またどの parameters を渡す必要があるかの説明を含めてください。AI functions の詳細は、AI functions documentation を参照してください。

次の例は、keyword filter を使って Linear issues をクエリする関数を示しています。

Backend code
import { SquidService } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @aiFunction(
    'Call this function when someone asks to find issues based on a keyword.',
    [
      {
        name: 'filter',
        description: 'The keyword or words to search for',
        required: true,
        type: 'string',
      },
    ],
  )
  async searchForIssue(filter) {
    const { filter } = data;
    const query = `
        query(searchTerm: String!) {
            issues(filter: { description: { containsIgnoreCase: $searchTerm } }) {
                nodes {
                    id
                    title
                    description
                    url
                }
            }
        }
    `;
    const variables = {
      searchTerm: filter,
    }

    const result = await graphQLClient.query({
      query: query,
      variables: variables,
    });
    return result;
  }
}

関数を使用するには、AI agent を作成し、agent の呼び出し時に option としてその関数を含めます。

次の例は、与えられた prompt に基づいて searchForIssue 関数を呼び出し、Linear issues の description から 'credit' を検索します。

Backend code
const response = await this.squid
  .ai()
  .agent('AGENT_ID')
  .ask('Which linear issues mention credit?', {
    functions: ['searchForIssue'],
  });

クエリをその場で実行する（on the fly）

クライアントがどのクエリを実行する必要があるか分からない場合は、AI agent が代理でクエリを実行できるようにできます。prompt として実行したいクエリの説明を与えると、AI agent がクエリを作成し、それを GraphQLClient に渡せます。

Linear GraphQL schema を context として AI agent に提供します。Squid Console で AI agent に移動し、最新の schema を upload します。schema は Linear documentation からダウンロードできます。
指示として、client prompt を agent がどのように解釈すべきかを伝えます。

次の例は、クエリ生成の 1 つのオプションを示しています。

Using Linear's GraphQL API reference and the Squid GraphQLClient reference, generate the correct query to pass to the Squid GraphQLClient, and pass it to the callLinearAPI function. Always include `url` as a query parameter.

!! Important: Use Linear's GraphQL API reference as context.

!!Important: Do not pass issue IDs or other data points that aren't provided in the prompt.

When filtering with `contains`, always use `containsIgnoreCase`.

If querying for search terms in an issue, only search the description.

Example response format to pass to the function:

query {
  issue(id: "DEV-184") {
    id
    title
    description
    url
  }
}

これらの指示には、agent が遵守すべき重要な点を強調するために「!!Important」が含まれています。また、agent がどのようにクエリを生成すべきかも指定しています。たとえば「If querying for search terms in an issue, only search the description.」などです。これらの指示は、特定のクエリ要件に合わせて変更できます。

Squid backend で、AI agent が生成したクエリを実行する AI function を作成します。

次の AI function は、AI agent からクエリを parameter として受け取り、その後 GraphQLClient を使用してクエリを実行します。

Backend code
import { SquidService } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @aiFunction(
    'call this function when someone asks to query their Linear issues, including querying open issues, updates, cycles, etc.',
    [
      {
        name: 'graphQLQuery',
        description: 'The GraphQL query for the Linear GraphQL API',
        required: true,
        type: 'string',
      },
    ],
  )
  async callLinearAPI(data: { graphQLQuery: string }) {
    const { graphQLQuery } = data;
    // Remove markdown
    const query = graphQLQuery.replace(/```graphql|`/g, '');

    const graphQLClient = new GraphQLClient(
      this.squid,
      'LINEAR_API_INTEGRATION_ID',
    );

    const result = await graphQLClient.query({
      query: query,
    });
  }
}

Linear organization を Squid に接続して、issue のクエリおよび更新を行う​

Linear personal API key の作成​

integration の追加​

integration の使用​

AI agent で integration を使用する​

AI function で Linear を使用する​

クエリをその場で実行する（on the fly）​