Linear

Linear organization を Squid に接続し、issue を query・update します

Linear Personal API Key を作成する

Linear GraphQL API への request には Authorization header が必要です。OAuth2 access token または personal API key を使用して request を authorize できます。詳細については、Linear API documentationを参照してください。

以下の instruction では personal API key を使用します。ただし、OAuth2 access token を作成しても同じ capability を実現できます。personal API key を使用すると、Squid injection capability を使用してすべての request に API key を自動的に追加できます。

Integration の追加

Squid Console の Integrations tab に移動します。
Available Integrations をクリックします。
GraphQL integration を見つけ、Add Integration を選択します。
次の detail を入力します。

Integration ID: code 内で integration を一意に識別する任意の string。

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

Inject Request Headers: on に toggle します。

Field name: Authorization

Location: Header

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

新しく作成した secret を保存します。
Add field をクリックして injection を保存します。
Test Connection をクリックして API への connection を test します。connection が failure した場合は endpoint の value を確認し、console の Secrets tab で secret の value を再入力してください。
connection が成功したら、Add Integration をクリックします。

Integration の使用

application に次の import を追加します。Squid backend から GraphQLClient を実行する場合は Squid を import する必要はありません。代わりに this.squid を使用して提供された Squid instance に access できます。

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

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

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

query を実行するには、GraphQLClient の query method を使用し、query と任意の variable を含む object を渡します。

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 method を使用し、query と任意の variable を渡します。

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 を使用する

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

AI function を使用して必要な variable を取得し、実行する specific query に渡す。
AI agent に Linear の GraphQL schema を提供し、agent に query を作成させる。

AI Function で Linear を使用する

Squid backend で、目的の action を実行する AI function を実装します。AI function により、agent は prompt の理解に基づいて指定された TypeScript function を実行できます。

AI function を記述する場合は、function に @aiFunction decorator を attach し、AI agent が function を call する場合と渡すべき parameter の description を含めます。AI function の詳細については、AI functions documentationを参照してください。

以下の例では、keyword filter を使用して Linear issue に query を実行する function を示します。

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;
  }
}

function を使用するには、AI agent を作成し、agent call の option に function を含めます。

次の例では、提供された prompt に基づいて searchForIssue function を call し、Linear issue の description から 'credit' を検索します。

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

On-the-fly で Query を実行する

client が実行する必要のある query が不明な場合は、AI agent が代わりに query を実行するよう許可できます。prompt として実行する query の description を指定すると、AI agent が query を作成し、それを GraphQLClient に渡せます。

Linear GraphQL schema を context として AI agent に提供します。Squid Console で AI agent に移動し、最新 schema を upload します。schema は Linear documentation から download できます。
instruction では、agent が client prompt をどのように interpret すべきか伝えます。

次の例は query を生成するための 1 つの option を示します。

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
  }
}

これらの instruction には、agent が従うべき key point を強調するために "!!Important" が含まれていることに注目してください。また、agent が query を生成する方法も指定しています。たとえば、「issue 内の search term を query する場合は、description のみを search する」とあります。これらの instruction は specific query need に合わせて変更できます。

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

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

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 を query・update します​

Linear Personal API Key を作成する​

Integration の追加​

Integration の使用​

AI Agent で Integration を使用する​

AI Function で Linear を使用する​

On-the-fly で Query を実行する​