Managed Agents

Agen adalah konfigurasi yang dapat digunakan kembali dan memiliki versi yang mendefinisikan persona dan kemampuan. Agen menggabungkan model, "system prompt" (prompt sistem), alat, server MCP, dan track yang membentuk bagaimana Haijun berperilaku selama sesi.

Buat agen sekali sebagai sumber daya yang dapat digunakan kembali dan referensikan berdasarkan ID setiap kali Anda memulai sesi. Agen memiliki versi dan lebih mudah dikelola di banyak sesi.

Field konfigurasi agen

Field	Deskripsi
`name`	Wajib. Nama agen yang mudah dibaca manusia.
`model`	Wajib. Model Haijun yang menjalankan agen. Menerima string ID model atau objek, misalnya `{"id": "haijun-opus-5"}`. Model Haijun 4.5 dan yang lebih baru didukung. Bentuk objek juga menerima field `speed`, `effort`, dan `inference_geo`; lihat tips di bawah Membuat agen, Tingkat effort, dan Menyematkan inference geo.
`system`	Prompt sistem yang mendefinisikan perilaku dan persona agen. Prompt sistem berbeda dari pesan pengguna, yang seharusnya mendeskripsikan pekerjaan yang akan dilakukan.
`tools`	Alat yang tersedia untuk agen. Menggabungkan alat agen bawaan, alat MCP, dan alat kustom.
`mcp_servers`	Server MCP yang menyediakan kemampuan pihak ketiga yang terstandar.
`tracks`	Track yang menyediakan konteks khusus domain dengan pengungkapan progresif.
`multiagent`	Deklarasi koordinator yang mencantumkan agen-agen yang dapat didelegasikan oleh agen ini. Lihat Orkestrasi multiagen.
`description`	Deskripsi tentang apa yang dilakukan agen.
`metadata`	Pasangan key-value arbitrer untuk pelacakan Anda sendiri.

Anda juga dapat menimpa model, system, tools, mcp_servers, dan tracks untuk satu sesi tanpa mengubah agen. Penimpaan model menggantikan objek model milik agen secara keseluruhan, sehingga effort milik agen tidak ikut terbawa. Untuk menjalankan sesi pada tingkat effort tertentu, atur effort di dalam objek model pada penimpaan tersebut. Lihat Menimpa konfigurasi agen untuk sesi.

Membuat agen

Contoh berikut mendefinisikan agen coding yang menggunakan Haijun Opus 5 dengan akses ke toolset agen bawaan. Toolset ini memungkinkan agen menulis kode, membaca file, mencari di web, dan lainnya. Lihat referensi alat agen untuk daftar lengkap alat yang didukung.

Contoh-contoh ini menggunakan curl, CLI ant, atau salah satu SDK. Jika Anda belum menyiapkannya, quickstart mencakup instalasi dan penyiapan klien.

bash

  agent=$(curl -fsSL https://haijun.my.id/v1/agents \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Coding Assistant",
      "model": "haijun-opus-5-5",
      "system": "You are a helpful coding agent.",
      "tools": [{"type": "agent_toolset_20260401"}]
    }')

  AGENT_ID=$(jq -r '.id' <<< "$agent")
  AGENT_VERSION=$(jq -r '.version' <<< "$agent")

bash

    ant apply coding-assistant.md

markdown

      ---
      name: Coding Assistant
      model: haijun-opus-5-5
      tools:
        - type: agent_toolset_20260401
      ---

      You are a helpful coding agent.

ant apply membuat agen dari coding-assistant.md, mencetak ID-nya, dan mencatatnya di haijun-lock.json. Commit haijun-lock.json agar ant apply berikutnya memperbarui agen ini alih-alih membuat yang kedua.

python

  agent = client.beta.agents.create(
      name="Coding Assistant",
      model="haijun-opus-5-5",
      system="You are a helpful coding agent.",
      tools=[
          {"type": "agent_toolset_20260401"},
      ],
  )

typescript

  const agent = await client.beta.agents.create({
    name: "Coding Assistant",
    model: "haijun-opus-5-5",
    system: "You are a helpful coding agent.",
    tools: [{ type: "agent_toolset_20260401" }],
  });

