{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2026-06-19-custom-agents/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "You can now create custom agents in Amp with plugins.\n\nYou can use these custom agents as your main Amp agent, or as subagents. You can use them as a small part of a tool pipeline that you invoke with `amp -x`. Or you can spawn 25 custom worker agents, then switch between them.\n\nEach custom agent comes with a custom orb color.\n\nHere is how you define a custom agent in an Amp plugin:\n\n```ts\n// .amp/plugins/focused-reviewer-agent.ts\nimport type { PluginAPI } from '@ampcode/plugin'\n\nexport default function (amp: PluginAPI) {\n\t// Create the agent\n\tconst reviewer = amp.createAgent({\n\t\tname: 'focused-reviewer',\n\t\tmodel: 'openai/gpt-5.5',\n\t\tinstructions: [\n\t\t\t'You are a focused code-review subagent.',\n\t\t\t'Inspect only the files and concerns named by the caller.',\n\t\t\t'Return concise findings with severity, evidence, and suggested fixes.',\n\t\t].join(' '),\n\t\ttools: 'all',\n\t\tdisplay: { label: 'reviewer', color: '#d97706' },\n\t})\n\n\t// Register a tool. This agent acts as a subagent\n\tamp.registerTool({\n\t\tname: 'focused_review',\n\t\tdescription: 'Run a focused code-review subagent.',\n\t\tinputSchema: {\n\t\t\ttype: 'object',\n\t\t\tproperties: {\n\t\t\t\trequest: { type: 'string' },\n\t\t\t},\n\t\t\trequired: ['request'],\n\t\t},\n\n\t\tasync execute(input, ctx) {\n\t\t\t// Run a one-shot agent turn\n\t\t\tconst result = await reviewer.run(input, {\n\t\t\t\tparentThreadID: ctx.thread.id,\n\t\t\t})\n\t\t\treturn result.text\n\t\t},\n\t})\n\n\t// Or register the agent as a selectable main thread mode\n\tamp.registerAgentMode({\n\t\tkey: 'focused-reviewer',\n\t\tdescription: 'Code Review Expert',\n\t\tagent: reviewer.definition,\n\t})\n}\n```\n\n## Threads\n\nOnce you have defined an agent, you can create threads:\n\n```ts\n// Spawn a new thread\nconst thread = await reviewer.createThread({\n\t// Tell the UI switch to this thread\n\tshow: true,\n})\n\n// Get an existing thread\nconst thread = amp.threads.get(input.threadID)\n```\n\nThe `Thread` object lets you interact with a thread in many different ways, and is where the real power comes in.\n\n### Send a message to a Thread\n\nAdd a new user message to a thread by calling `thread.appendUserMessage()`. The call returns as soon as Amp has accepted the message; it does not wait for inference to complete before returning.\n\n```ts\nawait thread.appendUserMessage({\n\ttype: 'user-message',\n\tcontent: 'Review the auth changes in this branch.',\n})\n```\n\n### Wait for the Agent's response\n\nWhen you do want to wait, call `waitForResponse()` on the thread. It resolves with the next assistant message after the agent finishes its turn.\n\n```ts\nconst reply = await thread.waitForResponse()\n```\n\n## Example: Spawn an async thread that responds to the main thread\n\nThese are just a few primitives provided by the Plugin API. Together, they compose into unique workflows. An example used on the Amp team: spawn an agent in an asynchronous thread, and give it the tools it needs to respond to the parent when it needs to.\n\n```ts\namp.registerTool({\n\tname: 'start_async_review',\n\tdescription: 'Start a review in a background thread.',\n\tinputSchema: { type: 'object', properties: {} },\n\tasync execute(_input, ctx) {\n\t\tconst thread = await reviewer.createThread({\n\t\t\tparentThreadID: ctx.thread.id,\n\t\t})\n\n\t\tawait thread.appendUserMessage({\n\t\t\ttype: 'user-message',\n\t\t\tcontent: [\n\t\t\t\t'Review the auth changes in this branch.',\n\t\t\t\t`When you are done, call send_to_thread with threadID ${ctx.thread.id}`,\n\t\t\t\t'and include your review in the message.',\n\t\t\t].join(' '),\n\t\t})\n\n\t\treturn `Started background review in ${thread.id}.`\n\t},\n})\n```\n\nFull documentation is [in the manual](https://ampcode.com/manual/plugin-api). Happy Hacking.\n", "authors": [], "captured_at": "2026-10-03T23:09:50.514863041+00:00", "category": "programming", "content_html": "

You can now create custom agents in Amp with plugins.

\n

You can use these custom agents as your main Amp agent, or as subagents. You can use them as a small part of a tool pipeline that you invoke with amp -x. Or you can spawn 25 custom worker agents, then switch between them.

\n

Each custom agent comes with a custom orb color.

\n

Here is how you define a custom agent in an Amp plugin:

\n
// .amp/plugins/focused-reviewer-agent.ts\nimport type { PluginAPI } from '@ampcode/plugin'\n\nexport default function (amp: PluginAPI) {\n\t// Create the agent\n\tconst reviewer = amp.createAgent({\n\t\tname: 'focused-reviewer',\n\t\tmodel: 'openai/gpt-5.5',\n\t\tinstructions: [\n\t\t\t'You are a focused code-review subagent.',\n\t\t\t'Inspect only the files and concerns named by the caller.',\n\t\t\t'Return concise findings with severity, evidence, and suggested fixes.',\n\t\t].join(' '),\n\t\ttools: 'all',\n\t\tdisplay: { label: 'reviewer', color: '#d97706' },\n\t})\n\n\t// Register a tool. This agent acts as a subagent\n\tamp.registerTool({\n\t\tname: 'focused_review',\n\t\tdescription: 'Run a focused code-review subagent.',\n\t\tinputSchema: {\n\t\t\ttype: 'object',\n\t\t\tproperties: {\n\t\t\t\trequest: { type: 'string' },\n\t\t\t},\n\t\t\trequired: ['request'],\n\t\t},\n\n\t\tasync execute(input, ctx) {\n\t\t\t// Run a one-shot agent turn\n\t\t\tconst result = await reviewer.run(input, {\n\t\t\t\tparentThreadID: ctx.thread.id,\n\t\t\t})\n\t\t\treturn result.text\n\t\t},\n\t})\n\n\t// Or register the agent as a selectable main thread mode\n\tamp.registerAgentMode({\n\t\tkey: 'focused-reviewer',\n\t\tdescription: 'Code Review Expert',\n\t\tagent: reviewer.definition,\n\t})\n}\n
\n

Threads

\n

Once you have defined an agent, you can create threads:

\n
// Spawn a new thread\nconst thread = await reviewer.createThread({\n\t// Tell the UI switch to this thread\n\tshow: true,\n})\n\n// Get an existing thread\nconst thread = amp.threads.get(input.threadID)\n
\n

The Thread object lets you interact with a thread in many different ways, and is where the real power comes in.

\n

Send a message to a Thread

\n

Add a new user message to a thread by calling thread.appendUserMessage(). The call returns as soon as Amp has accepted the message; it does not wait for inference to complete before returning.

\n
await thread.appendUserMessage({\n\ttype: 'user-message',\n\tcontent: 'Review the auth changes in this branch.',\n})\n
\n

Wait for the Agent's response

\n

When you do want to wait, call waitForResponse() on the thread. It resolves with the next assistant message after the agent finishes its turn.

\n
const reply = await thread.waitForResponse()\n
\n

Example: Spawn an async thread that responds to the main thread

\n

These are just a few primitives provided by the Plugin API. Together, they compose into unique workflows. An example used on the Amp team: spawn an agent in an asynchronous thread, and give it the tools it needs to respond to the parent when it needs to.

\n
amp.registerTool({\n\tname: 'start_async_review',\n\tdescription: 'Start a review in a background thread.',\n\tinputSchema: { type: 'object', properties: {} },\n\tasync execute(_input, ctx) {\n\t\tconst thread = await reviewer.createThread({\n\t\t\tparentThreadID: ctx.thread.id,\n\t\t})\n\n\t\tawait thread.appendUserMessage({\n\t\t\ttype: 'user-message',\n\t\t\tcontent: [\n\t\t\t\t'Review the auth changes in this branch.',\n\t\t\t\t`When you are done, call send_to_thread with threadID ${ctx.thread.id}`,\n\t\t\t\t'and include your review in the message.',\n\t\t\t].join(' '),\n\t\t})\n\n\t\treturn `Started background review in ${thread.id}.`\n\t},\n})\n
\n

Full documentation is in the manual. Happy Hacking.

\n", "content_markdown": "You can now create custom agents in Amp with plugins.\n\nYou can use these custom agents as your main Amp agent, or as subagents. You can use them as a small part of a tool pipeline that you invoke with `amp -x`. Or you can spawn 25 custom worker agents, then switch between them.\n\nEach custom agent comes with a custom orb color.\n\nHere is how you define a custom agent in an Amp plugin:\n\n```ts\n// .amp/plugins/focused-reviewer-agent.ts\nimport type { PluginAPI } from '@ampcode/plugin'\n\nexport default function (amp: PluginAPI) {\n\t// Create the agent\n\tconst reviewer = amp.createAgent({\n\t\tname: 'focused-reviewer',\n\t\tmodel: 'openai/gpt-5.5',\n\t\tinstructions: [\n\t\t\t'You are a focused code-review subagent.',\n\t\t\t'Inspect only the files and concerns named by the caller.',\n\t\t\t'Return concise findings with severity, evidence, and suggested fixes.',\n\t\t].join(' '),\n\t\ttools: 'all',\n\t\tdisplay: { label: 'reviewer', color: '#d97706' },\n\t})\n\n\t// Register a tool. This agent acts as a subagent\n\tamp.registerTool({\n\t\tname: 'focused_review',\n\t\tdescription: 'Run a focused code-review subagent.',\n\t\tinputSchema: {\n\t\t\ttype: 'object',\n\t\t\tproperties: {\n\t\t\t\trequest: { type: 'string' },\n\t\t\t},\n\t\t\trequired: ['request'],\n\t\t},\n\n\t\tasync execute(input, ctx) {\n\t\t\t// Run a one-shot agent turn\n\t\t\tconst result = await reviewer.run(input, {\n\t\t\t\tparentThreadID: ctx.thread.id,\n\t\t\t})\n\t\t\treturn result.text\n\t\t},\n\t})\n\n\t// Or register the agent as a selectable main thread mode\n\tamp.registerAgentMode({\n\t\tkey: 'focused-reviewer',\n\t\tdescription: 'Code Review Expert',\n\t\tagent: reviewer.definition,\n\t})\n}\n```\n\n## Threads\n\nOnce you have defined an agent, you can create threads:\n\n```ts\n// Spawn a new thread\nconst thread = await reviewer.createThread({\n\t// Tell the UI switch to this thread\n\tshow: true,\n})\n\n// Get an existing thread\nconst thread = amp.threads.get(input.threadID)\n```\n\nThe `Thread` object lets you interact with a thread in many different ways, and is where the real power comes in.\n\n### Send a message to a Thread\n\nAdd a new user message to a thread by calling `thread.appendUserMessage()`. The call returns as soon as Amp has accepted the message; it does not wait for inference to complete before returning.\n\n```ts\nawait thread.appendUserMessage({\n\ttype: 'user-message',\n\tcontent: 'Review the auth changes in this branch.',\n})\n```\n\n### Wait for the Agent's response\n\nWhen you do want to wait, call `waitForResponse()` on the thread. It resolves with the next assistant message after the agent finishes its turn.\n\n```ts\nconst reply = await thread.waitForResponse()\n```\n\n## Example: Spawn an async thread that responds to the main thread\n\nThese are just a few primitives provided by the Plugin API. Together, they compose into unique workflows. An example used on the Amp team: spawn an agent in an asynchronous thread, and give it the tools it needs to respond to the parent when it needs to.\n\n```ts\namp.registerTool({\n\tname: 'start_async_review',\n\tdescription: 'Start a review in a background thread.',\n\tinputSchema: { type: 'object', properties: {} },\n\tasync execute(_input, ctx) {\n\t\tconst thread = await reviewer.createThread({\n\t\t\tparentThreadID: ctx.thread.id,\n\t\t})\n\n\t\tawait thread.appendUserMessage({\n\t\t\ttype: 'user-message',\n\t\t\tcontent: [\n\t\t\t\t'Review the auth changes in this branch.',\n\t\t\t\t`When you are done, call send_to_thread with threadID ${ctx.thread.id}`,\n\t\t\t\t'and include your review in the message.',\n\t\t\t].join(' '),\n\t\t})\n\n\t\treturn `Started background review in ${thread.id}.`\n\t},\n})\n```\n\nFull documentation is [in the manual](https://ampcode.com/manual/plugin-api). Happy Hacking.\n", "dateCreated": "2026-10-03T23:09:50.514863041+00:00", "date_created": "2026-06-19T00:00:00+00:00", "date_modified": "2026-06-19T00:00:00+00:00", "date_published": "2026-06-19T00:00:00+00:00", "description": "You can now create custom agents in Amp with plugins. You can use these custom agents as your main Amp agent, or as subagents. You can use them as a small part of a tool pipeline that you invoke with amp -x. Or you can spawn 25 custom…", "external_url": "https://ampcode.com/news/custom-agents", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/ampcode-com/2026/06/2026-06-19-custom-agents.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/ampcode-com/2026/06/2026-06-19-custom-agents.md" }, "id": "urn:aggr:item:4ac359ae23fa1a7ab58227d3d98971db531ed7b1", "isBasedOn": { "@id": "https://ampcode.com/news/custom-agents" }, "mainEntity": { "@id": "https://ampcode.com/news/custom-agents", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2026-06-19-custom-agents/#webpage" }, "dateModified": "2026-06-19T00:00:00+00:00", "datePublished": "2026-06-19T00:00:00+00:00", "headline": "Custom Agents", "timeRequired": "PT3M", "url": "https://ampcode.com/news/custom-agents", "wordCount": 474 }, "name": "Archived snapshot: Custom Agents", "preview": null, "reading_minutes": 3, "replicated_at": null, "source": "ampcode-com", "source_name": "Amp News", "summary": "You can now create custom agents in Amp with plugins. You can use these custom agents as your main Amp agent, or as subagents. You can use them as a small part of a tool pipeline that you invoke with amp -x. Or you can spawn 25 custom worker agents, then switch between them. Each custom agent comes with a custom orb color. Here is how you define a custom agent in an Amp plugin: // .amp/plugins/focused-reviewer-agent.ts import type { PluginAPI } from '@ampcode/plugin' export default function (amp: PluginAPI) { // Create the agent const reviewer = amp.createAgent({ name: 'focused-reviewer', model: 'openai/gpt-5.5', instructions: [ 'You are a focused code-review subagent.', 'Inspect only the files and concerns named by the caller.', 'Return concise findings with severity, evidence, and suggested fixes.', ].join(' '), tools: 'all', display: { label: 'reviewer', color: '#d97706' }, }) // Register a tool. This agent acts as a subagent amp.registerTool({ name: 'focused_review', description: 'Run a focused code-review subagent.', inputSchema: { type: 'object', properties: { request: { type: 'string' }, }, required: ['request'], }, async execute(input, ctx) { // Run a one-shot agent turn const result = await reviewer.run(input, { parentThreadID: ctx.thread.id, }) return result.text }, }) // Or register the agent as a selectable main thread mode amp.registerAgentMode({ key: 'focused-reviewer', description: 'Code Review Expert', agent: reviewer.definition, }) } Threads Once you have defined an agent, you can create threads: // Spawn a new thread const thread = await reviewer.createThread({ // Tell the UI switch to this thread show: true, }) // Get an existing thread const thread = amp.threads.get(input.threadID) The Thread object lets you interact with a thread in many different ways, and is where the real power comes in. Send a message to a Thread Add a new user message to a thread by calling thread.appendUserMessage(). The call returns as soon as Amp has accepted the message; it does not wait for inference to complete before returning. await thread.appendUserMessage({ type: 'user-message', content: 'Review the auth changes in this branch.', }) Wait for the Agent's response When you do want to wait, call waitForResponse() on the thread. It resolves with the next assistant message after the agent finishes its turn. const reply = await thread.waitForResponse() Example: Spawn an async thread that responds to the main thread These are just a few primitives provided by the Plugin API. Together, they compose into unique workflows. An example used on the Amp team: spawn an agent in an asynchronous thread, and give it the tools it needs to respond to the parent when it needs to. amp.registerTool({ name: 'start_async_review', description: 'Start a review in a background thread.', inputSchema: { type: 'object', properties: {} }, async execute(_input, ctx) { const thread = await reviewer.createThread({ parentThreadID: ctx.thread.id, }) await thread.appendUserMessage({ type: 'user-message', content: [ 'Review the auth changes in this branch.', `When you are done, call send_to_thread with threadID ${ctx.thread.id}`, 'and include your review in the message.', ].join(' '), }) return `Started background review in ${thread.id}.` }, }) Full documentation is in the manual. Happy Hacking.", "tags": [], "temporalCoverage": "2026-10-03T23:09:50.514863041+00:00", "title": "Custom Agents", "url": "https://aggr.aymericbeaumet.com/items/ampcode-com/2026-06-19-custom-agents/", "word_count": 474 }