Agent Runs

Iniciar uma execução de agente salva

Inicia uma execução assíncrona em segundo plano para um agente salvo e retorna o registro da execução enfileirada. Use o endpoint de recuperação da execução para consultar o status ou o endpoint de eventos para transmitir o progresso. Quando o agente já estiver executando o número máximo de execuções max_concurrent_runs, concurrency_overflow decide: reject retorna 429 com o código de erro agent_concurrency_limit e não cria nenhuma execução; queue retorna 202 com uma execução em espera que começa quando uma vaga é liberada.

POST

api

agents

{agent_id}

runs

Typescript (SDK)

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await sdk.agentRuns.createAgentRun({
    agentId: "<id>",
    createAgentRunRequest: {
      input: [
        {
          type: "<value>",
        },
      ],
    },
  });

  console.log(result);
}

run();

package main

import(
	"context"
	mka1 "github.com/MeetKai/mka1-sdks/go"
	"github.com/MeetKai/mka1-sdks/go/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := mka1.New(
        mka1.WithSecurity("<YOUR_BEARER_TOKEN_HERE>"),
    )

    res, err := s.AgentRuns.CreateAgentRun(ctx, "<id>", components.CreateAgentRunRequest{
        Input: components.CreateCreateAgentRunRequestInputUnionArrayOfCreateAgentRunRequestInput(
            []components.CreateAgentRunRequestInput{
                components.CreateAgentRunRequestInput{},
            },
        ),
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.AgentRun != nil {
        // handle response
    }
}

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using System.Collections.Generic;

var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.AgentRuns.CreateAgentRunAsync(
    agentId: "<id>",
    body: new MeetKai.MKA1.Types.Components.CreateAgentRunRequest() {
        Input = CreateAgentRunRequestInputUnion.CreateArrayOfCreateAgentRunRequestInput(
            new List<CreateAgentRunRequestInput>() {
                new CreateAgentRunRequestInput() {
                    Type = "<value>",
                },
            }
        ),
    }
);

// handle response

from meetkai_mka1 import SDK, models


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.agent_runs.create_agent_run(agent_id="<id>", input=[
        models.CreateAgentRunRequestInput(
            type="<value>",
        ),
    ], stream=False)

    # Handle response
    print(res)

curl --request POST \
  --url https://apigw.mka1.com/api/v1/agents/{agent_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<string>",
  "idempotency_key": "<string>",
  "agent_version": 1073741824,
  "conversation": "<unknown>",
  "previous_response_id": "<string>",
  "context_management": [
    {
      "type": "compaction",
      "compact_threshold": 1001
    }
  ],
  "stream": false,
  "metadata": {}
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: '<string>',
    idempotency_key: '<string>',
    agent_version: 1073741824,
    conversation: '<unknown>',
    previous_response_id: '<string>',
    context_management: [{type: 'compaction', compact_threshold: 1001}],
    stream: false,
    metadata: {}
  })
};