csharp

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Coding Assistant",
      Model = BetaManagedAgentsModel.HaijunOpus5_5,
      System = "You are a helpful coding agent.",
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = "agent_toolset_20260401",
          },
      ],
  });

  agent, err := client.Beta.Agents.New(ctx, juglow.BetaAgentNewParams{
  	Name: "Coding Assistant",
  	Model: juglow.BetaManagedAgentsModelConfigParams{
  		ID: juglow.BetaManagedAgentsModelHaijunOpus5_5,
  	},
  	System: juglow.String("You are a helpful coding agent."),
  	Tools: []juglow.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &juglow.BetaManagedAgentsAgentToolset20260401Params{
  			Type: juglow.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }

java

  var agent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Coding Assistant")
          .model(BetaManagedAgentsModel.HAIJUN_OPUS_5_5)
          .system("You are a helpful coding agent.")
          .addTool(
              BetaManagedAgentsAgentToolset20260401Params.builder()
                  .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                  .build()
          )
          .build()
  );

php

  $agent = $client->beta->agents->create(
      name: 'Coding Assistant',
      model: 'haijun-opus-5-5',
      system: 'You are a helpful coding agent.',
      tools: [
          BetaManagedAgentsAgentToolset20260401Params::with(
              type: 'agent_toolset_20260401',
          ),
      ],
  );

ruby

  agent = client.beta.agents.create(
    name: "Coding Assistant",
    model: "haijun-opus-5-5",
    system_: "You are a helpful coding agent.",
    tools: [{type: "agent_toolset_20260401"}]
  )

Respons menggemakan konfigurasi Anda dan menambahkan field id, type, version, created_at, updated_at, dan archived_at, serta mengisi field model yang Anda hilangkan, seperti effort, dengan nilai defaultnya. version dimulai dari 1 dan bertambah setiap kali pembaruan mengubah agen.

json

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "haijun-opus-5-5",
    "effort": { "type": "high" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "tracks": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

default_config pada toolset menunjukkan kebijakan izin defaultnya, always_allow, yang berlaku kecuali Anda mengonfigurasinya.

Tip: Untuk menggunakan Haijun Opus 5.5, Haijun Opus 5, atau Haijun Opus 4.8 dengan mode cepat, berikan model sebagai objek, misalnya: {"id": "haijun-opus-5", "speed": "fast"}. Lihat model yang didukung pada halaman mode cepat.

Tip: Untuk menetapkan tingkat effort model, teruskan model sebagai objek, misalnya: {"id": "haijun-opus-5", "effort": "high"}. Field effort menerima string tingkat (low, medium, high, xhigh, atau max) atau objek seperti {"type": "high"}. Lihat Tingkat effort untuk mengetahui apa yang dilakukan setiap tingkat.

Menyematkan inference geo

Seperti speed dan effort, inference_geo ditetapkan melalui bentuk objek dari model: teruskan model sebagai objek dan tetapkan inference_geo bersama id. Field ini menerima "us" atau "global". Ketika tidak ditetapkan, setiap permintaan model mengikuti inference geo default workspace pada saat permintaan dilayani. Lihat Residensi data untuk kontrol geo tingkat workspace dan harga.

Contoh berikut menyematkan agen ke inferensi AS dan mencetak nilai inference_geo dari objek model milik agen:

bash

  agent=$(curl -fsSL https://haijun.my.id/v1/agents \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Geo-pinned assistant",
      "model": {"id": "haijun-opus-5-5", "inference_geo": "us"},
      "system": "You are a helpful assistant."
    }')

  echo "Inference geo: $(jq -r '.model.inference_geo' <<< "$agent")"

bash

    ant apply geo-pinned-assistant.md

markdown

      ---
      name: Geo-pinned assistant
      model:
        id: haijun-opus-5-5
        inference_geo: us
      ---

      You are a helpful assistant.

python

  agent = client.beta.agents.create(
      name="Geo-pinned assistant",
      model={
          "id": "haijun-opus-5-5",
          "inference_geo": "us",
      },
      system="You are a helpful assistant.",
  )

  print(f"Inference geo: {agent.model.inference_geo}")

typescript

  const agent = await client.beta.agents.create({
    name: "Geo-pinned assistant",
    model: { id: "haijun-opus-5-5", inference_geo: "us" },
    system: "You are a helpful assistant.",
  });

  console.log(`Inference geo: ${agent.model.inference_geo}`);

csharp

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Geo-pinned assistant",
      Model = new BetaManagedAgentsModelConfigParams
      {
          ID = BetaManagedAgentsModel.HaijunOpus5_5,
          InferenceGeo = "us",
      },
      System = "You are a helpful assistant.",
  });

  Console.WriteLine($"Inference geo: {agent.Model.InferenceGeo}");

  agent, err := client.Beta.Agents.New(ctx, juglow.BetaAgentNewParams{
  	Name: "Geo-pinned assistant",
  	Model: juglow.BetaManagedAgentsModelConfigParams{
  		ID:           juglow.BetaManagedAgentsModelHaijunOpus5_5,
  		InferenceGeo: juglow.String("us"),
  	},
  	System: juglow.String("You are a helpful assistant."),
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("Inference geo: %s\n", agent.Model.InferenceGeo)

java

  var agent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Geo-pinned assistant")
          .model(
              BetaManagedAgentsModelConfigParams.builder()
                  .id(BetaManagedAgentsModel.HAIJUN_OPUS_5_5)
                  .inferenceGeo("us")
                  .build()
          )
          .system("You are a helpful assistant.")
          .build()
  );

  IO.println("Inference geo: " + agent.model().inferenceGeo().orElseThrow());

php

  $agent = $client->beta->agents->create(
      name: 'Geo-pinned assistant',
      model: BetaManagedAgentsModelConfigParams::with(
          id: 'haijun-opus-5-5',
          inferenceGeo: 'us',
      ),
      system: 'You are a helpful assistant.',
  );

  echo "Inference geo: {$agent->model->inferenceGeo}\n";

ruby

  agent = client.beta.agents.create(
    name: "Geo-pinned assistant",
    model: {id: "haijun-opus-5-5", inference_geo: "us"},
    system_: "You are a helpful assistant."
  )

  puts "Inference geo: #{agent.model.inference_geo}"

Penyematan inference_geo divalidasi terhadap allowed_inference_geos milik workspace ketika agen disimpan, ketika sesi dibuat darinya, dan pada setiap giliran yang dilayani sesi. Jika allowlist workspace menyempit sehingga penyematan tidak lagi diizinkan, sesi baru tidak dapat dibuat dari agen tersebut dan sesi yang sedang berjalan menolak giliran selanjutnya; penyematan tidak pernah dikecualikan, karena workspace mengandalkannya untuk kepatuhan dan residensi data.

Menetapkan inference_geo pada model yang tidak mendukung penyematan inferensi geografis mengembalikan error 400; lihat Ketersediaan model untuk model yang mendukungnya. Dalam konfigurasi multiagent, penyematan koordinator dan setiap anggota roster harus semuanya ditetapkan ke nilai yang sama atau semuanya tidak ditetapkan; lihat Orkestrasi multiagen. Untuk mengubah atau menghapus penyematan nanti, perbarui objek model agen; menyediakan model tanpa inference_geo akan menghapusnya, seperti dijelaskan di bawah Semantik pembaruan.

Memperbarui agen

Memperbarui agen menghasilkan versi baru ketika konfigurasi berubah. Field version bersifat opsional: sediakan untuk optimistic concurrency (ketidakcocokan mengembalikan 409), atau hilangkan untuk menerapkan pembaruan tanpa syarat (penulisan terakhir menang). Pembaruan pada agen yang diarsipkan ditolak.

Dengan CLI, edit file agen dan jalankan ant apply lagi; apply akan memberikan version untuk Anda.

bash

  updated_agent=$(curl -fsSL "https://haijun.my.id/v1/agents/$AGENT_ID" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "version": $AGENT_VERSION,
    "system": "You are a helpful coding agent. Always write tests."
  }
  EOF
  )

  echo "New version: $(jq -r '.version' <<< "$updated_agent")"

