AI工作流

Installation

Agents API supports the same two delivery shapes used by other shared WordPress runtime packages such as Action Scheduler: install it as a normal WordPress plugin, or require it through Composer and load Composer's autoloader from the host project.

Both paths load the same agents-api.php bootstrap. The bootstrap is idempotent, so loading it through Composer and WordPress in the same request is safe.

Guideline Capabilities

When Agents API provides the wp_guideline polyfill, guideline access is scoped by explicit capabilities instead of ordinary post/private-post semantics:

• read_agent_memory
• edit_agent_memory
• read_private_agent_memory
• edit_private_agent_memory
• read_workspace_guidelines
• edit_workspace_guidelines
• promote_agent_memory

Private user-workspace memory is identified with guideline metadata, not by post_status=private alone:

• _wp_guideline_scope=private_user_workspace_memory
• _wp_guideline_user_id=<owner user id>
• _wp_guideline_workspace_id=<workspace id>

Workspace-shared guidance is identified with _wp_guideline_scope=workspace_shared_guidance and _wp_guideline_workspace_id=<workspace id>.

The substrate maps private memory reads/edits through the explicit owner metadata, so editors and administrators do not gain access merely because they can read private posts. Workspace-shared guidance reads map to the editorial threshold (edit_posts), edits map to the publishing threshold (publish_posts), and promotion from private memory to shared guidance requires the owner plus the explicit promote_agent_memory capability.

Hosts that provide their own guideline substrate can disable the polyfill with the wp_guidelines_substrate_enabled filter or register wp_guideline before Agents API does.

Minimal caller-managed usage

$result = AgentsAPI\AI\WP_Agent_Conversation_Loop::run(
	$messages,
	static function ( array $messages, array $context ): array {
		return $runner->run_turn( $messages, $context );
	},
	array(
		'max_turns'       => 4,
		'should_continue' => static function ( array $turn_result, array $context ): bool {
			return $policy->should_continue( $turn_result, $context );
		},
		'compaction_policy' => $agent->conversation_compaction_policy,
		'summarizer'         => $summarizer,
	)
);

Full usage with tool mediation, completion policy, persistence, and events

When tool_executor and tool_declarations are provided, the loop handles the tool-call → validate → execute → message assembly cycle internally. The turn runner becomes the AI request adapter only — it sends messages to the provider and returns a response with optional tool_calls:

$result = AgentsAPI\AI\WP_Agent_Conversation_Loop::run(
	$messages,
	static function ( array $messages, array $context ): array {
		// Turn runner dispatches to the AI provider and returns:
		// - 'messages': current transcript
		// - 'content': assistant text response (optional)
		// - 'tool_calls': array of {name, parameters} (optional)
		$response = $ai_client->prompt( $messages );
		return array(
			'messages'   => $messages,
			'content'    => $response->text(),
			'tool_calls' => $response->tool_calls(),
		);
	},
	array(
		'max_turns'         => 10,
		'context'           => array( 'agent_id' => 'my-agent' ),

		// Tool execution mediation (#45)
		'tool_executor'     => $my_tool_executor,      // WP_Agent_Tool_Executor
		'tool_declarations' => $available_tools,        // array keyed by tool name

		// Typed completion policy (#42)
		'completion_policy' => $my_completion_policy,   // WP_Agent_Conversation_Completion_Policy

		// Optional tool result truncation for oversized mediated results.
		'tool_result_truncator' => new AgentsAPI\AI\WP_Agent_Byte_Limit_Tool_Result_Truncator( 8192 ),

		// Optional between-turn interruption. Return a message array or null.
		'interrupt_source' => static function ( AgentsAPI\AI\WP_Agent_Conversation_Request $request ): ?array {
			return $interrupt_queue->next_message_for( $request );
		},

		// Transcript persistence (#43)
		'transcript_persister' => $my_persister,        // WP_Agent_Transcript_Persister

		// Iteration budgets (#47)
		'budgets' => array(
			new AgentsAPI\AI\WP_Agent_Iteration_Budget( 'tool_calls', 20 ),
			new AgentsAPI\AI\WP_Agent_Iteration_Budget( 'tool_calls_progress_story', 5 ),
		),

		// Lifecycle events (#44)
		'on_event' => static function ( string $event, array $payload ): void {
			// Events: turn_started, tool_call, tool_result, tool_result_truncated, interrupt_received, budget_exceeded, completed, failed
			$logger->log( $event, $payload );
		},

		// Caller-owned continuation policy; typed completion policy takes precedence.
		'should_continue' => static function ( array $result, array $context ): bool {
			return ! empty( $result['tool_execution_results'] );
		},

		// Compaction (unchanged)
		'compaction_policy' => $agent->conversation_compaction_policy,
		'summarizer'         => $summarizer,

		// Optional: pass the original request for transcript persistence context
		'request' => $conversation_request,            // WP_Agent_Conversation_Request
	)
);

