メインコンテンツまでスキップ

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 の追加​

  1. Squid Console の Integrations タブに移動します。

  2. Available Integrations をクリックします。

  3. GraphQL integration を見つけて、Add Integration を選択します。

  4. 次の詳細を入力します。

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

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

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

Field name: Authorization

Location: Header

Secret Toggle on. 新しい secret を作成し、値に Linear personal API key を設定します。Secrets は Squid 内で安全に保管されます。Squid Secrets の詳細は、Secrets documentation を参照してください。

  1. 新しく作成した secret を保存します。

  2. Add field をクリックして injection を保存します。

  3. Test Connection をクリックして API への接続をテストします。接続に失敗する場合は、endpoint の値を確認し、コンソールの Secrets タブで secret の値を再入力してみてください。

  4. 接続に成功したら、Add Integration をクリックします。

integration の使用​

  1. 次の import をアプリケーションに追加します。Squid backend から GraphQLClient を実行する場合、Squid を import する必要はありません。代わりに、this.squid を使って提供されている Squid instance にアクセスできます。
import { Squid } from '@squidcloud/client';
import { GraphQLClient } from '@squidcloud/graphql';
  1. Squid instance と integration の ID を渡して GraphQL client を作成します。
const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');
  1. クエリを実行するには、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,
});
  1. 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 つあります。

  1. AI function を使って必要な variables を取得し、実行したい特定のクエリに渡す。

  2. AI agent に Linear の GraphQL schema を提供し、agent にクエリを作成させる。

AI function で Linear を使用する​

  1. Squid backend で、目的のアクションを実行する AI function を実装します。AI functions により、agent はプロンプトの理解に基づいて、指定された TypeScript 関数を実行できます。

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

次の例は、キーワードフィルタを使って 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;
  }
}
  1. 関数を使用するには、AI agent を作成し、agent 呼び出し時の option としてその関数を含めます。

次の例は、指定したプロンプトに基づいて searchForIssue 関数を呼び出し、Linear issues の description 内から「credit」を検索します。

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

その場でクエリを実行する​

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

  1. AI agent にコンテキストとして Linear GraphQL schema を提供します。Squid Console で AI agent に移動し、最新の schema をアップロードします。schema は Linear documentation からダウンロードできます。

  2. 手順として、クライアントのプロンプトを 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.」のようにです。これらの指示は、必要なクエリ要件に合わせて調整できます。

  1. 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,
    });
  }
}