fetch('https://apigw.mka1.com/api/v1/agents/{agent_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigw.mka1.com/api/v1/agents/{agent_id}/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => '<string>',
    'idempotency_key' => '<string>',
    'agent_version' => 1073741824,
    'conversation' => '<unknown>',
    'previous_response_id' => '<string>',
    'context_management' => [
        [
                'type' => 'compaction',
                'compact_threshold' => 1001
        ]
    ],
    'stream' => false,
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://apigw.mka1.com/api/v1/agents/{agent_id}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"agent_version\": 1073741824,\n  \"conversation\": \"<unknown>\",\n  \"previous_response_id\": \"<string>\",\n  \"context_management\": [\n    {\n      \"type\": \"compaction\",\n      \"compact_threshold\": 1001\n    }\n  ],\n  \"stream\": false,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigw.mka1.com/api/v1/agents/{agent_id}/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"agent_version\": 1073741824,\n  \"conversation\": \"<unknown>\",\n  \"previous_response_id\": \"<string>\",\n  \"context_management\": [\n    {\n      \"type\": \"compaction\",\n      \"compact_threshold\": 1001\n    }\n  ],\n  \"stream\": false,\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "object": "agent.run",
  "id": "<string>",
  "agent_id": "<string>",
  "agent_version": 2,
  "status": "waiting",
  "input": "<unknown>",
  "conversation": "<unknown>",
  "previous_response_id": "<string>",
  "metadata": {},
  "gateway_response_id": "<string>",
  "gateway_response": "<unknown>",
  "error": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

{
  "object": "agent.run",
  "id": "<string>",
  "agent_id": "<string>",
  "agent_version": 2,
  "status": "waiting",
  "input": "<unknown>",
  "conversation": "<unknown>",
  "previous_response_id": "<string>",
  "metadata": {},
  "gateway_response_id": "<string>",
  "gateway_response": "<unknown>",
  "error": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

Autorizações

Authorization

string

header

obrigatório

Send Authorization: Bearer , using an MKA1 API key for automation or an OAuth API access token for a signed-in application. Use a dynamic security callback to refresh OAuth access tokens. Browser session-only operations still require their declared cookie.

Cabeçalhos

X-On-Behalf-Of

string

Optional external end-user identifier forwarded by the API gateway.

Parâmetros de caminho

agent_id

string

obrigatório

Corpo

application/json

input

obrigatório

Required string length: 1 - 20000

idempotency_key

string

Chave limitada ao chamador para repetir o mesmo envio sem iniciar outra execução. Reutilizar uma chave com uma solicitação diferente retorna 409.

Required string length: 1 - 255

agent_version

integer

Versão imutável da configuração do agente salvo a ser executada. Omitir para usar a versão atual. Versões explícitas permanecem fixadas enquanto estiverem na fila.

Intervalo obrigatório: 1 <= x <= 2147483647

conversation

any

Valor JSON arbitrário.

previous_response_id

string

context_management

object[]

Estratégias de gerenciamento de contexto a serem aplicadas durante a geração de respostas executadas por agentes. Suporta compactação, que resume o histórico de conversa mais antigo quando o contexto excede um limite de tokens.

Show child attributes

stream

boolean

padrão:false

Quando verdadeiro, o gateway gera eventos delta por token para esta execução, de modo que o endpoint de eventos transmite a saída incremental em vez de apenas limites de item e de ciclo de vida. A execução ainda é realizada em segundo plano e este endpoint ainda retorna o registro da execução enfileirada.

metadata

object

Show child attributes

Resposta

Execução na fila.

object

enum<string>

obrigatório

Opções disponíveis:

agent.run

string

obrigatório

agent_id

string

obrigatório

agent_version

integer | null

obrigatório

A versão da configuração do agente que esta execução foi executada. Nulo para execuções criadas antes da versionação.

Intervalo obrigatório: x >= 1

status

enum<string>

obrigatório

waiting significa que a execução está retida em um dos slots de max_concurrent_runs do agente e não foi enviada ao modelo; ela pode ser cancelada. Os resultados terminais permanecem distintos: cancelled é solicitado pelo chamador; incomplete significa que um limite ou interrupção interrompeu a execução. gateway_response.incomplete_details registra o motivo, incluindo max_tokens ou max_tool_calls. Linhas falhas armazenadas com um desses resultados de gateway são serializadas com o resultado do gateway, preservando qualquer erro do conector e o carimbo de data/hora de conclusão.

Opções disponíveis:

waiting,

queued,

submitting,

completed,

failed,

cancelled,

incomplete

input

any

obrigatório

Valor JSON arbitrário.

conversation

any | null

obrigatório

Valor JSON arbitrário.

previous_response_id

string | null

obrigatório

metadata

object | null

obrigatório

Show child attributes

gateway_response_id

string | null

obrigatório

gateway_response

any | null

obrigatório

Valor JSON arbitrário.

error

any | null

obrigatório

Valor JSON arbitrário.

created_at

string<date-time>

obrigatório

completed_at

string<date-time> | null

obrigatório

⌘I

Typescript (SDK)

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await sdk.agentRuns.createAgentRun({
    agentId: "<id>",
    createAgentRunRequest: {
      input: [
        {
          type: "<value>",
        },
      ],
    },
  });

  console.log(result);
}

run();

package main

import(
	"context"
	mka1 "github.com/MeetKai/mka1-sdks/go"
	"github.com/MeetKai/mka1-sdks/go/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := mka1.New(
        mka1.WithSecurity("<YOUR_BEARER_TOKEN_HERE>"),
    )

    res, err := s.AgentRuns.CreateAgentRun(ctx, "<id>", components.CreateAgentRunRequest{
        Input: components.CreateCreateAgentRunRequestInputUnionArrayOfCreateAgentRunRequestInput(
            []components.CreateAgentRunRequestInput{
                components.CreateAgentRunRequestInput{},
            },
        ),
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.AgentRun != nil {
        // handle response
    }
}

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using System.Collections.Generic;

var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.AgentRuns.CreateAgentRunAsync(
    agentId: "<id>",
    body: new MeetKai.MKA1.Types.Components.CreateAgentRunRequest() {
        Input = CreateAgentRunRequestInputUnion.CreateArrayOfCreateAgentRunRequestInput(
            new List<CreateAgentRunRequestInput>() {
                new CreateAgentRunRequestInput() {
                    Type = "<value>",
                },
            }
        ),
    }
);

// handle response

from meetkai_mka1 import SDK, models


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.agent_runs.create_agent_run(agent_id="<id>", input=[
        models.CreateAgentRunRequestInput(
            type="<value>",
        ),
    ], stream=False)

    # Handle response
    print(res)

curl --request POST \
  --url https://apigw.mka1.com/api/v1/agents/{agent_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<string>",
  "idempotency_key": "<string>",
  "agent_version": 1073741824,
  "conversation": "<unknown>",
  "previous_response_id": "<string>",
  "context_management": [
    {
      "type": "compaction",
      "compact_threshold": 1001
    }
  ],
  "stream": false,
  "metadata": {}
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: '<string>',
    idempotency_key: '<string>',
    agent_version: 1073741824,
    conversation: '<unknown>',
    previous_response_id: '<string>',
    context_management: [{type: 'compaction', compact_threshold: 1001}],
    stream: false,
    metadata: {}
  })
};

