An Agent Skill that uses Kafka Java APIs for Oracle AI Database

In my own work, I found most coding agents weren’t generating high-quality code for Oracle AI Database’s Kafka Java API (OKafka). You can get results, but they’re not idiomatic, and miss subtleties. This is why I created the okafka-java-code oracle agent skill, based off my hand-written Kafka Java API examples.

Agent skills can greatly enhance code generation for Oracle AI Database apps, and this skill encapsulates solutions to the problems I kept hand-coding: how to authenticate with OKafka, how to use transactions, how to create topics, and how to use Oracle-specific serialization.

To install the skill, point your agents skill installer at this GitHub link:

https://github.com/anders-swanson/oracle-database-code-samples/tree/main/skills/okafka-java-code

https://github.com/anders-swanson/oracle-database-code-samples/tree/main/skills/okafka-java-code

What’s in the skill

This is a standard agent skill, with markdown references to code snippets implemented by my samples:

			
skills/okafka-java-code
├── agent-skill-okafka-java-api.md
├── agents
│   └── openai.yaml
├── references
│   ├── authentication-and-properties.md
│   ├── dependencies.md
│   ├── oson-serialization.md
│   ├── producer-consumer.md
│   ├── testing-and-troubleshooting.md
│   ├── topics-and-admin.md
│   └── transactions.md
└── SKILL.md

		

Each reference markdown file covers specific areas of OKafka Java code: initializing OKafka classes, serialization, authentication, testing, and transactional workloads.

Let’s try using the skill to generate an app

Start by installing the OKafka Java Code skill and see what you can generate.

I used the Oracle agent skill to generate an app with a transactional producer and consumer, and a Testcontainers test. The app was generated in one shot with Codex and GPT 5.5-high and is almost identical to code I’d write myself.

The generated app creates a transactional event flow around Oracle AI Database Transactional Event Queues:

TopicAdmin creates the topic through Kafka Admin with OKafka’s AdminClient.
OkafkaProperties builds base properties and adds producer or consumer settings in separate methods.
TransactionalEventProducer sends a record and writes to produced_events through producer.getDBConnection() before commitTransaction().
TransactionalEventConsumer writes consumed records through consumer.getDBConnection() and calls commitSync() only after the database work succeeds.
TransactionalEventsIT starts an Oracle AI Database Free container with Testcontainers, applies the OKafka grants, creates a topic, and verifies producer commit, producer abort, and consumer rollback behavior.

This producer method is the kind of output I wanted to nudge agent stoward:

private void publish(BusinessEvent event, boolean failAfterDatabaseWrite) throws Exception {
    producer.beginTransaction();
    try {
        producer.send(new ProducerRecord<>(topic, event.id(), event.payload())).get();
        insertProducedEvent(producer.getDBConnection(), event);
        if (failAfterDatabaseWrite) {
            throw new IllegalStateException("Simulated failure before producer commit");
        }
        producer.commitTransaction();
    } catch (InterruptedException exception) {
        Thread.currentThread().interrupt();
        abortAndRethrow(exception);
    } catch (Exception exception) {
        abortAndRethrow(exception);
    }
}

private void publish(BusinessEvent event, boolean failAfterDatabaseWrite) throws Exception {
    producer.beginTransaction();
    try {
        producer.send(new ProducerRecord<>(topic, event.id(), event.payload())).get();
        insertProducedEvent(producer.getDBConnection(), event);
        if (failAfterDatabaseWrite) {
            throw new IllegalStateException("Simulated failure before producer commit");
        }
        producer.commitTransaction();
    } catch (InterruptedException exception) {
        Thread.currentThread().interrupt();
        abortAndRethrow(exception);
    } catch (Exception exception) {
        abortAndRethrow(exception);
    }
}

You can see the transaction boundary, the Kafka send, the database write, and the abort path in one place.

An infographic illustrating the integration of Oracle AI Database and OKafka, showcasing the process of a transaction involving a Producer and a Consumer. It details actions like beginning a transaction, sending a record, committing or aborting, and the shared database connection with OKafka, along with the poll, insert, and rollback operations.

The consumer side follows the same idea:

private void persistAndCommit(ConsumerRecords<String, String> records, boolean failAfterDatabaseWrite)
        throws Exception {
    Connection connection = consumer.getDBConnection();
    try {
        for (ConsumerRecord<String, String> record : records) {
            insertConsumedEvent(connection, record);
        }
        if (failAfterDatabaseWrite) {
            throw new IllegalStateException("Simulated failure before consumer commit");
        }
        consumer.commitSync();
    } catch (Exception exception) {
        connection.rollback();
        throw exception;
    }
}

private void persistAndCommit(ConsumerRecords<String, String> records, boolean failAfterDatabaseWrite)
        throws Exception {
    Connection connection = consumer.getDBConnection();
    try {
        for (ConsumerRecord<String, String> record : records) {
            insertConsumedEvent(connection, record);
        }
        if (failAfterDatabaseWrite) {
            throw new IllegalStateException("Simulated failure before consumer commit");
        }
        consumer.commitSync();
    } catch (Exception exception) {
        connection.rollback();
        throw exception;
    }
}

The generated code preserves the important bits: database work happens on the consumer’s OKafka connection, and the offset is committed only after that work succeeds.

Testing is part of the skill

Flowchart illustrating the behavior of an app with Oracle AI Database Free, including Testcontainers, Bootstrap, and Topic components, detailing commit path, producer abort, and consumer rollback processes.

This skill includes guidance to validate with an integration test or smoke path that creates the topic, produces records, consumes records, and queries the TxEventQ backing table or related database side effect.

The generated app follows that direction. Its integration test starts gvenzl/oracle-free:23.26.1-slim-faststart, writes an ojdbc.properties file for local PLAINTEXT OKafka access, and then checks three paths:

a committed producer transaction creates the database row and can be consumed;
an aborted producer transaction leaves no produced row and no consumable record;
a failed consumer batch rolls back the database write and leaves the record available for a later successful consume.

You can run the generated app tests with mvn verify

Final Thoughts

An infographic illustrating the process of packaging corrections in an agent skill design, highlighting workflow rules, the OKafka Java code skill, and generated proof components.

The real leverage here is developing and sharing agent skills that capture the Oracle AI Database patterns your team needs. Do you have common database workflows? Common development patterns? Encapsulate them in a skill, iterate on it, and share it.

Once details are packaged, agents can operate at a higher level. You spend less time correcting boilerplate and more time designing stronger examples, testing real behavior, and building more powerful Oracle AI Database applications from a better starting point.