All new options are opt-in. Existing callers passing only the original options continue to work identically.

When tool_result_truncator is provided, the loop asks it to normalize mediated tool results before adding them to tool_execution_results and transcript tool_result messages. WP_Agent_Byte_Limit_Tool_Result_Truncator replaces oversized JSON-encoded results with an excerpt plus byte-count metadata and emits tool_result_truncated; the event payload includes original_result for observer-owned storage, logging, or artifact capture.

When interrupt_source is provided, the loop checks it between turns with the current WP_Agent_Conversation_Request. Returning a message appends that message to the transcript and emits interrupt_received. Message metadata can set interrupt_action to message, redirect, or cancel; cancel stops the loop with status: interrupted, while message and redirect continue through the normal continuation policy.

For large ability surfaces, Agents API registers two canonical meta-abilities. agents/ability-search searches registered abilities by name, category, substring, +keyword, or select:foo/bar,baz/qux and returns compact { name, summary, required_fields } entries. agents/ability-call invokes a registered ability by name with JSON parameters, letting consumers keep lower-priority tools out of the prompt while still making them reachable through a stable discovery-and-call path.

The loop treats all adapter inputs and outputs as JSON-friendly arrays so products can map them to their own storage, streaming, audit, and transport layers without Agents API owning those layers.

Agents API

The shared foundation for building AI agents in WordPress.

If you're building a plugin that needs an AI agent — one that can hold a conversation, call tools, run workflows, remember things between sessions, or talk to users through Slack, Telegram, or email — you shouldn't have to reinvent the plumbing every time. Agents API gives you that plumbing.

It's a small, focused WordPress package maintained by Automattic. Think of it as the layer that sits underneath your product: it owns the boring-but-important parts (agent identity, runtime contracts, tool mediation, sessions, transcripts, memory, workflow scaffolding), so your plugin can focus on what makes it special.

What you get out of the box: a way to register agents, a messaging channel base class that plugs into any transport, value objects for the agent lifecycle, contracts for tools and memory and consent, and lightweight workflow plumbing (spec, validator, runner skeleton, three abilities, an optional Action Scheduler bridge).

What you don't get — and shouldn't expect: a concrete workflow runtime, durable run history, an editor UI, admin screens, or any provider-specific AI client. Those belong to your product. Agents API is the substrate, not the application.

New here? Start with the Introduction — it breaks down the core concepts and vocabulary in plain language — then browse the developer documentation.

What Agents API Owns

• Agent registration and lookup.
• Messaging channel base class (WP_Agent_Channel) that maps an external transport (Telegram, Slack, WhatsApp, Email, …) onto the Abilities-API chat surface, with shared session continuity and lifecycle hooks.
• Runtime message, request, result, and completion value objects.
• Agent execution principal/context value objects.
• Agent access grant, token, token authenticator, authorization policy, and capability ceiling contracts.
• Multi-turn orchestration contracts.
• Opt-in mediated tool result truncation for oversized transcript payloads.
• Opt-in between-turn interrupt sources for cancel, redirect, or additional instruction messages.
• Canonical chat run-control contracts for run IDs, run status, best-effort cancellation, and queued messages.
• Canonical ability discovery and dispatch meta-abilities for large tool surfaces.
• Agent package and package-artifact contracts.
• Shared wp_guideline / wp_guideline_type storage substrate polyfill when Core/Gutenberg do not provide it.
• Agent memory store contracts and value objects.
• Generic memory/context source registry, context section registry, injection policy vocabulary, and composable context value object.
• Conversation compaction policy and transcript transformation contracts.
• Generic multi-turn conversation loop sequencing around caller-owned adapters.
• Iteration budget primitives for bounded execution across configurable dimensions.
• Tool-call mediation contracts and runtime tool declaration value objects.
• Generic tool visibility policy and action policy resolver contracts.
• Conversation transcript store contracts.
• Consent policy contracts for memory, transcripts, sharing, and escalation.
• Tool source registration, parameter normalization, tool-call mediation, and execution result contracts.
• Session and persistence contracts where they are provider-neutral.
• Retrieved context authority vocabulary, context item shape, and conflict resolution contracts.
• Workflow spec value object, structural validator, in-memory registry, abstract runner with ability and agent step types, Store and Run_Recorder interfaces, optional Action Scheduler bridge, and three canonical abilities (agents/run-workflow, agents/validate-workflow, agents/describe-workflow).

What Agents API Does Not Own

• Provider-specific request code. wp-ai-client owns provider/model prompt execution.
• Concrete workflow runtimes, durable workflow / run history, scheduling adapters beyond the optional Action Scheduler bridge, workflow editor UI, and product-specific step types (branch, parallel, nested workflow). The substrate provides the contract surface; consumers ship the persistence and product UX.
• Product UI such as admin pages, settings screens, dashboards, or onboarding.
• Product CLI commands beyond generic substrate needs.
• Public REST controllers in v1 unless they are separately designed.
• Product runner adapters that assemble prompts, choose concrete tools, materialize storage, or decide product policy.
• Concrete tool execution adapters, prompt assembly policy, or product storage/materialization policy.
• Product-specific consent UX, support routing, escalation targets, or transcript-sharing policy.
• Concrete memory retrieval, file projection, convention-path writing, or filesystem layout adapters.

Products can require Agents API because they build on the substrate. Agents API must not depend on any product plugin, import product classes, mirror a product source tree, or encode product vocabulary as generic runtime API.

Core-Candidate API Naming

Agents API intentionally exposes WordPress-shaped public APIs such as wp_register_agent(), wp_get_agent(), wp_agents_api_init, and wp_agent_* hooks.

These names are not accidental plugin globals. They are the public API surface being evaluated for possible WordPress Core alignment, following existing Core naming conventions for substrate APIs. Plugin Check may report prefix warnings for these symbols; those warnings are expected for this Core-candidate package and should be reviewed in that context.

WordPress Plugin

Install and activate the Agents API plugin through the normal WordPress plugin mechanism. This is the recommended path for site owners and plugins that declare Agents API as a plugin dependency.

Consumer Integration

Product plugins should treat Agents API as an optional or required runtime dependency depending on their feature surface.

For hard requirements, declare the plugin dependency using normal WordPress/plugin-distribution mechanisms and fail clearly when Agents API is unavailable.

For optional integrations, feature-detect the public API before registering agent-backed features inside the registration hook:

add_action(
	'wp_agents_api_init',
	static function () {
		if ( function_exists( 'wp_register_agent' ) ) {
			wp_register_agent( 'example-agent', array( /* ... */ ) );
		}
	}
);

Register agent definitions from inside a wp_agents_api_init callback. Reads such as wp_get_agent() and wp_has_agent() are safe after WordPress init has fired.

Agents can declare source provenance in meta so registration diagnostics can identify which plugin or package owns a slug:

wp_register_agent(
	'example-agent',
	array(
		'label' => 'Example Agent',
		'meta'  => array(
			'source_plugin'  => 'example-plugin/example-plugin.php',
			'source_type'    => 'bundled-agent',
			'source_package' => 'example-package',
			'source_version' => '1.2.3',
		),
	)
);

Loop integration

Pass budgets to WP_Agent_Conversation_Loop::run() via the budgets option. The loop enforces them at the appropriate seams:

• turns — incremented after each turn. When an explicit WP_Agent_Iteration_Budget('turns', N) is provided, it overrides max_turns and produces a budget_exceeded status when tripped.
• tool_calls — incremented after each tool call when tool mediation is enabled.
• tool_calls_<name> — incremented per tool name for ping-pong protection (e.g. tool_calls_progress_story).

$result = AgentsAPI\AI\WP_Agent_Conversation_Loop::run(
	$messages,
	$turn_runner,
	array(
		'max_turns' => 10,
		'budgets'   => array(
			new AgentsAPI\AI\WP_Agent_Iteration_Budget( 'tool_calls', 20 ),
			new AgentsAPI\AI\WP_Agent_Iteration_Budget( 'tool_calls_progress_story', 5 ),
		),
		'tool_executor'     => $executor,
		'tool_declarations' => $tools,
	)
);

if ( ( $result['status'] ?? null ) === 'budget_exceeded' ) {
	// $result['budget'] contains the name of the exceeded budget.
	$logger->warn( 'Budget exceeded: ' . $result['budget'] );
}

When a budget trips, the loop returns early with status: 'budget_exceeded' and budget: '<name>' in the result. A budget_exceeded event is also emitted through the on_event sink with budget, current, and ceiling in the payload.

External observers tracking exotic dimensions (token cost, wall-clock, custom chain depth) can use the on_event hook to increment their own WP_Agent_Iteration_Budget instances and signal the loop through the existing should_continue or completion policy escape hatches.

The substrate ships only the per-execution value object. Registries, configuration persistence, and ceiling policies are consumer concerns.