bash

    ant apply coding-assistant.md

markdown

      ---
      name: Coding Assistant
      model: haijun-opus-5-5
      tools:
        - type: agent_toolset_20260401
      ---

      You are a helpful coding agent. Always write tests.

python

  updated_agent = client.beta.agents.update(
      agent.id,
      version=agent.version,
      system="You are a helpful coding agent. Always write tests.",
  )

  print(f"New version: {updated_agent.version}")

typescript

  const updatedAgent = await client.beta.agents.update(agent.id, {
    version: agent.version,
    system: "You are a helpful coding agent. Always write tests.",
  });

  console.log(`New version: ${updatedAgent.version}`);

csharp

  var updatedAgent = await client.Beta.Agents.Update(agent.ID, new()
  {
      Version = agent.Version,
      System = "You are a helpful coding agent. Always write tests.",
  });

  Console.WriteLine($"New version: {updatedAgent.Version}");

  updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, juglow.BetaAgentUpdateParams{
  	Version: juglow.Int(agent.Version),
  	System:  juglow.String("You are a helpful coding agent. Always write tests."),
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("New version: %d\n", updatedAgent.Version)

java

  var updatedAgent = client.beta().agents().update(
      agent.id(),
      AgentUpdateParams.builder()
          .version(agent.version())
          .system("You are a helpful coding agent. Always write tests.")
          .build()
  );

  IO.println("New version: " + updatedAgent.version());

php

  $updatedAgent = $client->beta->agents->update(
      $agent->id,
      version: $agent->version,
      system: 'You are a helpful coding agent. Always write tests.',
  );

  echo "New version: {$updatedAgent->version}\n";

ruby

  updated_agent = client.beta.agents.update(
    agent.id,
    version: agent.version,
    system_: "You are a helpful coding agent. Always write tests."
  )

  puts "New version: #{updated_agent.version}"

Contoh sebelumnya menyediakan version dari respons pembuatan, sehingga pembaruan hanya diterapkan jika tidak ada hal lain yang mengubah agen sejak Anda membacanya. Untuk menerapkan pembaruan tanpa syarat, hilangkan version dari permintaan:

bash

  updated_agent=$(curl -fsSL "https://haijun.my.id/v1/agents/$AGENT_ID" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "description": "Writes and reviews code."
    }')

  echo "New version: $(jq -r '.version' <<< "$updated_agent")"

Semantik pembaruan

version bersifat opsional dan harus minimal 1 ketika disediakan. Ketika disediakan, permintaan mengembalikan 409 jika tidak cocok dengan versi agen saat ini, bahkan ketika field yang Anda kirim sudah cocok dengan nilai yang tersimpan; baca ulang agen dan coba lagi. Ketika dihilangkan, pembaruan diterapkan tanpa syarat dan pembaruan terbaru secara diam-diam menggantikan pembaruan bersamaan lainnya, tanpa error bagi kedua pemanggil. Menyediakan version adalah default yang direkomendasikan untuk pemanggil interaktif, dan menghilangkannya cocok untuk loop apply deklaratif, seperti job CI yang menyinkronkan definisi agen yang di-check-in, di mana loop tersebut memiliki agen.

Field yang dihilangkan dipertahankan. Anda hanya perlu menyertakan field yang ingin Anda ubah.

Field skalar (model, system, name, description) diganti dengan nilai baru. system dan description dapat dihapus dengan meneruskan null. model dan name bersifat wajib dan tidak dapat dihapus. Di dalam objek model yang Anda sediakan, effort adalah satu-satunya pengecualian: jika id model tidak berubah, menghilangkan effort membiarkan tingkat effort yang tersimpan tidak berubah. Jika Anda mengubah id model, effort yang dihilangkan direset ke default model baru. Field model lainnya diganti bersama objeknya: menyediakan model tanpa inference_geo menghapus penyematan inference geo agen.

Field array (tools, mcp_servers, tracks) diganti sepenuhnya oleh array baru. Untuk menghapus field array seluruhnya, teruskan null atau array kosong.

multiagent diganti secara keseluruhan, termasuk roster agents-nya. Teruskan null untuk menghapusnya.

Metadata digabungkan pada tingkat key. Key yang Anda sediakan ditambahkan atau diperbarui. Key yang Anda hilangkan dipertahankan. Untuk menghapus key tertentu, tetapkan nilainya ke null.

Deteksi no-op. Jika pembaruan tidak menghasilkan perubahan relatif terhadap versi saat ini, tidak ada versi baru yang dibuat dan versi yang ada dikembalikan.

Roster koordinator tidak diperbarui. Koordinator yang mereferensikan agen ini dalam roster multiagent.agents mereka tetap menggunakan versi yang disematkan ketika koordinator dibuat atau terakhir diperbarui, bahkan jika referensi tersebut menghilangkan version. Untuk mendelegasikan ke versi baru, perbarui koordinator agar rosternya mereferensikannya.

Siklus hidup agen

Operasi	Perilaku
Perbarui	Menghasilkan versi agen baru ketika konfigurasi berubah.
Daftar versi	Mengembalikan riwayat versi lengkap sehingga Anda dapat melacak perubahan dari waktu ke waktu.
Arsipkan	Membuat agen menjadi read-only. Sesi baru tidak dapat mereferensikannya, tetapi sesi yang ada terus berjalan.

Daftar versi

Ambil riwayat versi lengkap untuk melacak bagaimana agen telah berubah dari waktu ke waktu. Hasil dipaginasi, dan contoh SDK mengambil setiap halaman secara otomatis.

bash

  curl -fsSL "https://haijun.my.id/v1/agents/$AGENT_ID/versions" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01" \
    | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

bash

  ant beta:agents:versions list --agent-id "$AGENT_ID"

python

  for version in client.beta.agents.versions.list(agent.id):
      print(f"Version {version.version}: {version.updated_at.isoformat()}")

typescript

  for await (const version of client.beta.agents.versions.list(agent.id)) {
    console.log(`Version ${version.version}: ${version.updated_at}`);
  }

csharp

  var versions = await client.Beta.Agents.Versions.List(agent.ID);
  await foreach (var version in versions.Paginate())
  {
      Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}");
  }

  iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, juglow.BetaAgentVersionListParams{})
  for iter.Next() {
  	version := iter.Current()
  	fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
  }
  if err := iter.Err(); err != nil {
  	panic(err)
  }