fetch('https://apigw.mka1.com/api/v1/agents/{agent_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigw.mka1.com/api/v1/agents/{agent_id}/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => '<string>',
    'idempotency_key' => '<string>',
    'agent_version' => 1073741824,
    'conversation' => '<unknown>',
    'previous_response_id' => '<string>',
    'context_management' => [
        [
                'type' => 'compaction',
                'compact_threshold' => 1001
        ]
    ],
    'stream' => false,
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://apigw.mka1.com/api/v1/agents/{agent_id}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"agent_version\": 1073741824,\n  \"conversation\": \"<unknown>\",\n  \"previous_response_id\": \"<string>\",\n  \"context_management\": [\n    {\n      \"type\": \"compaction\",\n      \"compact_threshold\": 1001\n    }\n  ],\n  \"stream\": false,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigw.mka1.com/api/v1/agents/{agent_id}/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"agent_version\": 1073741824,\n  \"conversation\": \"<unknown>\",\n  \"previous_response_id\": \"<string>\",\n  \"context_management\": [\n    {\n      \"type\": \"compaction\",\n      \"compact_threshold\": 1001\n    }\n  ],\n  \"stream\": false,\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "object": "agent.run",
  "id": "<string>",
  "agent_id": "<string>",
  "agent_version": 2,
  "status": "waiting",
  "input": "<unknown>",
  "conversation": "<unknown>",
  "previous_response_id": "<string>",
  "metadata": {},
  "gateway_response_id": "<string>",
  "gateway_response": "<unknown>",
  "error": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

{
  "object": "agent.run",
  "id": "<string>",
  "agent_id": "<string>",
  "agent_version": 2,
  "status": "waiting",
  "input": "<unknown>",
  "conversation": "<unknown>",
  "previous_response_id": "<string>",
  "metadata": {},
  "gateway_response_id": "<string>",
  "gateway_response": "<unknown>",
  "error": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

Responses and conversations

Models and routing

Images and audio

Files and retrieval

Agents

Tools and sandbox

Evals and feedback

Compute

Repositories

Dataset generations

Organizations and access

Usage and budgets

Application utilities

Analytics

Legacy APIs

Additional APIs

Iniciar uma execução de agente salva

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta