リニア
SquidにLinear組織を接続して、課題をクエリおよび更新する
LinearパーソナルAPIキーの作成
Linear GraphQL APIへのリクエストにはAuthorizationヘッダーが必要です。OAuth2 access tokensまたはパーソナルAPIキーを使用してリクエストを認証できます。詳細については、Linear API documentationをご覧ください。
以下の手順ではパーソナルAPIキーを使用します。しかし、同様の機能はOAuth2 access tokenを作成することで達成可能です。パーソナルAPIキーを使用することで、Squidのinjection capabilityを利用してすべてのリクエストに自動的にAPIキーを追加できます。
インテグレーションの追加
-
Squid Console の Integrations タブに移動します。
-
Available Integrations をクリックします。
-
GraphQL インテグレーションを見つけ、Add Integration を選択します。
-
以下の詳細を入力してください:
Integration ID: コード内でインテグレーションを一意に識別するための任意の文字列。
Base URL: https://api.linear.app/graphql
Inject Request Headers: Toggle on.
Field name: Authorization
Location: Header
Secret Toggle on. 新しいsecretを作成し、値にLinearパーソナルAPIキーを設定してください。SecretsはSquidに安全に保存されます。Squid Secretsの詳細については、Secrets documentationをご覧ください.
-
新しく作成したsecretを保存します.
-
Add field をクリックしてinjectionを保存します.
-
Test Connection をクリックしてAPIへの接続をテストします。接続に失敗した場合は、エンドポイントの値を確認し、コンソールの Secrets タブでsecretの値を再入力してください.
-
接続が成功したら、Add Integration をクリックします.
インテグレーションの利用方法
- アプリケーションに以下のimport文を追加します。SquidバックエンドでGraphQLClientを実行する場合、Squidをimportする必要はありません。その代わりに、
this.squidを使用して提供されたSquidのインスタンスにアクセスできます。
import { Squid } from '@squidcloud/client';
import { GraphQLClient } from '@squidcloud/graphql';
- SquidのインスタンスとインテグレーションのIDを渡して、GraphQLクライアントを作成します:
const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');
- クエリを実行するには、GraphQLClientの
queryメソッドを使用し、クエリと変数を含むオブジェクトを渡します:
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,
});
- ミューテーションを実行するには、
GraphQLClientのmutateメソッドを使用し、クエリと変数を渡します:
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エージェントとインテグレーションを利用する方法
LinearのインテグレーションをAIエージェントとともに利用する方法は主に2通りあります:
-
AI function を使用して必要な変数を取得し、実行したい特定のクエリに渡す。
-
AIエージェントにLinearのGraphQL schemaを提供し、エージェントにクエリの作成を任せる。
AI functionでLinearを利用する
-
Squidバックエンドで、希望するアクションを実行するAI functionを実装します。AI functionは、プロンプトの理解に基づいてエージェントが指定されたTypeScript関数を実行することを可能にします。
-
AI functionを書く際は、関数に
@aiFunctionデコレーターを付与し、AIエージェントがいつこの関数を呼び出すべきか、またどのパラメータを渡す必要があるかの説明を含めます。AI functionの詳細については、AI functions documentationをご覧ください.
以下の例は、キーワードフィルターを使用してLinearの課題をクエリする関数の例です:
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エージェントを作成し、エージェントへの呼び出しオプションとして関数を含めます。
以下の例では、提供されたプロンプトに基づいて searchForIssue 関数が呼び出され、Linearの課題のdescription内で 'credit' を検索します:
const response = await this.squid
.ai()
.agent('AGENT_ID')
.ask('Which linear issues mention credit?', {
functions: ['searchForIssue'],
});
クエリを即時実行する
クライアントが実行する可能性のあるクエリが事前に分からない場合、AIエージェントに代わってクエリを実行させることができます。プロンプトとして実行するクエリの説明を提供すると、AIエージェントが作成したクエリを GraphQLClient に渡すことができます。
-
AIエージェントにコンテキストとしてLinear GraphQLスキーマを提供します。Squid ConsoleでAIエージェントに移動し、最新のスキーマをアップロードしてください。スキーマはLinear documentationからダウンロード可能です.
-
指示として、エージェントにクライアントプロンプトの解釈方法を通知します.
以下の例は、クエリを生成する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
}
}
これらの指示には、エージェントが遵守すべき重要な点を強調するために「!!Important」が含まれていることに注意してください。また、エージェントがどのようにクエリを生成すべきかが指定されています。例えば、「If querying for search terms in an issue, only search the description.」のように。これらの指示は、特定のクエリ要件に合わせて修正することができます.
- Squidバックエンドで、AIエージェントが生成したクエリを実行するAI functionを作成します.
以下のAI functionは、AIエージェントからのクエリをパラメータとして受け取り、GraphQLClient を使用してクエリを実行します:
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,
});
}
}