java

  for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
      IO.println("Version " + version.version() + ": " + version.updatedAt());
  }

php

  foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
      echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n";
  }

ruby

  client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version|
    puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}"
  end

Mengarsipkan agen

Pengarsipan membuat agen menjadi read-only dan tidak dapat dibatalkan. Sesi yang ada terus berjalan, tetapi sesi baru tidak dapat mereferensikan agen tersebut. Respons menetapkan archived_at ke timestamp pengarsipan.

bash

  archived=$(curl -fsSL -X POST "https://haijun.my.id/v1/agents/$AGENT_ID/archive" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01")

  echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"

bash

  ant beta:agents archive --agent-id "$AGENT_ID"

python

  archived = client.beta.agents.archive(agent.id)

  print(f"Archived at: {archived.archived_at.isoformat()}")

typescript

  const archived = await client.beta.agents.archive(agent.id);
  console.log(`Archived at: ${archived.archived_at}`);

csharp

  var archived = await client.Beta.Agents.Archive(agent.ID);
  Console.WriteLine($"Archived at: {archived.ArchivedAt:O}");

  archived, err := client.Beta.Agents.Archive(ctx, agent.ID, juglow.BetaAgentArchiveParams{})
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339))

java

  var archived = client.beta().agents().archive(agent.id());
  IO.println("Archived at: " + archived.archivedAt().orElseThrow());

php

  $archived = $client->beta->agents->archive($agent->id);

  echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n";

ruby

  archived = client.beta.agents.archive(agent.id)
  puts "Archived at: #{archived.archived_at.iso8601}"

Langkah selanjutnya

Konfigurasikan alat yang tersedia untuk agen Anda.

Lampirkan keahlian berbasis filesystem yang dapat digunakan kembali ke agen Anda untuk alur kerja khusus domain.

Buat sesi untuk menjalankan agen Anda dan mulai mengeksekusi tugas.

Tipe event, flag CLI worker self-hosted, tipe server MCP yang didukung, batas laju, dan pedoman branding untuk Haijun Managed Agents.

#Field konfigurasi agen

#Membuat agen

#Menyematkan inference geo

#Memperbarui agen

#Semantik pembaruan

#Siklus hidup agen

#Daftar versi

#Mengarsipkan agen

#Langkah selanjutnya

Field konfigurasi agen

Membuat agen

Menyematkan inference geo

Memperbarui agen

Semantik pembaruan

Siklus hidup agen

Daftar versi

Mengarsipkan agen

Langkah selanjutnya